From MemberWiki

This wiki page holds a portion of the latest internal editorial draft for what ultimately will become the OpenAjax Metadata 1.0 Specification. The base wiki page for this (latest) version of the draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Metadata_Specification. Here are the IDE WG's rules for editing this specification:

• The current working text for the specification has normal text properties (i.e., black)
• Open issues that require WG discussion are highlighted with red text
• Notes to the editor about necessary minor editorial changes are highlighted with purple text

Chapter 3: Widget Metadata

Introduction

This chapter is the starting point for the detailed specification for the XML format for OpenAjax Widgets. For an overview of OpenAjax Widgets, refer to the Widget Overview chapter.

This chapter defines the following elements:

• <widget>
• <content>
• <javascript>
• <library>, <preload>, <postload>
• <require>
• <topic>
• <category>

The following elements are defined in subsequent chapters:

• <property>, <properties>, <childProperties>
• <config>
• <enum>
• <description>
• <title>
• <shortDescription>
• <example>
• <icon>
• <license>
• <remarks>
• <reference>
• <author>
• <available>
• <deprecated>
• <useragent>
• <locale>
• Plural elements: <authors>, <categories>, <configs>, <contents>, <enums>, <examples>, <icons>, <javascripts>, <libraries>, <references>, <requires>, <topics>

Additional information about OpenAjax Widgets can be found in:

• Widget APIs chapter
• Localization chapter
• Variable Substitution chapter

<icon>

The <icon> element specifies the URI for a graphical representation for the <icon> element's parent (or grandparent element if the parent element is the plural <icons> element).

Schema

icon_element = element icon {
  icon_content  &  icon_attributes  &  foreign_attributes
}
icon_content = (
  empty
)
icon_attributes = ( 
  width?  &  height?  &  src 
)

Child content

The <icon> element must be an empty element (i.e., no child content).

Attribute summary

Additional information

An example:

<widget ... >
  ...
  <icons>                
    <icon width="36" height="36" src="lightwindow_pi.gif" />
    <icon width="16" height="16" src="lightwindow.gif" />
  </icons>
...
</widget>

When multiple <icon> elements appear in the widget metadata file, the developer tool MAY select an icon that appears to be the closest match to their needs and rescale as necessary.

Developer tools MAY use image size information included within the referenced image file instead of the values specified on the width and height attributes.

If the width or height attributes are not provided, default values are implementation-dependent.

2009-06-25 Jon: Editorial updates in attempt to reflect long-ago resolutions. There was an action to review against the W3C Widgets spec <icon> element, and their <icon> element aligns well with ours.

<content>

The <content> element specifies the markup (usually HTML) that provides the widget's presentation. The content can be either inline or in an external file (referenced by the 'src' attribute).

The content may include <script> elements. (Note: JavaScript logic can be included within a widget in multiple ways: as <script> elements within the <content>, and by including any of the following OpenAjax Metadata elements: <javascript>, <library>, <require>, <preload>, and <postload>.)

Schema

content_element = element content {
    content_content  &  content_attributes  &  foreign_attributes
}
content_content = (
  browser_markup
)
content_attributes = ( 
  lang?  &  locid?  &  mode?  &  src?  
)

Child content

The child content of the <content> element can be either empty (when the 'src' attribute is specified) or it can contain browser markup (typically, HTML). Developers SHOULD bracket any inline markup that is not well-formed or not properly-namespaced XML within a CDATA section (see Additional information for an example).

If the 'src' attribute is not provided, then the developer tool MUST assemble the browser markup by concatenating all child TEXT_NODEs and the text data within all child CDATA_SECTION_NODEs. (See discussion of DOM nodes at: [1].)

2009-06-23 Lori commented at telecon that CDATA is mentioned before properly introduced and volunteered to clean up the spec.

Attribute summary

Attribute details

'src' attribute

If the <content> element includes a 'src' attribute, then tools MUST use the referenced file and ignore any content inside the <content> element; otherwise, tools MUST use the markup contained within the <content> element.

Widget developers need to be aware of potential cross-domain restrictions when using the 'src' attribute. In some usage scenarios, the developer tool might be running within a Web browser (i.e., implemented in client-side JavaScript), in which case the browser's same-domain security policy might prevent cross-domain content retrieval. For widget portability across multiple scenarios, widget developers SHOULD ensure that the resource referenced by the src attribute is available from the same Web domain as the widget metadata file. In most situations, this can be accomplished by setting the src attribute to a relative URI. (See section on Relative URIs in the Introduction chapter.) Note that when <library> and <require> elements point to JavaScript files, they usually do not have the same domain restrictions because they typically translate into HTML <script> elements, which can reference files from other domains. 2009-05-16 Jon: WG needs to review the wording in this paragraph. At 2009-06-23 phone call, Lori said she reviewed this section and it looks OK.

'mode' attribute

(NOTE: The mode attribute targets run-time scenarios, such as mashup assembly applications. Design-time IDEs MAY ignore all display modes other than 'view'.)

The mode attribute specifies a comma-separated list of named display modes. The following display modes are defined by this specification:

• view - The default standard rendering for the widget when instantiated onto a Web page.
• edit - Custom user interface that provides a property editor that allows a user to configure the properties on a particular widget instance. In mashup workflows, edit mode typically represents the property editor that is available to the user during the mashup assembly phase.
• help - Custom user interface that provides help information about the widget.

2009-05-12 Editor: Make sure description of edit mode is sufficiently precise. Rich to forward wording used by IBM's internal format. [2] [3] 2009-05-16 Jon: Made an attempt to include words to address Rich's email, but still waiting to see what words Rich/IBM are using.

Additional information about the mode attribute:

• Custom display modes (i.e., beyond those that are defined within this specification) should use QNames, as in "foo:LargeAreaContent" and "foo:SmallAreaContent".
• When a comma-separated list of display modes is provided, then the given <content> element can be used for all display modes that are named within the list. For example, if mode="default,edit", then this content can be for both view mode and edit mode.
• A <content> element that does not have a mode attribute is functionally equivalent to <content> element that has mode="view".
• When attempting to find the appropriate content for a particular display mode, the developer tool MUST use the first <content> element whose mode attribute matches that mode.

Developer tools MUST render the appropriate <content> that corresponds to the 'view' mode for the given widget.

It is NOT required that developer tools render the alternate <content> elements that correspond to the other display modes (i.e., 'edit', 'help' and custom). However, if these other display modes are supported, then it is up to the developer tool (i.e., the mashup environment) to change the mashup environment such that the display mode is changed. One way a custom display mode might be realized would be to change the 'display' property for the old mode's content to 'none' and change the 'display' property for the new mode's content from 'none' to some other value (e.g, 'block'). However, the realization of display mode changes is implementation-specific and developer tools may use whatever technique they choose to provide the desired effect.

Whenever a display mode is changed, then the mashup environment must send a modeChanged event to the widget.

Additional information

Developers SHOULD bracket any inline markup that is not well-formed or not properly-namespaced XML within a CDATA section, as in:

<widget...>
  ...
  <content>
    <![CDATA[
      ...widget markup...
    ]]>
  </content>
  ...
</widget>

JavaScript can be included within <content> via the standard browser <script> element (see below):

<widget...>
  ...
  <content>
    <![CDATA[
      <script type="text/javascript">
        ...JavaScript logic...
      </script>
     ]]>
  </content>
  ...
</widget>

or can be placed inside within one or more separate <javascript> elements, as show below:

<widget ...>
  ...
  <javascript location="beforeContent | afterContent | atEnd">
    ...JavaScript logic...
  </javascript >
  ..
</widget>

Content may include substitution variables (e.g., __WID__, @@propname@@, %%localization_name%%, etc.) as described in the Variable Substitution chapter.

Example

The following example shows the HTML markup required for a jQueryUI Slider widget. The @@id@@ string indicates that the value of the id attribute should be substituted with the value of the id property when the widget is assembled on the page.

<content>
<![CDATA[<div id="@@id@@" class="ui-slider"><div class="ui-slider-handle"></div></div>]]>
</content>

<javascript>

The <javascript> element specifies a block of JavaScript logic that MUST be included in the runtime Web page for the widget to run.

(Note: JavaScript logic can be included within a widget in multiple ways: as <script> elements within the <content>, and by including any of the following OpenAjax Metadata elements: <javascript>, <library>, <require>, <preload>, and <postload>.)

Schema

javascript_element = element javascript {
    javascript_content  &  javascript_attributes  &  foreign_attributes
}
javascript_content = (
  text
)
javascript_attributes = ( 
  location?  &  src?
)

Child content

The child content of the <javascript> element can be either empty (when the 'src' attribute specified) or it can contain JavaScript logic.

If the 'src' attribute is not provided, then the developer tool MUST assemble the string that defines the JavaScript markup by concatenating all child TEXT_NODE's and the text data within all child CDATA_SECTION_NODE's. (See discussion of DOM nodes at: [4].) 2009-05-16 Jon: WG needs to review this paragraph.

Attribute summary

Attribute details

'src' attribute

If the <javascript> element includes a 'src' attribute, then tools MUST use the referenced file and ignore any content inside the <javascript> element; otherwise, tools MUST use the markup contained within the <javascript> element.

(See discussion about cross-domain issues within the description of the src attribute for the <content> element.)

'location' attribute

The location attribute applies to design-time scenarios, such as when using a design-time IDE to author a Web page that is ultimately saved and deployed onto a Web server. The location attribute SHOULD be ignored in run-time scenarios, such as mashup assembly tools where widgets might be added to a mashup assembly at run-time. For run-time scenarios, the JavaScript logic found within <javascript> elements SHOULD be evaluated after the appropriate <content> element has been inserted into the active Web page. 2009-06-17 Jon: WG needs to review the wording in this paragraph.

For design-time scenarios, the location attribute indicates the required placement of the JavaScript logic within the Web page. Possible values are:

• 'beforeContent' - The corresponding <script> tag MUST be inserted into the web page just before where the <content> is inserted.
• 'afterContent' - (Default) - The corresponding <script> tag MUST be inserted into the web page just after where the <content> is inserted.
• 'atEnd' - The corresponding <script> tag MUST be inserted into the web page at the end of the BODY section of the web page.

Additional information

Any JavaScript logic that contains (or might contain) characters that are significant to XML parsers, such as < or &glt; symbols, SHOULD be placed within a CDATA section, as in:

<javascript>
  <![CDATA[
    ...JavaScript logic...
  ]]>
</javascript>

When the given JavaScript logic executes at runtime, the 'this' object is the 'window' object.

JavaScript logic may include substitution variables (e.g., __WID__, @@propname@@, %%localization_name%%, etc.) as described in the Variable Substitution chapter .

Require elements

The various "require elements" described in the section below specify two types of dependencies:

• file dependency: Widgets often require external files in order to work properly, such as supplemental JavaScript or CSS files. The <library> and <require> elements reference those supplemental files through the src attribute. Users agents must ensure that all resources identified by <library> and <require> elements are available to the widget at run-time. (Exception: <library> and <require> elements that explicitly include a copy="false" attribute setting: see description of the copy attribute below.)
• HTML header dependency: Widgets often require that particular content is added to the document's <head> in order to work properly, such as a <script> element (for JavaScript) or <link> or <style> elements (for CSS). Users agents must ensure that all JavaScript and CSS and resources identified by <library> and <require> elements have appropriate HTML elements (e.g., <script>, <link>, or <style> ) added to the document. (Exception: <library> and <require> elements that explicitly include a includeRef="false" attribute setting: see description of the includeRef attribute below.)

All assets (JavaScript files, CSS files, images, etc.) that a widget requires in order to run successfully, across all possible modes (see the description of the mode attribute on the <content> element), MUST be identified by <library> and/or <require> elements. 2009-06-18 Jon: WG needs to review this paragraph.

Here is an overview of the relevant parent/child element structure and attributes for the various elements that identify which resources are required by the widget. The various elements consist of <require>, <library>, <preload> and <postload>:

<widget xmlns ="http://openajax.org/metadata" ...>
  ...
  <!-- Any number of <require> elements -->
  <require [type=""] [src=""] [target=""] [copy=""] [includeRef=""]>
    ...optional inline content if no 'src' attr and 'type' is css or javascript...
  </require>

  <!-- Any number of <library> elements -->
  <library [name=""] [version=""] [src=""] [target=""] [copy=""] [includeRef=""]>
    <!-- Any number of <require> sub-elements -->
    <require [type=""] [src=""] [target=""] [copy=""] [includeRef=""]>
      ...Optional inline content if no 'src' attr and 'type' is css or javascript...
    </require>

    <!-- at most one each of <preload> and <postload> -->
    [<preload>
      ...JavaScript to execute before the library assets are loaded...
    </preload>]
    [<postload>
      ...JavaScript to execute after the library assets are loaded...
    </postload>]
  </library>
...
</widget>

<library>

The <library> element describes an Ajax library used by the widget.

Schema

library_element = element library {
    library_content  &  library_attributes  &  foreign_nodes
}
library_content = (
  descriptive_elements  &  
  postload_element?  &  preload_element?  &  require_element*
)
library_attributes = ( 
    copy?  &  includeRef?  &  name?  &  src  &  target?  &  version?
)

Child content

The <library> element might contain any of the following sub-elements:

• descriptive_elements (various elements, such as <description> and <example>)
• <postload>
• <preload>
• <require>

Attribute summary

Attribute details

'name' attribute

The name attribute specifies a string that serves as a unique identifier for an Ajax library. It is recommended that the value for the name attribute matches the library's entry within the OpenAjax Registry. For example, "dojo" or "jQuery". (For additional information, see "Ajax library notes" below.)

'version' attribute

The version attribute specifies the version number for the referenced Ajax library. For the detailed syntax rules for the version attribute, refer to the section titled "Version number attributes" within the "Compatibility" chapter, but note that for this version attribute, only a single version number value is allowed; it is invalid to specify a version range. (For additional information, see "Ajax library notes" below.)

'src' attribute

The src attribute is required and holds the absolute or relative URI for the main JavaScript file or the base directory for the given Ajax library. For single-file Ajax/JavaScript libraries, typically the src attribute will point to the file. For multi-file libraries, typically the src attribute will point to the base folder for the library, but can also point to the main JavaScript file for the library. Assuming the copy attribute is not false, if src points to a file, then that file will be will be made available (via copying or referencing) to the deployed application, whereas if src points to a folder, then the entire contents of that folder will be made available (via copying or referencing) to the deployed application. (For additional information, see "Ajax library notes" below.) 2009-06-18 Jon: WG should review this wording.

'target' attribute

The target attribute holds the relative URI within the Web page deployment area where the resource should be placed. 2009-06-16 Jon: I believe the following sentence should be removed. The target attribute will be ignored on any <require> elements that have either type="library" or a library attribute. The target attribute defaults to the value of the src attribute.

'copy' attribute

The copy attribute is a boolean that says whether the given asset must be available to the widget at runtime. The default is "true". The main usage scenario for copy="false" is when the widget uses an Ajax library but actually only requires an explicitly-defined subset of files from that library. In this case, the widget metadata might specify copy="false" on the <library> element for a particular Ajax library and then include explicit <require> sub-elements for every resource from the Ajax library that the widget needs. This approach allows the developer tool (e.g., IDE or mashup tool) the ability to deploy an size-optimized version of the widget and its resources. Note that this attribute is only a hint. The developer tool may still make the entire Ajax library available at runtime, such as when multiple widgets reference the same Ajax library.

'includeRef' attribute

This attribute only applies when the src attribute references a file and not a folder. The includeRef attribute indicates whether the runtime Web page requires the addition of a <script> element corresponding to this <library> element. Possible values:

• 'true' (the default) indicates that tools MUST insert a <script> element. When building new HTML documents, this usually results in a new <script> element within the HEAD.
• 'false' indicates that tools MUST NOT insert a <script> element into the document.

(Note: There are no known real-world requirements for 'includeRef' on <library>. The attribute is included in the language schema for completeness.)

2009-06-30 WG needs to review the above paragraph.

Additional information

Here is an example where there is an Ajax library named "CoolAjaxLib" where the widget really only needs one JavaScript file, one CSS file, and one image file from this library:

<library copy="false" name="CoolAjaxLibrary" version="1.0" src="../libs/CoolAjaxLibrary/"/>
  <require type="javascript" src="script/parser.js"/>
  <require type="css" src="style/main.css"/>
  <require type="image" src="images/Cool.jpg"/>
</library >

(For additional information, see "Ajax library notes" below.)

<preload>

preload_element = element preload {
    preload_content  &  preload_attributes  &  foreign_attributes
}
preload_content = (
  text
)
preload_attributes = ( 
  empty
)

The <preload> element is an optional child of <library> and contains JavaScript logic to execute before the asset is loaded.

Note that there is a collision potential with <preload> if multiple widgets are placed within the same browser frame, and these widget use the same Ajax/JavaScript library, but set up conflicting library configuration parameters via different values within <preload> elements. For example, if two widgets use Dojo, and one widget sets djConfig="parseOnLoad: true";, and the other sets djConfig="parseOnLoad: false";, and and both widgets exist within the same browser frame, then there will be a conflict. Widget developers can avoid such conflicts by setting the sandbox attribute on the <widget> element to true. WG needs to review this paragraph.

Below is an example of <preload>. The widget below is a Dojo calendar widget. The <preload> logic sets three Dojo run-time configuration parameters (isDebug: false, parseOnLoad: false, afterOnLoad: true) such that these configuration parameters will have values before the Dojo JavaScript files are loaded into the Web page.

<widget name="Dojo Calendar" id="..."
        spec="1.0" width='155' height='185' sandbox="true"
        xmlns="http://openajax.org/metadata">
  <require type="javascript" src="calendar.js"/>
  <library name="dojo" version="1.2" src="http://ajax.googleapis.com/ajax/libs/dojo/1.2/">
    <preload>
      djConfig = { isDebug: false, parseOnLoad: false, afterOnLoad: true };
    </preload>
    <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/Calendar.css"/>
    <require type="css" src="dijit/themes/tundra/Calendar_rtl.css"/>
  </library>
...
</widget>

<postload>

postload_element = element postload {
    postload_content  &  postload_attributes  &  foreign_attributes
}
postload_content = (
  text
)
postload_attributes = ( 
  empty
)

The <postload> element is an optional child of <library> and contains JavaScript logic to execute after the asset is loaded.

(See the write-up of the <preload> element for additional information.)

<require>

The <require> element describes resources on which this widget depends.

Schema

require_element = element require {
    require_content  &  require_attributes  &  foreign_nodes
}
require_content = (
    text
)
require_attributes = ( 
    copy?  &  includeRef?  &  src?  &  target?  &  type
)

Child content

The child content of the <require> element can be either empty (when the 'src' attribute specified) or it can contain content appropriate to the 'type' attribute.

If the 'src' attribute is not provided, then the developer tool MUST assemble the child content by concatenating all child TEXT_NODE's and the text data within all child CDATA_SECTION_NODE's. (See discussion of DOM nodes at: [5].) 2009-05-16 Jon: WG needs to review this para

Attribute summary

Attribute details

'type' attribute

The type attribute specifies the type of the resource. Possible values are:

• 'javascript' indicates either a reference to a single external JavaScript file (if the src attribute is supplied) or an embedded snippet of JavaScript (i.e., the content of the <require> element, for when the src attribute is not supplied). A referenced JavaScript file SHOULD be converted into an HTML <script> element with a src attribute that points to the file. An embedded JavaScript snippet SHOULD be converted into an HTML <script> element where the content of the <require> element is used as the content of the generated <script> element.
• 'css' indicates either a reference to a single external CSS stylesheet file (if the src attribute is supplied) or an embedded CSS stylesheet (i.e., the content of the <require> element, for when the src attribute is not supplied). A referenced CSS stylesheet SHOULD be converted into an HTML <link> element. An embedded CSS stylesheet SHOULD be converted into an HTML <style> element within the rendered HTML document.
• 'folder' indicates a folder whose entire contents are needed by the widget and should be available to the widget at run-time (e.g., due to copying the folder into the Web page deployment area).
• 'image' indicates a single image file that is needed by the widget and should be available to the widget at run-time (e.g., due to copying the resource into the Web page deployment area). (Note: an "image file" indicates a file that is suitable for an HTML <img> element.)
• 'media' indicates a single media file (e.g., audio or video) that is needed by the widget and should be available to the widget at run-time (e.g., due to copying the resource into the Web page deployment area).
• 'other' indicates a file that is needed by the widget which doesn't fall into any of the above types and should be available to the widget at run-time (e.g., due to copying the resource into the Web page deployment area).

'src' attribute

The src attribute holds the URI for the given resource. The src attribute can be either an absolute URI or a relative URI. Below are processing rules for different cases:

• If a <require> element is a child of a <library> element, then the src attribute must be a relative URI, where the specified location is relative to the base directory for the Ajax library. This requirement for relative URIs allows developer tools (e.g., IDEs and mashup editors) to relocate Ajax libraries such that multiple widgets can use share instances of Ajax libraries. (For additional information, see "Ajax library notes" below.)
• For other cases (i.e., when the <require> element is not a child of a <library> element):
  • An absolute URI specifies the location on the Web where the resource can be found.
  • A relative URI specifies a location relative to the widget metadata file where the resource can be found.
• Widget metadata files should avoid having an absolute URI for the src attribute while also specifying a target attribute. For various reasons, the developer tools (e.g., IDE or mashup editor) might not be able to pull down the referenced resource from an absolute location on the Web and then copy the resource into the deployed Web page. It is particularly difficult to copy whole directories from a Web site using an absolute URI, such as when the <require> element has type="library" or type="folder"; developer tools are not required to support such an operation.

The src attribute is required except when type="javascript" and type="css". For these two cases, if the src is not supplied, then the inline child content of the <require> element holds the JavaScript logic or CSS internal stylesheet.

'target' attribute

The target attribute holds the relative URI within the Web page deployment area where the resource should be placed. 2009-06-16 Jon: I believe the following sentence should be removed. The target attribute will be ignored on any <require> elements that have either type="library" or a library attribute. The target attribute defaults to the value of the src attribute.

'copy' attribute

The copy attribute is a boolean that says whether the given asset must be available to the widget at runtime. The default is "true". The main usage scenario for copy="false" is for a JavaScript or CSS resource that requires a <script>, <link> or <style> element added to the <head> of the target Web page, but the resource should not be copied into the deployment area. (For example, perhaps another <library> or <require> element already caused the given resource to be available at run-time.) Note that this attribute is only a hint. The developer tool may still make the entire Ajax library available at runtime, such as when multiple widgets reference the same Ajax library.

'includeRef' attribute

The includeRef attribute indicates whether the runtime Web page requires the addition of elements to the Web page's <head> in order to work properly, such as the addition of a <script> element (for JavaScript resources identified by a <require type="javascript">) or the addition of a <link> or <style> element (for CSS resources identified by a <require type="css">). includeRef must be ignored when the type attribute is neither css nor javascript. Possible values:

• 'true' (the default) indicates that tools MUST insert an appropriate element into the document that references the given resource. When building new HTML documents, the resource reference usually consists of a new element within the HEAD (e.g., a new <script> element within the HEAD).
• 'false' indicates that tools MUST NOT insert an element into the document that references the given resource.

Ordering issues

In scenarios where this is possible, tools must add new <script>, <link> or <style> elements into the runtime document's <head> in the same order as the corresponding <library> and <require> elements appear in the widget metadata file. Note, however, in scenarios where multiple widgets within the same runtime Web page reference the same resources, the various metadata files for the different widgets might specify conflicting order, in which case the developer tool should do its best to match the order of any <require> elements that do not have conflicts.

The JavaScript logic found within <preload> and <postload> elements MUST be added to the run-time document immediately before or after (respectively) the <script>element that corresponds to the <code><library> element that is the parent of the given <preload> or <postload> element.

Ajax library notes

It is often desirable (and sometimes necessary) that multiple widgets in the same Web page share the same instance of an Ajax library. To support such sharing, the <library> element provides a mechanism for identifying any Ajax libraries used by the widget and the specific resources from the library that the widget requires at runtime in order to work properly.

To identify an Ajax library used by the widget, the widget metadata should include a
  <library name="<libname>" version="<libversion>" src="<uri>">
element, where libname and libversion are the name and version number for the library. (See previous discussion about the name, version and src attributes.)

To identify specific resources from an Ajax library that the widget must have at runtime in order to work properly, the widget metadata should include a
  <require type="<type>" src="<uri>">
child element for each specific resource needed from the given <library> element. The src attribute for the <require> element for specific library resource must be a relative URI, where the location is relative to the root folder for the Ajax library.

Widget developers that make use of an Ajax library may choose one or two strategies:

• The widget metadata might include a single <library> element for that Ajax library and not provide an explicit list of resources that his widget needs. This MUST result in the entire library being available to the widget at runtime. This is the simplest approach for the widget developer, but in some cases might result in unnecessarily large runtime download requirements. (One warning to widget developers: some Ajax libraries include auto-loading logic where the library indirectly loads files in the background. Therefore, it is not always obvious which library resources are actually used by the widget.)
• The widget metadata might include a single <library> element for that Ajax library and then multiple <require> sub-elements, one for each resource from the library that the widget uses. The main advantage of this approach is to provide enough information to the developer tool (e.g., IDE or mashup editor) such that the developer tool can achieve a size-optimized download for the widget. In this case, the <library> element that identifies the Ajax library should include a copy="false" attribute so that the developer tool knows that it doesn't have to deploy the entire library.

When developer tools (e.g., IDEs and mashup editors) attempt to have multiple widgets share the same Ajax library, developer tools may choose to assume that different versions of a given Ajax library with the same major version number provide backwards compatibility with previous versions. As a result, if the Web page includes multiple widgets that use the same library but reference different versions, widgets are able to share the same instance of the library, where the shared instance has a version number of greater than or equal to the largest version number required by any of the widgets.

For popular Ajax libraries that are posted on high-volume, high-performance CDNs ("Content delivery network), it is recommended that the src specify an absolute URI for one of the CDNs where the given Ajax library is posted.

For Ajax libraries that are not available at a CDN but are posted on the Web as an exploded directory tree (which means relative URLs will reach the resources within that library), it also might make sense to have the src specify the absolute URI for the root folder where Ajax library is posted; however, the widget developer needs to be aware that there is risk that the Web site might be subject to less reliability and performance than a CDN.

To ensure high performance, the widget developer might choose to embed the Ajax library (or at least the resources within the Ajax library that the widget uses) within the widget's directory tree itself so that runtime access to the Ajax library will have the same performance characteristics as the widget's own files.

Incorrect or incomplete <library> or <require> elements

If a given <library> or <require> element is incorrectly specified, such as when required attributes are missing, then the developer tool (e.g., IDE or mashup editor) must ignore the given <library> or <require> element and if possible notify the user about the error.

<topic>

The <topic> element provides metadata about a message topic that this widget will publish and/or to which it will subscribe. The metadata provided by the <topic> element allows mashup assembly tools (and similar products, such as portals) to link message publishers with message subscribers, thereby providing an option for inter-widget communication.

Widgets that publish and/or subscribe messages MUST use the publish/subscribe APIs on the <Widget>.OpenAjax.hub JavaScript object.

Schema

topic_element = element topic {
  topic_content  &  topic_attributes  &  foreign_nodes
}
topic_content = (
  property_element*  &  properties_element*  &  
  descriptive_elements  &  compatibility_elements
)
topic_attributes = (
  datatype?  &  format?  &  name  &  publish?  &  subscribe?
)

Child content

The <topic> element might contain any of the following sub-elements:

• descriptive_elements (various elements, such as <description> and <example>)
• compatibility_elements (various elements, such as <available> and <deprecated>)
• <property>, <properties>

<topic name="org.example.request_random_number" datatype="Number" subscribe="true">
  <description>
    Message received by this widget, which tells the widget to generate a random number.
    The expected payload of the received message is a Number which represents the seed 
    to the random number generator.
  </description>
</topic>
<topic name="org.example.new_random_number"" datatype="Number" publish="true">
  <description>
    Messsage sent from this widget that contains a newly generated random number.
    The message payload is a Number (the newly generated random number).
  </description>
</topic>

{
  coordinates:"EquatorPrimeMeridian",
  values: {
    lat:0,
    long:0,
    height:0
  }
}

<topic subscribe="true" name="org.example.geolocation" datatype="Object">
  <property name="coordinates" datatype="String"/>
  <property name="values" datatype="Object">
    <property name="lat" datatype="Number"/>
    <property name="long" datatype="Number"/>
    <property name="height" datatype="Number"/>
  </property>
</topic>

category_element = element category {
    category_content  &  category_attributes  &  foreign_attributes
}
category_content = (
  empty
)
category_attributes = ( 
  name
)

<widget ...>
  ...
  <categories>
     <category name="basic"/>
     <category name="layout"/>
  </categories>
  ...
</widget>