Building a Multilingual UcompOS Implementation

The UcompOS Rich Productivity Framework is designed to make it easy to serve localized Rich Portal Application implementations.

In this tutorial, we are going to explore the localization capabilities of the UcompOS RPF and look at some strategies for leveraging these capabilities.

I have created a Video that I encourage you to view that shows the implementation we are going to build in this tutorial in action, and you should also Download the source code that we build in this application so you can better follow along with it.

As is the case with most of our UcompOS tutorials, we are going to focus much less on aesthetics and presentation and more on the highlighting of core UcompOS fundamentals and mechanics.

In addition to highlighting the localization capabilities of the UcompOS RPF, we are also going to touch on a number of other useful and important topics including some advanced capabilities of UcompOS Application Manifest files as well as working with the UcompOSStyleProxy class which manages the aesthetic presentation of the UcompOS Portal.

In addition, we are going to learn more about the UcompOS Menu Bar, and also about the concept of declaring default UcompOS Background Applications.

Our Target Implementation

The implementation we want to build will involve a UcompOS application that opens some simple content in a UcompOS Window.  The content will internally be configured to display some simple text that can be automatically translated on the fly to another language using Yahoo’s BabelFish free translation API.

We will set up the application such that the user can switch the operating language using a “language chooser” we’ll build into the UcompOS Menu Bar.

We will also create graphical artifacts that provide a customized experience to the end user when they switch between languages.

The languages we’ll allow users to choose from will be:

  • English
  • Spanish
  • German
  • French
  • Italian

Two UcompOS Applications Involved

Our implementation will involve the construction of two UcompOS Applications.  One we will consider the Controller for our implementation, and another we will consider the View.

Both our applications will be UcompOS HTML applications that will leverage the UcompOS JavaScript SDK.

We are going to put all assets and code related to our implementation in a single folder named Multilingual.  Inside the Multilingual folder are controller and view subfolders with the pertinent assets and code in each folder.

Implementation Specifics

Let’s talk a little bit more about exactly how we want our implementation to behave.

We want to place a language chooser on the UcompOS Menu Bar that lets the user switch between languages.

We want this Menu Bar to be perpetually on the UcompOS Menu Bar even when our View application is in focus.

Our Dock Manifest

Let’s take a look at our Dock Manifest and discuss some of its more important aspects:

<applications>
<application background="true" default="true">

http://desktop.ucompass.com/Multilingual/controller/manifest.xml

</application>
<application>

http://desktop.ucompass.com/Multilingual/view/manifest.xml

</application>
</applications>

Obviously, the first UcompOS Application listed in our Dock Manifest is our Controller application and the second is our View application.

A very important point to discuss are the two attributes set for our Controller application, specifically background=”true” and default=”true”.

When you declare a UcompOS Application as a background application, that means it is to be launched immediately upon authentication to the UcompOS Portal and it is to not be presented on the UcompOS Application Dock.

The code is simply loaded in the UcompOS run-time immediately and remains available for interaction throughout the session.

Setting an application as the default has implications on the UcompOS Menu Bar – the Menu Bar of the application declared as the default application is the Menu Bar that shows when no application is in focus.

The best analogy to this is to consider the Finder application in Mac OS X.  The Finder’s Menu Bar shows up in Mac OS X when no other application is open.  Also, if you click the Mac OS X desktop on the wallpaper (not on an artifact from a running application), the Menu Bar of the Finder is what is displayed.

This is paralleled in the UcompOS RPF by designating an application with the default=”true” attribute in the Dock Manifest.

If no application is configured with the default=”true” attribute, then the base, default UcompOS Menu Bar is displayed when no application is in focus.

Also, if you try to configure a Dock Manifest with more than one application specified as the default, you’ll encounter a run-time error from the UcompOS Portal.

Also, in an individual application’s Application Manifest, you can instruct the UcompOS Portal to use the default Menu Bar.  We’ll look at this shortly as this will be how we configure our View application.

The Controller Application Manifest

Let’s take a look at the Application Manifest for our Controller:

<application>

 <source>
 <base>http://desktop.ucompass.com/Multilingual/controller/Controller.html</base>
 </source>

 <menu>
 <menuitem label="Language">
 <menuitem label="English" icon="http://desktop.ucompass.com/Multilingual/view/images/icons/en_US_menubar.png" data="en_US"/>
 <menuitem label="Spanish" icon="http://desktop.ucompass.com/Multilingual/view/images/icons/es_ES_menubar.png" data="es_ES"/>
 <menuitem label="German" icon="http://desktop.ucompass.com/Multilingual/view/images/icons/de_DE_menubar.png" data="de_DE"/>
 <menuitem label="French" icon="http://desktop.ucompass.com/Multilingual/view/images/icons/fr_FR_menubar.png" data="fr_FR"/>
 <menuitem label="Italian" icon="http://desktop.ucompass.com/Multilingual/view/images/icons/it_IT_menubar.png" data="it_IT"/>
 </menuitem>
 </menu>

</application>

As you can see our Controller Application Manifest is very simple but its chief critical responsibility is to furnish a Menu Bar implementation for the UcompOS Portal.

Since our Controller Application is configured as the default application in our Dock Manifest, its Menu Bar will be what displays when no other application is in focus.

The XML structure for the Menu Bar is very simple and straightforward.  Notice the icon property points to the network URL of an icon image to be displayed on the Menu Bar.  Also, a data property must be present in a Menu Bar node for an event to be dispatched to the applications and sub-applications the Menu Bar is associated with when the user chooses a Menu Bar option on the UcompOS Portal.

Our Menu Bar configures a Language Chooser on the UcompOS Menu Bar and lets the end-user choose between one of five different languages.

The View Application Manifest

Now let’s take a look at the View application’s Application Manifest:

<application selfLoading="true" width="500" height="500" x="100" y="100">

 <source>
 <base>http://desktop.ucompass.com/Multilingual/view/View.html</base>
 </source>

 <titles>
 <title locale="en_US">A Multilingual Application</title>
 <title locale="es_ES">Un uso multilingue</title>
 <title locale="de_DE">Eine mehrsprachige Anwendung</title>
 <title locale="fr_FR">Une application multilingue</title>
 <title locale="it_IT">Un'applicazione multilingue</title>
 </titles>

 <icons>
 <icon locale="en_US">http://desktop.ucompass.com/Multilingual/view/images/icons/en_US_dock.png</icon>
 <icon locale="es_ES">http://desktop.ucompass.com/Multilingual/view/images/icons/es_ES_dock.png</icon>
 <icon locale="de_DE">http://desktop.ucompass.com/Multilingual/view/images/icons/de_DE_dock.png</icon>
 <icon locale="fr_FR">http://desktop.ucompass.com/Multilingual/view/images/icons/fr_FR_dock.png</icon>
 <icon locale="it_IT">http://desktop.ucompass.com/Multilingual/view/images/icons/it_IT_dock.png</icon>
 </icons>

 <toolTips>
 <toolTip locale="en_US">See a UcompOS Application translate text into English</toolTip>
 <toolTip locale="es_ES">Vea un uso de UcompOS traducir el texto a inglés</toolTip>
 <toolTip locale="de_DE">Sehen Sie eine UcompOS Anwendung, Text ins Englische zu übersetzen</toolTip>
 <toolTip locale="fr_FR">Voir l'application d'UcompOS traduire le texte en anglais</toolTip>
 <toolTip locale="it_IT">Vedi un'applicazione di UcompOS tradurre il testo in inglese</toolTip>
 </toolTips>

 <menu default="true"/>

</application>

The first thing to notice about the Application Manifest above is the strategy employed for localizing Application titles, icons, and tool tips.

The Application Title shows up on the UcompOS Application Dock for a particular application as well as any UcompOS Windows that are spawned by the application.  The same applies to Application Icons.

Tool tips show up when the user mouses over an application icon on the UcompOS Application Dock and the mouse hovers for a second.

Notice how the locale attributes in this manifest match up to the data attributes for the menu bar model in our Controller manifest.

Another important thing to take note of is the <menu default=”true”/> element in the manifest.

This tells the UcompOS Portal that when this application is in focus, still use the UcompOS Portal’s default Menu Bar which will be the Menu Bar of our Controller Application.

Also, note the selfLoading=”true” attribute as well as the width, height, x, and y attributes in our manifest’s root <application/> element.

This tells the UcompOS Portal to launch the application into a UcompOS Window instance versus simply loading it into the UcompOS run-time.

Preparing the Graphics

The next task in building our implementation will be to prepare the graphic assets we’ll use.

In this implementation, I want our application icon to automatically update on the UcompOS Dock and UcompOS Window instances spawned by our application to reflect the most recently selected language.  So I’ll need five different application dock icons – one for each language.

Then on the UcompOS Menu Bar, we will add a “language chooser” utility.  I want each node in the language chooser, which will represent a different language, to have an icon representative of the given language.  So I’ll need five different menu bar icons – one for each language.

Finally, each time a new language is selected, I want the background wallpaper for my UcompOS Portal implementation to display an image representative of the chosen language.

I have created a folder named images in my Multilingual project’s view folder and in the images folder I’ve created two more folders:  icons and backgrounds.  I am placing the dock and menu bar icons in the icons folder and the background images in the backgrounds folder.

The Controller Source Code

As you can see in our Controller‘s Application Manifest, it points to the following network URL as the location for the application’s source code:

http://desktop.ucompass.com/Multilingual/controller/Controller.html

Let’s take a look at this application’s source code below and discuss it:

<html>
<head>
<title>Multilingual Controller</title>

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

<script type="text/javascript">

 var m;
 var g;
 var s;

 function start()
 {
 m = new UcompOSMenuBarProxy();
 g = new UcompOSGlobalManagerProxy();
 s = new UcompOSStyleProxy();

 m.addEventListener(m.CHANGE,menuChangeHandler);
 }

 function menuChangeHandler(menuData)
 {
 g.changeLanguage(menuData.data);
 s.setBackgroundImage("http://desktop.ucompass.com/Multilingual/view/images/backgrounds/"+menuData.data+".jpg");
 }

</script>

</head>
</html>

The first thing to notice is since this is an HTML application, we have the UcompOS JavaScript SDK installed.

Our start(); method employs a class we haven’t looked at yet in any of our tutorials, UcompOSMenuBarProxy, which manages and handles events dispatched by the Menu Bar on the UcompOS Portal.

In this case, we are added an event handler to handle CHANGE events.

In addition to the UcompOSMenuBarProxy, we are also working with the UcompOSGlobalManagerProxy and UcompOSStyleProxy classes in this application.

In this application, when we receive notification that the user has selected a new option on the Menu Bar, we access the newly selected language as the data property of the menuData Object passed to the event handler by the UcompOS SDK.

We then take that value and pass it to the changeLanguage(); method of the UcompOSGlobalManagerProxy.  This method configures the operating language on the UcompOS Portal with the newly chosen language string.  Whenever the UcompOS Portal’s operating language changes, a UcompOS Continuum Event is dispatched meaning that every running application and sub-application in the UcompOS Continuum is notified instantly.  This detail will be important to us when we look at our View application.

We also call the setBackgroundImage(); of the UcompOSStyleProxy and pass it the URL of a background image that is representative of the newly selected language.  This method sets the wallpaper image for the UcompOS Portal.

The View Source Code

As we saw in our View application’s Application Manifest, the source code of our View application is reachable at a network URL of:

http://desktop.ucompass.com/Multilingual/view/View.html

In the View application, we are starting with a string of text embedded in an HTML DIV element that is in the English language.

In our start(); method, we are creating an instance of the UcompOSGlobalManagerProxy class and calling its getSessionInfo(); method.  We are also attaching an event listener for events of type UcompOSGlobalManagerProxy.SESSION_INFO.

The getSessionInfo(); method the UcompOS Global Manager Proxy is extremely important.  It returns an Object with a number of important properties including the unique user Id that the current user is authenticated into the UcompOS Portal with.

Also, it returns the current language the UcompOS Portal is operating in in a property called language.

The exact implementation details regarding doing the actual language translation are outside the scope of the UcompOS RPF but I’ll explain them briefly.

We are using a web-based service called Enrich which provides an API to the Yahoo BabelFish free online language translation service to convert our content from one language to another.

One other UcompOS-related detail in our implementation is we are creating a UcompOSWindowProxy instance and setting its self property to true.

This lets us access the methods and properties of the UcompOS Window that the application we are operating in has been loaded into.

Once the user changes to a new language, we are then calling the UcompOSWindowProxy‘s setTitle(); method to update the title on the UcompOS Window in real-time.

Let’s take a look at the full source code of our View application below:

<html>
<head
<title>Multilngual Application</title>

<style type="text/css">

 body
 {
 font-family: Helvetica, Arial;
 font-size: 12px;
 }

 #title
 {
 font-size: 24px;
 background-color: #2677B6;
 color: #FFFFFF;
 font-weight: bold;
 text-align: center;
 padding: 2px;
 }

</style>

<script type="text/javascript" src="http://pilotfish.ucompass.com/gofish"></script>
<script type="text/javascript" src="/UcompOSSDK.js"></script>

<script type="text/javascript">

 var currentLanguage = 'en_US';
 var g;
 var thisWindow;
 var languageReference = {en_US:'English',es_ES:'Spanish',fr_FR:'French',de_DE:'German',it_IT:'Italian'};

 function start()
 {
 thisWindow = new UcompOSWindowProxy();
 thisWindow.self = true;
 g = new UcompOSGlobalManagerProxy();
 g.addEventListener(g.LANGUAGE_CHANGE,changeLanguage);
 g.addEventListener(g.SESSION_INFO,init);
 g.getSessionInfo();
 }

 function init(sdkData)
 {
 var c = setInterval(function () { if(callWebService) { clearInterval(c); changeLanguage(sdkData); } },100);
 }

 function changeLanguage(sdkData)
 {
 var query = new Object();
 query['feature'] = 'Search';
 query['module'] = 'Translate';
 query['sourceLanguage'] = currentLanguage;
 query['targetLanguage'] = sdkData.language;
 query['selectedText'] = document.getElementById('content').innerHTML;
 query['handler'] = 'changeLanguage_handler';
 callWebService(query);
 currentLanguage = sdkData.language;
 }

 function changeLanguage_handler(xmlObject)
 {
 document.getElementById('content').style.visibility = 'visible';
 document.getElementById('content').innerHTML = getTextNode(getXPath(xmlObject,"//translation")[0]);
 document.getElementById('title').innerHTML = languageReference[currentLanguage];
 thisWindow.setTitle(languageReference[currentLanguage]+" Window Title");
 }

</script>

</head>

<div id="title"></div>

<p/>

<div id="content" style="visibility: hidden;">
 As the name implies, an air mass is a mass of air that has
 relatively uniform characteristics with respect to temperature,
 and moisture. Air masses are often characterized by both their
 temperatures and their humidities. Air masses can basically be
 classified as warm or cold with respect to temperature and moist
 or dry with respect to humidity. The characteristics of an air
 mass are determined by the region over which it formed. For
 instance, during the winter, when the nights are long and frigid
 over the Polar regions, the air tends to become relatively
 uniform. A very cold and dry air mass develops. Occasionally,
 pieces of these air masses will break free and be transported by
 the jet stream.
</div>

<body>
</body>
</html>

Big Picture Conclusions

By isolating the language chooser into its own application, we are able to take advantage of the concept of UcompOS Continuum Events.  In our implementation, when the user changes their operating language, the UcompOSGlobalManagerProxy‘s changeLanguage(); method is invoked, which causes a UcompOS Continuum Event to be dispatched.

Therefore, we could have an unlimited number of UcompOS applications or sub-applications running, all of which employed their own custom logic and behavior when encountering a single language change event that originated in our Controller application.

Screen Capture

Below is a look at our implementation in operation:

Demo

Building a UcompOS Weather Channel Widget

In this tutorial posting we are going to look at several advanced features of the UcompOS Rich Productivity Framework.

You’ll want to download the source of the example application at the link below so you can follow along and there is also a video tutorial that goes along with this tutorial posting.

Download the Weather Widget Example Source Code

We will be building a small UcompOS application that attaches a Current Weather Conditions Widget to a UcompOS Portal implementation.  The source of the weather data will be The Weather Channel’s API Service.

We are going to look at a number of different UcompOS Rich Productivity Framework concepts in this tutorial including:

  • Working with both the UcompOS JavaScript and Flash SDK
  • Creating UcompOS background applications
  • Working with both UcompOS Artifacts and UcompOS Artifact Containers
  • Working with the UcompOS HTML Proxy

Let’s first start by looking at the application and exploring its functionality.  Then we’ll dissect the implementation carefully and explain exactly how everything was set up.

Below is a screen capture showing our simple implementation.

Demo

We can see a transparent bar on the bottom of the UcompOS Portal.  To the far right, we see a little weather icon with a temperature reading on top of it.

The transparent bar is actually a UcompOS Artifact Container and the weather widget is a UcompOS Artifact instance.

When I right click on the temperature reading, we see a context menu as shown below:

ContextMenu

We’ll look at how this weather widget was constructed as a UcompOS application.

First, let’s look at the Weather Widget itself which is a simple ActionScript 3 Flash CS5 application.

This tutorial assumes you have at least a basic command of the ActionScript 3 programming language so we will not study the construction of the weather widget itself in too much detail, but will rather focus on some of the key aspects of it as they pertain to creating a UcompOS Rich Productivity experience.

The main .fla file for our widget is named weather.fla.

As you can see below, its main document class is a class named Weather and the Flash movie itself is a small square of dimensions 25 pixels x 25 pixels.  Below is a look at the set up of our Flash movie:

FlashSetup

Next, let’s look in my Flash movie’s File > ActionScript Settings > Library Path location in my weather.fla file and we’ll see we have implemented our UcompOSSDK.swc file which is the UcompOS Flash SDK:

SWCSetup

Now let’s take a look at the main Weather class and see how it works.

Let’s first take a moment to reflect on what we want our Flash application to do.

We want our Flash movie to display an icon that displays the current weather conditions and then overlaid on top of that image we want the current temperature to display.

We also want our Flash movie to have a Context Menu associated with it that will let users access certain extended functionality like the ability to change to a new location to retrieve current weather conditions for.

First, in our constructor function for our Weather class, we are going to instantiate the UcompOS SDK by calling the static getInstance() method of the SDKClient class and passing it a self-reference:

SDKClient.getInstance(this);

Next, we’ll create the Loader that will house the image that will display the current weather conditions and add it to the stage:

_loader = new Loader();
 
addChild(_loader);

Now comes a key step.  We are going to create a UcompOSArtifactProxy instance and we will set its self property to true:

_artifact = new UcompOSArtifactProxy();
 
_artifact.self = true;

The Flash movie we are building here is going to be added to the UcompOS Portal as a UcompOS Artifact.  By setting the self property to true, we can manipulate the widget on the UcompOS Portal from within the widget itself.

Now, we are going to add an event listener to handle selections the user makes to items on the Context Menu that we’ll eventually add to the widget:

_artifact.addEventListener(UcompOSArtifactProxy.MENU_ITEM_SELECT,contextMenu_handler);

Next, I’ll create an instance of a TemperatureReport class.  Let’s see what the TemperatureReport class is.

Back in our weather.fla Flash movie, we have a movie clip in the Library named TemperatureReport that is associated with a class of the same name (TemperatureReport).  The movie clip has on its main timeline a simple TextField with the instance name of _textField.

In our TemperatureReport class, we have a public setter function, set temperature, that accepts a value of type String and sets the value as the text property on our _textField instance.

Now, back in our main Weather class, we’ll add the TemperatureReport instance to the stage and position it at (0,5):

_temperatureReport = new TemperatureReport();
addChild(_temperatureReport);
_temperatureReport.y = 5
_temperatureReport.x = 0;

Next we are going to create an instance of the UcompOSHTMLProxy class:

_html = new UcompOSHTMLProxy();

Finally, we will call our private getWeather(); method.

A full discussion of the Weather Channel API is well outside the scope of this tutorial.  In our application, we are using an API to a service called Enrich to access the Weather Channel API.  The API to Enrich is installed in the UcompOS SDK in a class called EnrichComm but again, the implementation details of how we are actually retrieving the weather data in use here is irrelevant.

The specifications for our application are we want to be able to pass a zip code to indicate our location.  The Weather Channel API has a public method that translates a zip code into a weather station identifier.

Once we have our weather station identifier, we can then call the Weather Channel API and request the current weather and pass our station identifier.

The Weather Channel API will return an XML representation of the current weather and our handler will pick out the key values we are interested in using E4X (EcmaScript for XML).

We are interested in the current temperature, the icon that represents the current weather, and the actual official city name that our zip code is associated with.

Now, we will call the load() method on our Loader instance and pass the URL of the current weather icon and we are going to set the temperature property on our TemperatureReport instance to display the current temperature.

Next, we are going to create an XML model for the Context Menu that we want to appear on our weather widget that will let the user change to a different location, open the detailed current weather conditions for the location, or see the 10-day forecast for the location.

We will then pass our XML model to the setContextMenu(); method of our UcompOS Artifact instance.  Since we set the self property of our UcompOSArtifactProxy instance to true, any methods we call on our artifact instance will be applied to the widget itself.

When the user selects an option on the context menu of the widget, the handler invoked is
the contextMenu_handler method.

Artifact context menu handlers are returned an SDKEvent by the UcompOSSDK.  The SDKEvent objects data property is an Object with a label property and this label property is the value of the label on the context menu item the user selected.

We are going to employ a simple switch / case block to handle 3 different scenarios.

Scenario 1 is a change of location where we will call the prompt method of our UcompOSHTMLProxy instance and attach an event listener for the PROMPT_SUBMIT event.

Scenario 2 is the 10-day forecast which we will open up in a UcompOS Window and load the web site on the Weather Channel of the current location in scope.

And Scenario 3, the default in our switch / case block is the detailed local weather conditions for our current location in scope which we will also display in a UcompOS Window.

Going back to Scenario 1 for a moment, the prompt method of the UcompOSHTMLProxy actually causes the UcompOS Portal’s HTML Wrapper to dispatch a call to the JavaScript prompt() command and displays the text passed to it.

The value the user enters into the Prompt dialogue is returned to our event handler which in our case is a private method named newLocation_handler and the value the user entered is contained in the response property of the SDKEvevt object’s data property.

So we now have finished building our widget.

We are now ready to set up the application that will attach the widget to the UcompOS Portal as
a UcompOS Artifact.

We are going to build a simple HTML UcompOS application to accomplish this.  Our HTML application is the file Weather_Widget.html in our example package’s html folder.

We will insert the the UcompOS JavaScript SDK into our application.

In any UcompOS HTML application, any method named start(); is used as the initialization code for the application.

In our start(); method, we are first going to create an instance of UcompOSArtifactContainerProxy and then call its add() method.

We will make it a container of type “HBox” meaning we want the artifacts placed in it to be laid out horizontally.  The second parameter of the add(); method is an Array of style objects where each object has a styleProp and a newValue property.

We want the container positioned along the entire bottom portion of my UcompOS Portal and to do this we’ll set the bottom, right, and left styles to the values you see here.
Container

We have an image that we want displayed as the background image for the container that is at the URL you see indicated above.

Then, we are going to create an instance of UcompOSArtifactProxy and call its add(); method.

var artifact = new UcompOSArtifactProxy();
artifact.add(null,"http://desktop.ucompass.com/Weather_Widget/flash/weather.swf",0,0,false,true,{},container,true);

The URL of our artifact will be the URL of the Weather Widget we created earlier which of course is a SWF file.

A couple key things to point out about our artifact.  First, the sandbox parameter is set to true.

We want the Flash content that constitutes our widget to be sandboxed as we don’t have any need for it to participate in drag and drop activity with other flash content loaded into our portal implementation.

Also, notice for the container parameter of the artifact we are passing a reference to our UcompOSArtifactContainer we created.  This tells the UcompOS Portal to load the artifact into the specified artifact container.

Now, we’re ready to create a simple application manifest for our application.

Here is our manifest and the source code for the application will be the HTML application we just created.

ApplicationManifest

Finally, we’ll create our Dock Manifest for our UcompOS Portal implementation.

The <application/> tag here points to the manifest of our UcompOS application.
Manifest


A very important point to make here is that we have the background=”true” attribute set on our application tag.  What this is saying is immediately launch the application as a background process.  This causes the application to execute as soon as the user logs into the UcompOS Portal but the application is not placed on the application dock.

The UcompOS Portal can launch as many background processes as you need it to.