OpenAjax Metadata 1.0 Specification Widget Overview

From MemberWiki

Jump to: navigation, search

NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.

<--previous       contents--^       next-->


Chapter 2: Widget Overview


This chapter provides an overview of "OpenAjax Widgets".

The OpenAjax Widget format targets the following two definitions of the term "widget":

  • UI controls - The user interface components—such as combo boxes, menu bars, charts, and calendars—that some Ajax libraries provide.
  • Mashup components - Pre-packaged mini-applications (sometimes called "widgets" or "gadgets") that can be combined together within a composite application (the "mashup"), where the mashup components react to each other intelligently, such as when the user selects an address in one component, and a different component displays an updated map for that address.

An OpenAjax Widget consists of two components:

  • Widget metadata (expressed in XML).
  • JavaScript APIs that, if provided, allow a widget to be used within a mashup and to share properties and messages with other widgets.

Note that this specification does not focus on desktop-installed mini-applications that run outside of the browser, such as the "widgets" or "gadgets" that run inside the Apple Dashboard or the Microsoft Vista Sidebar, or that launch from a mobile phone. Other standards organizations, such as the W3C, are focused on desktop-installed scenarios.

Feature overview

OpenAjax Widgets encompasses:

The XML markup for OpenAjax Widgets specifies the following tags for all widgets:

The root element of a widget metadata file, includes various attributes and child elements that provides general information about the widget, such as its name, its globally unique ID, version information, the JavaScript class used to instantiate the widget (for mashable widgets), and other information.
Specifies the HTML markup that contains the widget's user interface. The block of HTML that is included within (or referenced by) the <content> element must be suitable for inclusion within an HTML <div> or <span> element. <script> elements can be included within this block of HTML.
Specifies JavaScript logic that needs to be inserted immediately before the widget's content, immediately after the widget's content, or placed at the bottom of the HTML page. (This element primarily targets design-time IDE workflows.)
<require> and <library>
Specify dependencies on various assets that are required for the widget to work properly. These dependencies consist of <link> and <script> elements that must be placed into the HTML page's <head> and the list of files (and/or entire JavaScript/Ajax libraries) that must be available to the widget at run-time.
Defines one of the widget's properties. Properties represent configurable widget parameters that might be assigned values at design-time via a property editor dialog or (in mashup scenarios) at run-time. (Shared properties are one way that widgets can interact when used together in a mashup.)
Descriptive elements such as <description>
The <description> element provides a long description for the widget. Other descriptive elements include <title>, <shortDescription>, <example>, <remarks>, <reference>, and <author>.
Provides a category keyword for this widget to allow a widget catalog to group this widget with other widgets that belong to the same category.

And an additional tag for mashable widgets:

Defines a message topic through which this widget communicates with other widgets when used in a mashup. For each given topic, a widget can indicate that it either publishes events on that topic, or subscribes to events on that topic, or both. (Pubsub techniques -- i.e., publish and subscribe -- are a second way that widgets can interact when used together in a mashup.)

See the Mashable widgets section below for an overview of features specific to mashable widgets.

UI control example

The following illustrates a sample color palette widget. This sample widget requires the Dojo toolkit (version 1.2) and the color palette widget that is included within Dojo.

Note that the OpenAjax Metadata file below, though brief, contains all of the information necessary for a developer tool to insert the code that will make the widget run in a browser: namely, the external files it relies on, the HTML and CSS that represent the widget UI, and any additional JavaScript that must be run before or after the content has loaded.


<widget id=""
	name="ColorPalette" spec="1.0" width="208" height="148"
  <library name="dojo" version="1.2" src="">
      djConfig = { isDebug: false, parseOnLoad: false, afterOnLoad: true };
    <require type="javascript" src="dojo/dojo.xd.js"/>
    <require type="css" src="dojo/resources/dojo.css"/>
    <require type="css" src="dijit/themes/dijit.css"/>
    <require type="css" src="dijit/themes/dijit_rtl.css"/>
    <require type="css" src="dijit/themes/tundra/ColorPalette.css"/>
      <div class="tundra" style="background-color:#f5f5f5" >
        <span id='__WID__palette' dojoType="dijit.ColorPalette">
  <javascript location='afterContent'>
      new dijit.ColorPalette(
            "class": "tundra"

Mashable Widgets

In this specification, the term mashable widget indicates an OpenAjax Widget that includes various optional features that allow that widget to interact with other OpenAjax Widgets at run-time when combined with other widgets in a mashup.

The following is an overview of the optional features in OpenAjax Widgets that enable a widget to interact with other OpenAjax Widgets in a mashup:

  • The 'jsClass' attribute on the <widget> element
    The presence of a 'jsClass' attribute on the <widget> element indicates that the given widget takes advantage of the mashable widget features described in this section, and that the widget requires support for the Widget APIs defined in this specification. The value of 'jsClass' specifies the widget's JavaScript class.
    NOTE: Developer tools that do not support the Widget APIs defined in this specification SHOULD NOT attempt to load widgets that include a 'jsClass' attribute.
  • The 'sharedAs' attribute on the <property> element
    By default, properties are private to a given widget. Properties can be shared across widgets (i.e., public properties) by including a 'sharedAs' attribute on the <property> element. Public properties are managed by the mashup container application.
  • The <topic> element
    The topic element specifies message topics that the given widget publishes and/or to which it subscribes. Widgets can publish messages in JavaScript by invoking the OpenAjax Hub 2.0 HubClient publish() method and can subscribe to messages published by other widgets by invoking the OpenAjax Hub 2.0 HubClient subscribe() method (see OpenAjax Hub 2.0 Specification).
  • Widget APIs - Most mashable widgets will include inline or external JavaScript logic that helps to manage
    • widget lifecycle (e.g., widget loading and unloading)
    • properties (e.g., handling notification of property value changes, changing property values)
    • events (i.e., publish on a particular topic or subscribing to a topic, using the HubClient APIs from the OpenAjax Hub 2.0 Specification)
    • size
    • modes (e.g., normal view mode, edit mode and help mode)
    • URL proxies (some mashup environments require cross-domain requests to be channeled through a proxy server)
  • Various additional attributes focused on mashup scenarios
    The XML format for OpenAjax Widgets includes various elements and attributes that are focused on mashup scenarios. Examples include:

Mashable widget example

The Widget APIs chapter includes an example of a mashable widget.

OpenAjax Widget Developer Notes

OpenAjax Alliance maintains a wiki page that contains supplemental widget developer tips and guidelines beyond what is in this specification, such as specific techniques for particular Ajax libraries. The wiki page is at:

<--previous       contents--^       next-->
Personal tools