Create a translator widget both on mobile and web!

In the first tutorial, we have seen the basic rules to create a mobile widget. This tutorial will show how to make a widget both on web and mobile.
To illustrate how it is simple to create widgets and synchronize them, we will create a translator widget.

This part is just an advise to manage architecture environment. You can choose another structure.

To separate the two worlds ( Mobile/Web ), we create one folder for Web and one sub folder ( /mob ) for mobile.
For installation, you must have a network access to put all resources to an accessible server directory. Local network does not work. In this tutorial, we assume you have access to “http://yourServer.yourDomain.com/translator/”.

At the root folder, we put Web files :

• translator.xml : contains web script and the declaration to the mobile script ( ( see Widget Web ) )
• icon.png : represent the visible icon of your own page on Webwag

In the sub folder ”/mob”, we put Mobile files :

• translator.xml : contains mobile script engine ( see Widget Mobile )
• translatorBG.png : represent the background image for dashboard into application
• snapshot.png : represent the icon of your widget inside the mobile screen on the web page

We obtain this structure :

For the mobile part, we illustrate our example by using a physical handset or by using a simulator.

1. Please follow these instructions from introduction tutorial to download and install Webwag mobile on your phone or simulator.
2. Edit the translator.xml file of the web folder by copy/paste these lines. This script describe the minimum information to add a Web AND Mobile widget:

    <?xml version="1.0"?>
    <widget>
	<title>Translator</title>
	<config platform="web">
		<icon>http://yourServer.yourDomain.com/translator/icon.png</icon>
	</config>
	<config platform="mobile">
		<icon>http://yourServer.yourDomain.com/translator/mob/icon.png</icon>
		<snapshot>http://yourServer.yourDomain.com/translator/mob/snapshot.png</snapshot>
		<src>http://yourServer.yourDomain.com/translator/mob/translator.xml</src>
	</config>
	<script>
		<![CDATA[
  		]]>
	</script>
    </widget>

Note : You just have to replace path names for your own widget.
Note : Please see Web Widget part for full script description. For now, we just want to know how to install widgets. Full version describe behavior of web widget.

In this script we can see 4 parts :

• title tag : title of the web widget
• config platform=“web” tag : icon path for web widget.
• config platform=“mobile” tag :
  • icon : path to the Mobile screen icon
  • snapshot : path to the Web discovery icon
  • src : path to the Mobile script
• script tag : Web widget behaviour

Once you have your structure stored on a web server, you can install widgets.

1. Go to http://www.webwag.com and connect you to your account by clicking on the signIn icon on top right of the screen,
2. Click on Add Content icon on the top left screen and choose External Widget entry,
3. Enter the URL of the Web widget you just created into the Add a widget window and click on the webwag button below,
4. The web widget is created if exist.
5. For the Mobile, we can have two behavior :
   1. It will be saved directly to your Mobile screen account if no Web config exist. You can see it by clicking on the large Mobile icon on top left screen,
   2. Else no Mobile widget is added to the Mobile Screen. In that case, you must click on phone icon in top bar of the web widget.
6. When you will start your mobile application on your handset or on simulator, your account will be synchronized. So your widget will appears. If no account is set, please go to Menu/Account/Settings to your.

All this procedure has been done just one time for installation. For further update, you just have to use console.

Once application has been loaded, you can activate the debug console into your simulator or your handset by typing “999”. You will see all the command available as below :

• '999' to display pending errors,
• '990' to display current settings,
• '991' to display current widget (elements+properties),
• '992' to display widgets'scripts outputs (println),
• '993' to display last synchro details (sent and received),
• '994' to display network requests,
• '995' to display memory usage,
• '996' to force a garbage collection (clean memory ⇒ displayed result = real memory consumed by application),
• '997' to force current widget's code to be downloaded and reloaded.

Each time you want to see some informations, type the appropriate code to display them.

Let's start by create the mobile widget of our translator. The mobile version is quite simple.

On the dashboard, we will have the translatorBG.png image and by clicking on it, we open the second level materialized by a view element. In this view, we will have four lines ( text element ) and an image element. By clicking on the image, we will open a form to enter the word or sentence to translate. Clicking on the “translate” softKey will send a request to a dedicated server and the answer will be displayed in the previous view.

Note : softkeys are special keys usually located at bottom of a phone's screen, on left and right. They're often used on phones for actions such as “Ok”, “Select”, “Back”, “Cancel”, …

To do this, we just have to edit the translator.xml file from mobile folder ( /mob/translator.xml ). Keep in mind that a widget is composed of two parts :

• The declaration part : declare all elements you need. It is all lines before script tag,
• The script part : widget behavior. All lines inside script tags.

<widget name="translator" width="29" height="33" version="1.0" about="Translate a word or sentence from english to french!" >

    <image name="translatorBG" x="0" y="0" src="translatorBG.png" />
	
    <view name="translatorView" mode="full" bgColor="#E0F4B0" >
	<text name="text_label" x="6" y="5" data="Search:" color="0x000000" />
	<text name="text_src" x="6" y="25" data="" color="0x0000FF" />
	<text name="translatedtext_label" x="6" y="50" data="Answer:" color="0x000000" />
	<text name="translatedtext_src" x="6" y="70" data="" color="0xFF0000" />
	<image name="buttonEdit" x="6" y="100" src="buttonEdit.png" selectable="true" onselected="translate()" />
    </view>

    <form name="translatorForm" title="Translator" softKeyOk="Translate" >
        <input name="question" type="text" label="Search:" value="" />
    </form>

• The first line define widget's caracteristics. The most important informations are the name and size( width and height ). Size is used to display correctly the selector of widget.
• The second line define the first element we need, the background image representing our widget on the dashboard. Note : the path to find resource is always relative to the current widget.
• The third line define a view element ( see developer's documentation on view ) where full background will be painted with hexadecimal color 0xE0F4B0
  • On this view, 4 texts will be added with appropriate coordonate, size and color,
  • and a selectable image. By clicking on it, the translate() function will be called.
• The last element is a form ( see form and input tag ) which represent the edit box. We just have one item question with type text.

<script><![CDATA[

//-----------------------------------------------------------------------------
function onSelected( state ){

    if ( state == "true" ){
		showView( "translatorView" );
    }
}


//-----------------------------------------------------------------------------
function translate(){

	showView( "translatorForm" );
}


//-----------------------------------------------------------------------------
function onFormValidated( formName, command ){

    if ( formName == "translatorForm" ){

        if ( command == "Translate" ){
			translatorView.text_src.data = translatorForm.question.value;
			translationId = XMLHttpRequest( "http://www.google.fr/translate_a/t?client=ig&sl=en&tl=fr&text=" + translatorForm.question.value );
        }
    }
}


//-----------------------------------------------------------------------------
function onUrlFetched( id, inValue, code ){

	if ( id == translationId ){

		if ( code != 200 ){
			translatorView.translatedtext_src.data = "Error";
		}
		else{

			if ( inValue != "" ){
				translatorView.translatedtext_src.data = inValue;
			}
		}
	}
}


//-----------------------------------------------------------------------------
// Main
//-----------------------------------------------------------------------------
var translationId = -1;

]]>
</script>
</widget>

• The first function onSelected is called when we click on the widget from dashboard. This one display the view element. A state is done ( value true or false ) when enter or leave the second level.
• The second function translate is called when you click on the “buttonEdit” image. This function open the form element.
• The third function onFormValidated is called when you click on softKey inside a form element. In our case, we test if it is the right form ( we can have many! ) and the right softKey.
  

Note : by default a form has two softKey ( Ok and Cancel ). In our example, we change Ok softKey by label Translate in declaration part.
So if user click on the right softKey, a request is sent to the server we choose for translation : http://www.google.fr/translate_a/t?client=ig&sl=en&tl=fr&text=.

• The fourth function onUrlFetched is called when you the answer to the request sent before arrived. If the requete is correct, we analyse it.
  

Note : We have seen in the previous tutorial ( see Parsing an xml ) how to parse an XML request. In our example, we don't receive answer under XML format, so we don't need to use method xml_evaluate.

• The Main part is analysed when the application start.

In this part, we will see how to make a widget Web. This tutorial doesn't discribe the JavaScript language but only the structure need to edit a widget inside Webwag environment. So for more informations about JavaScript Framework used in Webwag, please see this documentation : Prototype API.

The Web version is quite simple too !

We want to make a widget as simple as possible. To do this, we choose to display three parts :

• An area to enter text
• An area to receive answer
• A button to launch translation

That's all !!

As on Mobile, we just have to edit the translator.xml file from web folder ( /translator.xml ).
We already seen in Installation -> preparation the first part of the web widget to manage installation. In this part, we will see the part missing.

Just to remember :

<?xml version="1.0"?>
<widget>
	<title>Translator</title>
	<config platform="web">
		<icon>http://yourServer.yourDomain.com/translator/icon.png</icon>
	</config>
	<config platform="mobile">
		<icon>http://yourServer.yourDomain.com/translator/mob/icon.png</icon>
		<snapshot>http://yourServer.yourDomain.com/translator/mob/snapshot.png</snapshot>
		<src>http://yourServer.yourDomain.com/translator/mob/translator.xml</src>
	</config>

Here is the missing part.

	<content>
		<![CDATA[
  		]]>
	</content>
	<style>
		<![CDATA[
			.answerBox {
				padding:5px;
				margin:5px;
				background-color:#eee;
				height:20px;
			}
		]]>
	</style>
	<script>
		<![CDATA[

			////////////////////////////////
			// define widget's methods
			////////////////////////////////

			widget.displaySearch = function() {

				var output = "";
				output += 	"<textarea id=\""+widget.id+"_text\" name=\""+widget.id+"_text\" rows=\"2\" cols=\"40\">";
				output += 	"</textarea><br/>";
				output += 	"<div class=\"answerBox\" id=\""+widget.id+"_translatedText\">";
				output += 	"</div>";
				output += 	"<input type=\"button\" value=\"Translate\" onclick=\"widget.translate();\"><br/>";

				widget.setContent(output);
			};

			widget.translate = function() {
				widget.setAnswerText("Translating...");
				var searchText	= $(widget.id+"_text");
				var value		= searchText.value.replace(/\s/g, "+");
				var url			= "http://www.google.fr/translate_a/t?client=ig&sl=en&tl=fr&text=" + value;
				widget.request(url, widget.receive);
			};
			
			widget.setAnswerText = function(text) {
				var translatedTextElem = $(widget.id+"_translatedText");
				translatedTextElem.innerHTML = text;
			};
			
			widget.receive = function(request) {
				widget.setAnswerText(request.responseText);
			};

			////////////////////////////////
			// define widget's events
			////////////////////////////////

			widget.onLoad = function() {
				widget.displaySearch();
			};
			
  		]]>
	</script>
	<prefs>
	</prefs>
</widget>

Three main tags :

• content tag : you can put there any element you want to display before the onLoad function be run. Ex: <div>Translator is loading…</div>
• style tag : edit all your CSS styles to be used in script tag
• script tag : the heart of the widget. Two main category :
  • The events section : many functions exist. The most important are : onLoad, onSave, onRefresh, onUpdate. At start, engine will read the onLoad function.
  • The method function : behavior of the widget is described here.

You can right-click on each image to get them.

• buttonEdit.png :
• snapshot.png :
• translatorBG.png :

• icon.png :

- End of the document -