In-Depth Coverage of the UcompOS Menu Bar

The menu bar feature on the UcompOS Portal can be customized in a number of different ways.  This article will discuss the basics of the UcompOS menu bar, and also provide a look at some of the features that have been recently added to the menu bar including support for keyboard shortcuts.

Attaching a Menu Bar to a UcompOS Application

The common paradigm of using the menu bar is to have a custom menu bar implementation appear while a particular UcompOS application is in focus.

There are two ways to go about doing this.

The first is to attach an XML model for the menu bar to the particular UcompOS application’s manifest file.

Below is an example of a simple menu bar model that would be placed in the UcompOS application manifest file as a child of the root application element.

	<menu>
		<menuitem label="File">
			<menuitem label="Open"/>
			<menuitem label="Close"/>
			<menuitem label="Quit"/>
		</menuitem>
		<menuitem label="Edit">
			<menuitem label="Copy"/>
			<menuitem label="Paste"/>
		</menuitem>
	</menu>

You can also add a custom menu bar implementation to a UcompOS application at run-time.

This is accomplished using the UcompOSMenuBarProxy class that is built into the UcompOS SDK.

UcompOSMenuBarProxy is a Singleton, meaning it is instantiated via a static method.

It offers a setMenuBar() method that accepts a parameter model of type XML (String in the JavaScript SDK).

Below is a simple example of the UcompOSMenuBarProxy‘s setMenuBar() method at work:

var menuBarModel:XML = new XML("<menu><menuitem label='File'><menuitem label='Open' data='open'/><menuitem label='Close' data='close'/></menuitem></menu>");
UcompOSMenuBarProxy.getInstance().setMenuBar(menuBarModel);

If you have done any coding in Flex and added your own XML dataProvider to a Flex MenuBar implementation, the above example should look familiar.  The XML data model we are using is based on the model that is used inside of Flex.

The Base UcompOS Menu Item

By default, UcompOS Portal implementations will have a base menu bar item that is perpetually viewable throughout the user’s session.  This is analogous to the Mac OS X Operating System’s menu bar implementation that has a base menu bar item on the left of the menu bar represented by Apple’s trademark logo.

BaseMenuBar

The base menu bar option is shown above.

Overriding the Base Menu Item

You can replace the built-in UcompOS menu bar item with your own custom implementation in one of two ways.

One such way is by adding a baseMenu element to one of your UcompOS application’s manifest files.

Below is an example of this:

<baseMenu>
	<menuitem label="Company X">
		<menuitem label="About Our Company" data="about"/>
	</menuitem>
</baseMenu>

This would replace the base UcompOS menu bar item with an option labeled “Company X” that has an “About Our Company” sub option.

Below is an example of the custom base menu bar for the Educator 2 software I am building on top of the UcompOS RPF:

Educator2MenuBar

The other way would be to use the UcompOSMenuBarProxy class and to override the base menu item at run-time.

The second parameter of the UcompOSMenuBarProxy‘s setMenuBar() method is an optional Boolean property named baseMenu that defaults to false.

When you pass in a true value for this parameter, the menu bar model you pass to setMenuBar() will become the base menu item.

There can only be one base menu item at a time throughout your entire UcompOS implementation.  If UcompOS Application A sets the base menu item, then UcompOS Application B sets the base menu item later, it will override the base menu item set by UcompOS Application A.

It is planned at some point that the UcompOS Dock Manifest will indicate which UcompOS Applications have the privilege of setting the base menu item which could be an important consideration in large collaborative development environments.

Sharing a Menu Bar Across Multiple UcompOS Applications

In some implementations, you may want one menu bar implementation to be used across multiple applications.

To do this, you would declare one of your applications as the default application.  This is accomplished in one of two ways: in the Dock Manifest by passing a default=”true” attribute to an <application/> element, or at run time with the UcompOSGlobalManagerProxy‘s isDefaultApplication property.

When a default application is set on the UcompOS Portal, then any UcompOS Applications that have the following menu bar models:

	<menu default="true"/>

will use the Menu Bar implementation that is assigned to the application that has been declared as the default application.

As a note of caution, only one application can be declared as the default at a time on the UcompOS Portal.  If you try to declare an application as the default while another application has already been defined as the default, a run-time error will occur.  This is by design, and you must set the isDefaultApplication property of the UcompOSGlobalManagerProxy to false before you can set it to true for another application.

As is the case with setting base menu items, I am considering setting it up at the Dock Manifest level such that it is articulated ahead of time which applications can declare themselves as the default.

Menu Bar Icons

The model for the UcompOS menu bar supports the icon attribute for menuitem elements.  The value of the icon attribute should be the full URL to an image of type GIF, JPG, or PNG.

You can use any sized icon but it is recommended you use an icon sized at 18×18.

Below is an example of a menu bar implementation with icons:

MenuBarIcons

Menu Bar Separators

In the image above, notice there is a separator between the “Delete” and “Close” options.

This is accomplished with the following menuitem element:

	<menuitem type="separator"/>

Window-Specific Menu Bars

In some UcompOS applications, you may spawn many different UcompOS windows and load a variety of different sub-applications into each window instance.

Each window instance may need their own unique menu bar implementation.

The UcompOSWindowProxy class offers a setMenuBar() method that allows you to attach a custom menu bar implementation to individual UcompOS Window instances.

The menu bar will come into view whenever the window it is attached to comes into focus.  When the window closes, the menu bar will return to the existing menu bar implementation attached to the UcompOS application in focus.

Menu Bar Events

Obviously, if you go through the trouble of implementing a custom menu bar, you want to know when the user has selected an option on the menu bar.

When an item is selected on the menu bar, an event of type UcompOSMenuBarProxy.ITEM_CLICK is dispatched to any listening UcompOSMenuBarProxy instances.

A strict protocol that must be recognized is that only menuitem elements that have a data property will dispatch a UcompOSMenuBarProxy.ITEM_CLICK event.

Let’s look at a very simple code-based example:

package
{
 
	import com.ucompass.ucompos.sdk.proxycomponents.UcompOSMenuBarProxy;
	import com.ucompass.ucompos.sdk.events.SDKEvent;
	import com.ucompass.ucompos.sdk.SDKClient;
 
	public class MenuBarExample extends Sprite
	{
 
		public function MenuBarExample()
		{
			var menuBarModel:XML = new XML("<menu><menuitem label='File'><menuitem label='Select Me' data='testData'/></menuitem></menu>");
			SDKClient.getInstance(this);
			UcompOSMenuBarProxy.getInstance().setMenuBar(menuBarModel);
			UcompOSMenuBarProxy.getInstance().addEventListener(UcompOSMenuBarProxy.ITEM_CLICK,eventHandler);
		}
 
		private function eventHandler(event:SDKEvent):void
		{
			trace("The user said "+event.data.label);
			trace("The associaed data is "+event.data.data);
		}
 
	}
 
 
}

UcompOSMenuBarProxy.ITEM_CLICK events are only dispatched to UcompOS entities in the scope of the UcompOS application in focus when the menu item was selected.  So if UcompOS Application B has implemented a custom menu bar, and UcompOS Application A is in focus, no menu events will be dispatched to UcompOS Application B.

Keyboard Shortcut Commands

In applications where you load a lot of functionality onto the menu bar, keyboard shortcut commands can be a very convenient feature for your users, and, perhaps as importantly, they can help your applications address important accessibility standards crucial for many public-use applications.

To add a keyboard shortcut command to a menu item, you use the shortcutKey attribute to the menuitem element in a menu bar model.

For instance:

	<menu>
		<menuitem label="File">
			<menuitem label="Print" data="print" shortcutKey="ALT-P"/>
		</menuitem>
	</menu>

In the above example, when the user presses the ALT key and the P key simultaneously, the action that will take place will be exactly the same as if the user would have chosen the Print option with the mouse.

Below is an example of a similar implementation from Educator 2:

PrintOption

Overriding the UcompOS Default MenuBar Item

The Menu Bar on the UcompOS Portal by default has a built-in menu item as displayed below:

DefaultMenuItem

You can override this default Menu Bar item in one of two ways.

First, in the application manifest for a particular application, you can specify the model for the Menu Bar that should be present when the application is in focus.

A sample Menu Bar model for a very simple File Management application may look something like this:

<menu>
	<menuitem label="File">
		<menuitem label="Open" data="open"/>
		<menuitem label="Close" data="close"/>
		<menuitem label="Quit" icon="http://apps.ucompass.com/exit.png" data="quit"/>
	</menuitem>
</menu>

As a relevant aside, the UcompOSWindowProxy has a setMenuBar(); method that accepts an XML object as input of the same form shown above. This lets you specify the model for the Menu Bar that should be in display while a particular window is in focus.

So you can have multiple windows spawned by the same UcompOS application all with different Menu Bar implementations. This is a very important capability.

What if you want to override the default UcompOS menu item and have 100% unique branding.

You can do this by building a baseMenu model into the application manifest.

For instance, my Educator 2 Menu Bar default Menu Bar item looks like this:

Educator2DefaultMenuItem

Here is the relevant code from my Application Manifest that articulates the base menu item:

<baseMenu>
	<menuitem label="" icon="http://applications.ucompass.com/Educator2PortalFoundation/images/Educator2_Menu_Bar_Icon.png">
		<menuitem label="About Educator 2" data="About Educator 2"/>
		<menuitem type="separator"/>
		<menuitem label="Logout" data="Logout" />
	</menuitem>
</baseMenu>

The setMenuBar(); method of the UcompOSMenuBarProxy class also has a second Boolean parameter named baseMenu. When you set a Menu Bar and pass true as the value for this parameter, that model will override the default UcompOS MenuBar implementation.

Overriding the default UcompOS MenuBar is just one of many ways to create a 100% unique and customized experience for users of your Rich Portal Application.

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

Meet the UcompOS Portal Proxy Components

If you’ve read my previous postings, you should now have a basic understanding of some of the core mechanics of the UcompOS Rich Productivity Framework including Proxy Components and Services Dictionaries.

The concept of the UcompOS Continuum should also be somewhat clearer now as well as the roles of the UcompOS Portal and the UcompOS SDK in the context of the UcompOS Continuum.

Despite the obvious significance of the UcompOS Portal, in the context of the UcompOS Continuum, it is just another entity with the UcompOS SDK implemented that publishes a Services Dictionary of public API methods exposed for other entities.

To take advantage of this fact, the UcompOS SDK has a host of Proxy Components built into it that can be thought of as client interfaces to the public API methods exposed by the UcompOS Portal.

Understanding the mechanics of building your own UcompOS public API methods and Proxy Components to those public API methods is the key to unleashing the true power of the UcompOS RPF and creating the most compelling rich experiences for users of your Rich Portal Application.

But even a basic exploration of the SDK’s built-in UcompOS Portal Proxy Components is a fun way to explore and learn.

In this post, I’ll introduce you briefly to the UcompOS Portal Proxy Components.  I won’t spend a lot of time detailing them as you’ll likely see some dedicated blog postings from me covering the individual Proxy Components and their nuances in the coming weeks.

Each Proxy Component covered is built into all 3 UcompOS SDKs – AIR, Flex/Flash, and JavaScript.

The implementation details of using the AIR and Flash/Flex (ActionScript 3.0) Proxy Components versus the JavaScript Proxy Components are very subtle and of course full SDK documentation is online for the ActionScript 3.0 SDK as well as the JavaScript SDK.

Since the SDK documentation is online, I won’t spend a lot of time covering the methods, properties, and events of the Proxy Components (as you can get all this information in the docs), rather I’ll just give a first-person synopsis of what you can do with each of the Proxy Components.

UcompOSAIRProxy

The UcompOSAIRProxy class allows you to create a virtual representation of a UcompOS AIR application in an entity.  Once you create this virtual representation, you then use this class’s launchApplication(); and quitApplication(); method to control the start and stop of the AIR application.  Then any communication with the AIR application is handled via the traditional means of Proxy Components and public API methods.  The UcompOSAIRProxy class would be used when you wanted to launch a UcompOS AIR application as a sub-application.  If the UcompOS AIR application was to be a base application, you would just have the network URL to the air package in the application manifest and the AIR application would be launchable from the UcompOS application dock.  See my tutorial entitled A Simple HTML Digital Camera Browser for an example of this.

UcompOSArtifactContainerProxy

The UcompOSArtifactContainerProxy class lets you create a container for UcompOS Artifacts on the UcompOS Portal.  A UcompOS Artifact is essentially a “widget” that can be an image or SWF application that can have functionality attached to it (drag and drop, double click, click, rollover, context menu, etc.).

A UcompOS Artifact Container then is a visual layout container for these artifacts.  I gave an example of this in my tutorial entitled Building a UcompOS Weather Channel Widget.

An example may be a taskbar.  Suppose I want to layout a number of widgets each with its own specific functionality attached to it along the bottom right corner of my UcompOS Portal interface.

To do this I could create a UcompOS Artifact Container via the UcompOSArtifactContainerProxy class.  Then when I create my UcompOS Artifact, I would pass a reference to my UcompOSArtifactContainerProxy instance and the artifact would be placed into the relevant container.

There are 3 layout options at present with the UcompOS Artifact Container: HBox, VBox, and Tile

These are parallel to the classes of the same name in the mx.containers package from the Flex 3 framework (FYI the UcompOS Portal is built on Flex 4).

UcompOSArtifactProxy

The UcompOSArtifactProxy is a class used to create UcompOS Artifacts on the UcompOS Portal.

A UcompOS Artifact can be thought of as a widget.  The widget can be purely presentational, or it can have functionality attached to it as my Weather Channel Widget example demonstrated.

The visual content of a UcompOS Artifact can articulated as one of three forms:

  1. The network URL to an image (PNG, GIF, JPG)
  2. The network URL to a SWF appication
  3. A ByteArray representation of an image

You then attach functionality to a UcompOS Artifact by calling the UcompOSArtifactProxy‘s many public methods and attaching various event listeners to it to handle click, double click, rollover, rollout, drag and drop, and other various events.

If the visual content of your artifact is a SWF, this SWF can be a UcompOS sub-application for even more exciting interactive possibilities.

At this point, HTML-type applications cannot be used as artifacts

As described above in my discussion of the UcompOSArtifactContainerProxy class, you can add a UcompOS Artifact to a container so that groups of similar artifacts can be arranged together in a logical presentation.

One cool thing you can do, if you don’t add an artifact to a container and just position it at specified coordinates on the UcompOS Portal, you can make it draggable.  And because you can configure artifacts to accept drops, the ability to drag and drop one artifact to another to create some desired behavior or functionality exists.

I’ll likely devote a tutorial to this interesting capability in the near future.

UcompOSBrowserWindowProxy

The UcompOSBrowserWindowProxy class lets you launch a satellite browser window from the UcompOS Portal.  You can add generic content to the browser window, or you can load a UcompOS sub-application.

The ability to communicate with a UcompOS sub-application loaded in a satellite browser window is the exact same as if the sub-application was loaded in the UcompOS Portal run-time, in a UcompOS Window, or in a UcompOS Artifact.

UcompOSDockProxy

The UcompOSDockProxy class lets you exert control over the UcompOS Portal’s Application Dock.

You can do things such as set context menus to the application icon an entity is associated with.  You can also change the size of the icons on the dock as well as control the “genie” effect (the effect where the dock icons expand and then contract as the mouse passes over them).

You can also hide the dock completely using the showDock(visible:Boolean):void; method.

And one of the more important capabilities is you can set an alert for the icon on the dock an entity is associated with using the setAlert(); method.  This would be useful perhaps in e-mail or instant messaging applications to alert the user of receipt of a new e-mail or instant message.

UcompOSGlobalManagerProxy

The UcompOSGlobalManagerProxy class provides an interface to a number of important visual and data features  of the UcompOS Portal.

For instance, if you wanted the UcompOS Portal to throw a generic Flex-style Alert, you could use the createAlert(); method.

If you wanted to dispatch an event to all entities in the UcompOS Continuum, you could use the dispatchContinuumEvent(); method.

Suppose you wanted to launch another UcompOS application from within an entity.  You could call the launchApplication(); method and pass the manifest URL of the target application’s application manifest.

These are only a few of the important duties the UcompOSGlobalManagerProxy facilitates.

UcompOSHTMLProxy

The UcompOS Portal is a Flex 4 application embedded in an HTML wrapper.

The UcompOSHTMLProxy class lets you call JavaScript functions in the HTML wrapper.

The class provides the alert();, confirm(); and prompt(); methods which invoke the JavaScript functionality of the same name.

You can then add event listeners such as UcompOSHTMLProxy.CONFIRM_SUBMIT and UcompOSHTMLProxy.PROMPT_SUBMIT to capture user-input.

You can also use the javascript(); method to pass pure JavaScript code.

So one possibility here, in the ucompos/local/LocalLib.js JavaScript file in the UcompOS Developers Package that you customize to create your own authentication, you can implement your own JavaScript methods that perform specific tasks and then access these methods from the UcompOSHTMLProxy.

UcompOSMenuBarProxy

The UcompOSMenuBarProxy lets you set the dataProvider for the UcompOS Menu Bar and your particular menu bar implementation comes into view when the UcompOS application associated with the entity that set the menu bar model comes into focus.

You can even associated a menu bar model with an individual UcompOS Window instance.

You then attach event listeners to capture user menu selections.

Two cool random quick points is that you can pass a baseMenu=true value to the second parameter of the setMenuBar(); method and it will remove the default UcompOS menu bar item so you can 100% customize the menu.  Also, in your dataProvider to the menu you can attach an icon property with the network URL of images you want to use for the individual menu bar nodes.

UcompOSStyleProxy

The UcompOSStyleProxy class lets you take control over the portal’s visual presentation including the background image (wallpaper) that appears on the UcompOS portal.

With the setTheme(); method, you can set the MDI window theme to one of 3 different pre-existing window themes.  Right now, I just have the 3 that come packaged with the flexlib.mdi package implemented (Windows XP, Mac OS 9, and the default style) but it is my intention to expand this.

There is also a setEffects(); method that let you control the visual effects that occur when UcompOS Windows are closed or minimized/maximized.  The options are Default, Linear, and Vista which are the effects built into the flexlib.mdi package.

There is also a generic setStyle(); method that lets you set a generic CSS style property to the UcompOS Portal.

One important point about this method.  When you call setStyle();, the UcompOS Portal dispatches a UcompOS Continuum Event – meaning that all entities get notified about the style change.

So if you did something like this:

UcompOSStyleProxy.getInstance().setStyle("Button","color",0xFF0000);

Every entity would be notified that the Button selector’s color property was just given a red value on the UcompOS Portal.

You could then listen for this UcompOSStyleProxy.STYLE_CHANGE event and change the visual presentation of an entity’s internal controls accordingly.

UcompOSWindowProxy

The UcompOSWindowProxy class is used to create MDI window instances on the UcompOS Portal and then load generic web content or a UcompOS sub-application into them.

The class documentation is definitely worth a look as there are a lot of really cool features you can employ with UcompOS Window instances.

So that’s it.  A brief look at all the UcompOS Portal Proxy Components built into the UcompOS SDK.

I invite you to view the source code of the the JavaScript SDK and you can check the UcompOS Flash/Flex SDK written in ActionScript 3 out of the UcompOS SVN Repository.  Viewing this code will give you some better ideas of how to construct Proxy Components.

I have not yet made the source code of the UcompOS Portal publicly viewable and do not have a timeline for doing so but if you have questions about how I have built the public API methods on the UcompOS Portal, please bring questions to me in the UcompOS Forum and I’ll share relevant strategies and code examples.