The Application Manifest Format

The fundamental building block in a UcompOS application is a simple file called the Application Manifest.

Each application will have an Application Manifest that is housed at a unique network URL.  In my post yesterday on Dock Manifest files I demonstrated that the UcompOS Portal is fed a simple XML file that contains a list of Application Manifest URLs.

The Application Manifest is then a configuration file for a UcompOS Application.

The XML format employed for Application Manifest files is very simple and I do have an XSD in development that will eventually be used to validate against.

I’d like to take a look at a sample Application Manifest file and then walk through it and discuss it.  I’ll use a manifest file that I used in one of the UcompOS Video Tutorials I’ve produced.

Application Manifest file

Application Manifest file

At left is an example Application Manifest File for a Hello World UcompOS Application.  Click on the image for a closer inspection.

First, let’s take a look at the root <application/> tag.

By default, a UcompOS application will be a non-visual entity and opened into the UcompOS run-time.

In a typical implementation, you could think of a UcompOS Application as the Controller and Model and sub-applications that the application launches as the View to create an MVC (Model-View-Controller) type of approach.

You can however open an Application into a UcompOS Window immediately upon the application being launched by adding the selfLoading=’true’ attribute to the root tag.  When this attribute is set, you must also set attributes for width and height and (optionally) x and y to size and position the UcompOS Window that the application is loaded into.  If you then add the newWindow=’true’ attribute in addition, then the application will launch in a UcompOS Browser Window (a separate browser window) versus a UcompOS (MDI type) window inside the UcompOS Portal.

The next element is the <source/> element.  The purpose of this element is to provide the network address of the application’s source, as well as to articulate any parameters that should be passed to the content.

The <base/> child of the <source/> element points at the URL of the application’s source.  Note this URL should NOT have query parameters.

Query parameters must be passed to the URL by way of the <params/> element and its <param/> child elements.

For instance, the following structure would pass a userId value of 101010 to the application’s content:

<params>
  <param>
    <name>userId</name>
    <value>101010</value>
  </param>
</params>

The UcompOS Portal enables for the launching of 3 specific types of applications: HTML, Flash, and Adobe AIR.

By default, the file extension of the base URL is what articulates to the UcompOS Portal what type of application is being launched.  The UcompOS Portal does not, at this time, do any inspections to the content as it loads it to make this determination dynamically.  .swf extensions are treated as Flash applications, .air extensions are treated as Adobe AIR applications, and any other extension or content with no extension is treated as an HTML application.

You can however override this by setting a format attribute on the root application element.  Valid values of format are AS0 (for legacy pre-ActionScript 1 content), AS1 (ActionScript 1 content), AS2 (ActionScript 2 content), AS3 (ActionScript 3 content), flash (treated as ActionScript 3 content), and html (HTML content).  At this time an Adobe AIR application simply must have an .air extension.  By default, manifests with content that has a .swf extension that doesn’t specify a format attribute is treated as ActionScript 3 content.

The reason for the need to distinguish different versions of ActionScript is because, at this time, Flex 4 (which the UcompOS Portal is built upon) has a very hard time loading ActionScript 2 content into a SWFLoader and by passing a format attribute, it enables the UcompOS Portal to employ some workarounds to enable legacy pre-ActionScript 3 content to successfully load.

At this point it is also worth mentioning that the UcompOS Flash/Flex SDK is for ActionScript 3 content only.  At this time, there is no ActionScript 2 SDK and the emergence of one will be dictated by my own needs or the needs of other developers.

The <titles/> element provides a localized collection of application titles.  The application title is how the user sees your UcompOS application labeled on the Application Dock as well as in UcompOS Windows that your application may spawn.

Each title will have its own <title/> child element which must have a locale attribute that specifies the language for the title.  By default, the UcompOS Menu Bar has a language option where the user can change the operating language in scope.  The labels presented on the UcompOS Application Dock and UcompOS Windows automatically adjusts itself when the user changes the operating language based on the localized titles in your application manifest.

The <icons/> element behaves the same way as titles and provides a way to supply a localized collection of icons for your application that should appear on the Application Dock as well as on UcompOS Windows the application spawns.  The <icon/> child elements should point to the network URL of the icon and the format for icons should be PNG, GIF, JPG, or SWF.

The optional <menu/> element lets you set up a MenuBar model on the UcompOS Portal.  This MenuBar comes into view when the application receives focus.  An application receives focus when its icon is clicked on on the Application Dock or when a UcompOS Window an application has spawned receives focus.

The <menu/> schema is very simple as you can see in the example and you can implement an icon attribute that points to the network URL of an icon that should be displayed on the Menu Bar for a particular Menu Bar item.

The <contextmenu/> element lets you specify ContextMenu items that should appear when the user right-clicks on a UcompOS application in the Application Dock.  The schema of this is also extremely simple and easy to follow in the example.

The <toolTips/> element is a localized collection of Tool Tips that the user sees when they mouse over the application in the Application Dock.

At this time, Menu Bar and ContextMenu models cannot be localized in the application manifest however they can still be localized using more advanced techniques that I’ll cover in future postings that relate to the subject of event management.

So that’s the Application Manifest format in a nutshell!  Download the UcompOS Developers Package today and get started building your own Rich Portal Application implementation!