DictionaryForMIDs - the free dictionary for cell phones and PDAs

DictionaryForMIDs WebApp development:
Creating a HTML/Javascript/CSS user interface based on the WebApp Translation Layer

Overview

For a general overview of the DictionaryForMIDs architecture, see here.

All the functionality from the Translation Layer and the Data Access Layer is available as Javascript in the WebApp Translation Layer. And we have a 'mini_hmi' which demonstrates the use of the interface to the WebApp Translation Layer.

For a WebApp you will also need to develop Javascript code as part of your HTML !

Remark: Several different HTML user interfaces may be developed. For example one HTML user interface that is optimized for mobile devices with small screens. And one which looks better on large screens. Or maybe an HTML user interface with a specific look or user philiosophy. Or {put your ideas here}.

Interface to the Javascript Translation Layer

The interface to the Data Access Layer is mostly the same as documented for the Java interface. With the following specialities:

The dictionary URL selects exactly one dictionary. There is no need to call TranslationExecution.loadDictionary()/unloadDictionary(). Instead the dictionary that is identified by the dictionary URL is internally loaded by the WebApp Translation Layer. The loaded dictionary is made available at the global object called dictionary. Note: 'global' refers to the windows object. The dictionary object is located at windows.dictionary.
The function TranslationExecution.executeTranslation takes two extra parameters as callback functions. These callback functions provide the same functionality as the in the Java interface TranslationExecutionCallback.

Preparation

Nothing to do: all initialisation is already done by the startup code of the WebApp Translation Layer.

Loading a dictionary

Nothing to do: see above, the dictionary that is selected by the dictionary URL is automatically loaded by the startup code of the WebApp Translation Layer.

Executing a translation

TranslationParameters are created with TranslationExecution.newTranslationParameters. For a description of the parameters see also the description of the Java interface.

var translationParameters = 
    TranslationExecution.newTranslationParameters(dictionary,                  // Type DictionaryDataFile: dictionary for translation
                                                  toBeTranslatedWordTextInput, // Type string: word/expression that shall be translated
                                                  inputLanguages,              // Type Array of boolean, size window.dictionary.numberOfAvailableLanguages
                                                  outputLanguages,             // Type Array of boolean, size window.dictionary.numberOfAvailableLanguages
                                                  executeInBackground,         // Type boolean: this parameter is currently ignored
                                                  maxHits,                     // Type integer: maximum number of translation results 
                                                  durationForCancelSearch)     // Type integer: maximum duration of search in milliseconds

Note: the parameter executeInBackground is currently ignored. The Javascript Translation Layer currently does not support background execution; this feature will be implemented in a future update with web workers.

The translation is executed with TranslationExecution.executeTranslation:

TranslationExecution.executeTranslation(translationParameters,
                                        deletePreviousTranslationResult,
                                        newTranslationResult);

The translation result is provided via a callback to the following 2 functions (see the description of the Java interface for more information):

function newTranslationResult(resultOfTranslation) 
function deletePreviousTranslationResult()

For a description of the parameter resultOfTranslation you can look at TranslationResult.java or see the file mini_hmi.html. Or ask for information in the DictionaryForMIDs forum.

A dictionary's properties

Please read the information about the data structures from DictionaryDataFile in the description of the Java interface.

The relevant information of the data structures from DictionaryDataFile is also available to Javascript in the dictionary object. In Javascript use statements such as

	var displayText = dictionary.supportedLanguages[0].languageDisplayText;

This will assign to the variable displayText the display text of the first language, e.g. "English".

Displaying log information

You can override the default implementation to provide your own implementation for UtilJs.outputMessage:

UtilJs.outputMessage = function(message) { /* do some output, e.g. in alert window */ }

The parameter message is a String-parameter that carries log information to UtilJs.outputMessage. By default the log level is set to the minimum, so only errors will be logged to outputMessage. The default implementation of UtilJs.outputMessage is to log the message on the console.

You can change the log level with the function UtilJs.setLogLevel:

UtilJs.setLogLevel(newLogLevel)

newLogLevel is an integer value. See for Util.java for details.

You may make logging outputs with UtilJs.log:

UtilJs.log(String logMessage, int logLevelOutput)

Also here, see for Util.java for details.

Background information: accessing data structures that are not yet available to Javascript (normally you will not need to do this, so you can skip this paragraph):

Just for completeness of documentation: in the unlikely case that you would need to access from Javascript a data structure from the Translation Layer that is not already available in the dictionary object, then things become a little harder: in order to access fields of a data structure, you woould need to follow the syntax of Google Web Toolkit for Accessing Java Fields from JavaScript. The Google Web Toolkit description is here: http://code.google.com/intl/de/webtoolkit/doc/latest/DevGuideCodingBasicsJSNI.html#methods-fields. The 'Javascript access code' will look like

	numberOfAvailableLanguages = @de.kugihan.dictionaryformids.dataaccess.DictionaryDataFile::numberOfAvailableLanguages;

That is clearly where we will provide support. Just make a posting in the DictionaryForMIDs forum ! Then we can implement the 'Javascript access code' that handles the access of the Java Fields.

Initialization in the HTML file

1. Including the Javascript files for the Translation Layer

Put in your HTML <head> the following line:

    <script type="text/javascript" src="../../Apps/DfMTranslationLayer/DfMTranslationLayer.js"></script>

This will include the Javascript files of the Translation Layer and also perform the necessary initilization of the Translation Layer (e.g. reading of the file DictionaryForMIDs.properties).

The files from the WebApp Translation Layer can be downloaded from the SVN repository: https://sourceforge.net/p/dictionarymid/code/HEAD/tree/trunk/WebApp/Apps/DfMTranslationLayer/

The directory structure needs to be as in this example:

WebApp/dictionaries/dictionary EngChi (CEDICT)/			
WebApp/dictionaries/dictionary EngLat (IDP)/
WebApp/Apps/DfMTranslationLayer
WebApp/Apps/your_user_interface/your_user_interface.html
WebApp/Apps/your_user_interface/any_other_files

Currently under there is the 'mini_hmi':

WebApp/Apps/mini_hmi/mini_hmi.html

On the sourceforge file server there is the file index.php in each of these directories. This index.php does currently load mini_hmi.php which loads the mini_hmi from http://dictionarymid.sourceforge.net/WebApp/Apps/mini_hmi/mini_hmi.html

Besides: on the sourceforge file server there is the file DfMTranslationLayer.js located here: http://dictionarymid.sourceforge.net/WebApp/AppsDfMTranslationLayer/DfMTranslationLayer.js

2. Referencing the cache manifest

Your <html> tag must include the manifest attribute:

<html manifest="cache_your_user_interface.manifest">

The file cache_your_user_interface.manifest lists all those files that will be put in the "application cache" (= files that are available without internet connection). The file cache_your_user_interface.manifest should be built analogous to the file cache_mini_hmi.manifest.

The file cache_your_user_interface.manifest needs to be put into each of the dictionaries. Just drop a message in our forum to get this done, because this is done by central maintenance.

In total there are a few files that need to be put into each of the dictionaries, see here. These files are maintained centrally, so you do not have to bother with that.

Local Testing of the WebApp without an HTTP server

For testing the WebApp you can use an HTTP server such as Jetty. Also without an HTTP server you can test the WebApp, here shown for the mini_hmi (you can replace mini_hmi with your_user_interface):

Establish the following directories:

Apps/mini_hmi                              -- here put the HMI html, js, css files 
Apps/DfMTranslationLayer                   -- here copy the file DfMTranslationLayer.js
Apps/mini_hmi/dictionary                   -- described below

For Apps/mini_hmi/dictionary copy a test dictionary locally. Pick any dictionary that you would like to use for testing purpose from here. Download and unzip the zip-file. Then unzip the jar-file. Copy the directory dictionary to mini_hmi. So you will have:

Apps/mini_hmi/dictionary/  -- here reside the index files, directory files etc.

For Chrome users: you need to start Chrome from the command line with the parameter allow-file-access-from-files (you must terminate all Chrome windows first):

chrome --allow-file-access-from-files

Note that any HTML, Javascript or CSS files you use must be prefixed with "../../Apps/mini_hmi". For example:

	<script type="text/javascript" src="../../Apps/mini_hmi/mini_hmi.js"> </script>

Reason: the 'current directory' is WebApp/dictionaries/dictionary_xyz,this is where the dictionary URL points to. The directory with the HTML, Javascript or CSS files is WebApp/Apps/mini_hmi. From WebApp/dictionaries/dictionary_xyz to WebApp/Apps/mini_hmi you get with ../../Apps/mini_hmi.

Deployment of the WebApp on the Sourceforge web server

The WebApp directory is located at /home/project-web/dictionarymid/htdocs/WebApp. Copy the WebApp files to the subdirectory WebApp/Apps/your_user_interface.

Other hints

If you intend to create an option dialogue where the user can enter input language etc., then you may want to have a look at the Java ME class de.kugihan.dictionaryformids.hmi_java_me.DictionarySettingForm. Or at the Android implementation.

Icons and support for various languages

For the existing implementations (JavaME, Android) there are already icons and user interface translations to numerous languages. Possibly the icons and translations can be reused for the Web App.

Do you need support on how to use the Javascript Translation Layer ?

No problem - we will provide help to you ! Just make a posting in our DictionaryForMIDs forum !

DictionaryForMIDs WebApp development: Creating a HTML/Javascript/CSS user interface based on the WebApp Translation Layer