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.


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:


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:


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:


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:


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();

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:


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();
_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.

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();

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.


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

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

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.