Some Tips and Tricks for Working with the UCompOS Framework

As I’ve experimented with some various aspects of the UCompOS framework, I have picked up on a couple of subtle nuances that I thought I’d share.

First, if you haven’t yet switched to the Flash Builder 4 Beta from Flex Builder 3, doing so is probably a good idea.  One key reason (beyond enhanced functionality) is that I have noticed a significant reduction in the sizes of exported Flash Builder 4 swf files.  For example, one artifact I had created in Flex Builder 3 was about 300 k when I exported it, but this was reduced to about 70 k once I ported it to Flash Builder.  I was surprised at the huge difference.

Speaking of Artifacts, after talking with Edward Mansouri at some length about some of the file size issues I mentioned above, and his recommendation is to use Flash CS 4 or 5 (if you’re lucky enough to be in the private beta program) for artifact development wherever possible.  Flash can get your file sizes down to roughly a tenth of what I can get them down to in Flash Builder, which is a big deal if you have a lot of artifacts in your implementation.

I want to move on a little bit and talk about developing applications using the AIR 2.0 SDK, which is the only way to take advantage of some of the AIR functionality in the UcompOS framework.  The AIR 2.0 SDK and runtime can both be downloaded from http://labs.adobe.com/downloads/air2.html (you will need both).  Once you have downloaded it, go ahead and install the runtime (which installs automatically).  However, you will need to need to do some tweaking to Flash Builder in order to install the SDK properly (I will only cover Flash Builder in this blog post).  What you need to do is find the “sdks” folder in your Flash Builder folder and open it.  It should look something like this:

pic1

What you are going to want to do next is make a copy of the 4.0.0 folder.  In my case I copied it and named it “4.0.0 AIR 2.0″

pic2

This will be the folder where we copy the files from the AIR 2.0 SDK into.  Simply open the ZIP file containing the AIR 2.0 SDK and copy and paste the files into the 4.0.0 AIR 2.0 folder.  If you are prompted, be sure to overlay any old files with the new ones from the ZIP file, or you will run into problems.

pic3

Now, you will need to configure Flash Builder to use the new SDK for applications.  To do this, open up Flash Builder, and create a new Flex project.  On the dialog that comes up, select the “Configure Flex SDKs” on the middle right of the dialog:

pic4

On the dialog that comes up, click the “Add” button, and browse to the 4.0.0 AIR 2.0 folder you created earlier:

pic5

pic6

Then, select the “Ok” button, and your dialog should look like this:

pic7

Once you’re done, click the “Apply” button, and then click “Ok”.  Then, under the “Flex SDK version” part of the dialog, select the “Use a Specific SDK” radio button, and select your new SDK from the select box.  From here on out, setting up your project is normal.  Note that unless you made your new SDK the default, you will have to manually select your SDK every time you create a new application that leverages the AIR 2.0 SDK (including UcompOS applications).

pic8

The final topic I wanted to touch on was getting your publisherID that you need to add to your application descriptor file in order to make it work with UCompOS.  The easiest way to do this is to export a release build of your AIR application and install it.  Once that’s done, you will need to browse to the location where you installed the AIR application, and browse to the “META-INF/AIR” folder.  In that folder, you will see a file called “publisherid” that contains the value that you need to set for publisherID in your AIR application descriptor file (don’t forget to set allowBrowserInvocation to true!):

pic9

I hope some of these tips help you out as you work with UcompOS.

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.