OpenAjax Metadata 1.0 Specification Widget Metadata

From MemberWiki

Jump to: navigation, search

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


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


Contents

Chapter 3: Widget Metadata

Introduction

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

This chapter defines the following elements:

The following elements are defined in subsequent chapters:

Additional information about OpenAjax Widgets can be found in:


<widget>

The <widget> element is the root element of an OpenAjax Metadata file that defines a single widget.

Schema

widget_element = element widget {
  widget_content  &  widget_attributes  &  foreign_nodes
}
widget_content = (
  descriptive_elements  &  compatibility_elements  &  
  category_element*  &  categories_element*  &  childProperties_element*  &  
  config_element*  &  configs_element*  &  content_element*  &  contents_element*  &  
  enum_element*  &  enums_element*  &  icon_element*  &  icons_element*  &  
  javascript_element*  &  javascripts_element*  &  library_element*  &  libraries_element*  &  
  license_element?  &  locale_element*  &  property_element*  &  properties_element*  &  
  require_element*  &  requires_element*  &  topic_element*  &  topics_element*
) 
widget_attributes = (
  aboutUri?  &  height?  &  id_attribute  &  jsClass?  &  
  lang?  &  name?  &  sandbox?  &   scrolling?  &  
  singleton?  &  spec  &  version?  &  width?
)

Child content

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

Attribute summary

AttributeDescriptionTypeRequiredDefault
aboutUri URI of a web page that contains descriptive information about this widget URI no none
height Preferred height of the area in which the widget will run Positive integer no none
id Unique identifier for this widget String (see below) yes none
jsClass JavaScript class name for the given widget. If specified, then indicates that this widget is a "mashable widget" that requires support for the Widget APIs defined in this specification. String (see below) no none
name Widget's name String (see below) no none
sandbox Hint to the tool to indicate whether the given widget requires isolation from other page content Boolean no false
scrolling Hint to the widget's container about whether the container should supply scrollbars for the widget Boolean no false
singleton Whether the given widget can only exist once in the same Web page assembly Boolean no false
spec Version number of the OpenAjax Metadata spec to which this metadata file conforms Version string (see below) yes none
version Version number that the widget developer has assigned to this widget Version string (see below) no none
width Preferred width of the area in which the widget will run Positive integer no none
lang Identifies the natural or formal language for the content. Defined in Localization chapter.

Attribute details

'aboutUri' attribute

The optional aboutUri attribute specifies the URI of a web page that contains supplemental descriptive information about this widget.

'height' attribute

The height attribute is a positive integer that specifies the preferred height (in pixels, per the CSS2 specification) of the area in which the widget runs. This value represents a hint to the developer tool, which can either honor the value or ignore it. If no value is provided, then the default value will be implementation-specific.

'id' attribute

The id attribute (referred to as id_attribute in the schema) is required and specifies a unique identifier for this widget in the form of a URI. The URI can use any valid URI protocol (e.g., http:, urn: or javascript:) so long as the value represents a globally unique identifier. For example, if OpenAjax Alliance created its own news widget, the id attribute might be id="http://openajax.org/widgets/latestnews".

'jsClass' attribute

The presence of a jsClass attribute on the <widget> element indicates that this is a mashable widget that requires support for the Widget APIs defined in this specification. The value of jsClass specifies the widget's JavaScript class, such as MyWidgetClass or com.example.abc.MyWidgetClass. If provided, then the widget run-time environment MUST invoke the class constructor for each instance of this widget. Typically, the class constructor is invoked using a JavaScript new operator, such as: new com.example.abc.MyWidgetClass().
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.

'name' attribute

The name attribute specifies the widget name, and is optional. If specified, the widget name SHOULD be unique within a particular widget collection (e.g., unique name within the set of widgets within an Ajax library).

'sandbox' attribute

The sandbox attribute is a hint to the tool to indicate whether the given widget can co-exist within the same document as other content. Note that tools do not have to honor this hint. In particular, a mashup tool might choose to sandbox all widgets into separate IFRAMEs regardless of the value of this attribute. Possible values:

  • 'false' - (Default) This widget can co-exist with other content.
  • 'true' - The widget cannot co-exist with other content and should be put into its own execution sandbox, such as its own IFRAME (in the case of HTML).
'scrolling' attribute

The scrolling attribute is an optional Boolean value indicating whether the container should provide scrollbars if the widget's width or height is greater than the area provided for the widget. The default is false.

'singleton' attribute

The singleton attribute is an optional boolean that specifies whether the given widget can only exist once within a given Web page assembly. The default is false, which indicates that the widget can be added more than once.

'spec' attribute

The spec attribute specifies the version number of the OpenAjax Metadata spec to which this metadata file conforms. (See the write-up on Version number attributes in the Compatibility elements and attributes chapter for rules on version number attributes.) This attribute is required.

'version' attribute

The version attribute specifies the version number that the widget developer has assigned to this widget. (See the write-up on Version number attributes in the Compatibility elements and attributes chapter for rules on version number attributes.)

'width' attribute

The width attribute is a positive integer that specifies the preferred width (in pixels, per the CSS2 specification) of the area in which the widget runs. This value represents a hint to the developer tool, which can either honor the value or ignore it. If no value is provided, then the default value will be implementation-specific.

Example

The following example shows a simple widget element:

<widget xmlns="http://openajax.org/metadata"
        name="Sample Widget"  
        version="1.0.0"
        id="http://openajax.org/spec/metadata/samples/samplewidget"
        spec="1.0">
  <content>Sample Widget</content>
</widget>


<content>

The <content> element specifies the markup (usually HTML) that provides the widget's presentation. Content can be either inline or in an external file, and it may include <script> elements. (See also <javascript>, <library>, <require>, <preload>, and <postload> for other places where a widget's JavaScript logic and dependencies can be described.) Content may also include substitution variables (e.g., __WID__, @@propname@@, ##localization_name##) as described in the Variable Substitution chapter.

Schema

content_element = element content {
    content_content  &  content_attributes  &  foreign_attributes
}
content_content = (
  browser_markup
)
content_attributes = ( 
  lang?  &  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, as in:

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


If the 'src' attribute is not provided, then the developer tool MUST assemble the browser markup using logic that is functionally equivalent to taking the textual representation of content inside of the <content> element, but converting all CDATA sections into text (i.e., in effect, strip out all <![CDATA[ and ]]> strings).

Attribute summary

AttributeDescriptionTypeRequiredDefault
mode The mode attribute allows for multiple alternate display modes for a particular widget view||edit||help||Qname no view
src The src attribute, if present, specifies the URL of an external file that contains the content URI no see below
lang Identifies the natural or formal language for the content. Defined in Localization chapter.

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 <library> and <require> elements that reference JavaScript files do not have the same domain restrictions because they typically translate into HTML <script> elements, which can reference files from other domains.


'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 for 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.

Additional information about the mode attribute:

  • Custom display modes (i.e., beyond those that are defined within this specification) SHOULD be specified as 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 widget run-time environments 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.


<javascript>

The <javascript> element specifies a block of JavaScript logic that MUST be included in the runtime Web page for the widget to run. (See also <content>, <library>, <require>, <preload>, and <postload> for other places where a widget's JavaScript logic and dependencies can be described.) The JavaScript can either be inline or in an external file, and it may include substitution variables (e.g., __WID__, @@propname@@, ##localization_name##) as described in the Variable Substitution chapter.

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 is specified) or it can contain JavaScript logic. Developers SHOULD bracket any inline JavaScript logic that contains (or might contain) characters that are significant to XML parsers, such as < or > symbols, within a CDATA section, as in:

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

If the 'src' attribute is not provided, then the developer tool MUST assemble the browser markup using logic that is functionally equivalent to taking the textual representation of content inside of the <javascript> element, but converting all CDATA sections into text (i.e., in effect, strip out all <![CDATA[ and ]]> strings).

Attribute summary

AttributeDescriptionTypeRequiredDefault
location Placement of the JavaScript logic within the Web page beforeContent|afterContent|atEnd no afterContent
src The src attribute, if present, specifies the URL of an external file that contains the content URI no see below

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

For design-time scenarios, such as when using an IDE to author a Web page, 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.

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 runtime. 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.


Additional information

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


Require elements

The elements in this section, collectively referred to as "require elements," are concerned with identifying the assets that a widget requires in order to run successfully—and with indicating to the developer tool whether those assets should be copied to the deployment area and referenced in the head of the document containing the widget. All assets that a widget requires in order to run successfully, across all possible modes, MUST be identified by <library> and/or <require> elements. Developers have control over which files are copied and which are referenced via the copy and includeRef attributes, described below.

The following code snippet shows the parent/child element structure and attributes for the various require elements: <require>, <library>, <preload> and <postload>:

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

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

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.

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 of 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. (Note that when referring to a library by folder, a <require> element that points to the main file for the library must also be included so that a <script> element referencing the library can be included in the user's document.)
  • 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. 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. (One warning to widget developers: Some Ajax libraries load modules indirectly, through in-library logic, rather than explicitly, through <script> tags. It may be necessary to use a browser console tool such as Firebug to determine which library resources are actually being loaded by a 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?  &  type?  &  version?
)

Child content

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


Attribute summary

AttributeDescriptionTypeRequiredDefault
name String that serves as a unique identifier for an Ajax library String yes none
version Version number for the referenced Ajax library Version string (see below) no none
src URI for the main JavaScript file or the base directory for the given Ajax library URI yes none
type Specifies whether the library is a single JavaScript file or a folder containing any number of files javascript|folder no folder
target Relative URI within the widget deployment area where the resource should be placed URI no Value of 'src' attribute
copy Specifies whether the entire library MUST be available to the widget at runtime Boolean no true
includeRef (Only applicable if type="javascript") Indicates whether a <script> element must be added to the document's <head> for this library's JavaScript file. Boolean no true


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". The name MUST be globally unique within the context of current container object.

'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.

When developer tools 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.

'src' attribute

The src attribute specifies the absolute or relative URI for the main JavaScript file or the base directory for the given Ajax library. This attribute is required. 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 it can also point to the main JavaScript file for the library. Assuming the copy attribute is not false, then the file or contents of the folder will be made available (via copying or referencing) to the deployed application.

For popular Ajax libraries that are posted on high-volume, high-performance content delivery networks (CDNs), 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 so that runtime access to the Ajax library will have the same performance characteristics as the widget's own files.

'type' attribute

The type attribute whether the library is a single JavaScript file or a folder containing any number of files. The default is 'folder'.

'target' attribute

The target attribute specifies the relative URI within the widget deployment area where the resource should be placed. It defaults to the value of the src attribute. See 'target' attribute details below.

'copy' attribute

The copy attribute is a Boolean value indicating whether the entire library must be available to the widget at runtime. The default is true. When a widget only requires an explicitly-defined subset of files from an Ajax library, the widget metadata might specify copy="false" on the <library> element for the Ajax library and then include an explicit <require> sub-element for each resource from the library that the widget needs. This approach allows the developer tool to deploy a 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

The includeRef attribute is a Boolean value indicating whether a <script> element should be added to the Web page's <head> in order to work properly. includeRef MUST be ignored when the type attribute is not equal to javascript. The default value is true.

One scenario where includeRef might be set to false is when other logic within the widget will import the library's JavaScript file, so insertion of a <script> element into the <head> would be unnecessary or would cause the widget to malfunction. A false value indicates that tools MUST NOT insert an element into the document that references the given resource.

Example

The following snippet is for a widget that needs only one JavaScript file, one CSS file, and one image file from the CoolAjaxLibrary 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 >


<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 an asset is loaded.

Note that there is a collision potential with <preload> if multiple widgets are placed within the same browser frame, and these widgets 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 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.

Example

The metadata below describes 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 an asset is loaded. See <preload> element.


<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 = ( 
    includeRef?  &  src?  &  target?  &  type
)

Child content

The child content of the <require> element can be either empty (when the 'src' attribute is specified) or it can contain content appropriate to the 'type' attribute. Developers SHOULD bracket any inline markup that is not well-formed or not properly-namespaced XML within a CDATA section.

If the 'src' attribute is not provided, then the developer tool MUST assemble the browser markup using logic that is functionally equivalent to taking the textual representation of content inside of the <require> element, but converting all CDATA sections into text (i.e., in effect, strip out all <![CDATA[ and ]]> strings).

Attribute summary

AttributeDescriptionTypeRequiredDefault
type Specifies the type of the resource javascript|css|folder|image|media|markup|other yes none
src URI for the given resource URI see below none
target Relative URI within the widget deployment area where the resource should be placed URI no Value of 'src' attribute
includeRef Indicates whether appropriate elements must be added to the document's <head> Boolean no true


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 where the content of the <require> element is used as the content of the generated <style> element.
  • 'folder' indicates a folder whose entire contents are needed by the widget and should be available to the widget at run-time.
  • 'image' indicates a single image file that is needed by the widget and should be available to the widget at run-time. (Note: An "image file" indicates a file that could be included with 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.
  • 'markup' indicates arbitrary inline content to include inside of the <head> of the HTML document. This option can be used for a variety of purposes, such as including an HTML comment into the document or adding a fully-formed <script> element.
  • 'other' indicates a file that is needed by the widget and should be available to the widget at run-time, but that doesn't fall into any of the above types.
'src' attribute

The src attribute holds the URI for the given resource. It is required except when type="javascript" and type="css" (in these cases, the inline child content is used when src is not supplied).

The src attribute can be either an absolute or a relative URI, as follows:

  • When the <require> element is a child of a <library> element, the src attribute must be a relative URI, where the specified location is relative to—and inside—the base directory for the Ajax library. Upward references (e.g., ../) are not allowed. This requirement for relative URIs allows developer tools to relocate Ajax libraries such that multiple widgets can share instances of Ajax libraries.
  • 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.
'target' attribute

The target attribute specifies the relative URI within the widget deployment area where the resource should be placed. It defaults to the value of the src attribute. See 'target' attribute details below.

'includeRef' attribute

The includeRef attribute indicates whether the runtime Web page requires the addition of <script>, <link>, or <style> elements to the Web page's <head> in order to work properly. 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.


Absolute URIs not valid for type="folder" and copy="true"

Widget developers SHOULD NOT set the src attribute on <library> and <require> elements to an absolute URI if the given element has type="folder" and copy="true". For various reasons, the developer tools 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. Developer tools are not required to support such an operation.


'target' attribute details

The target attribute on the <library> and <require> elements specifies a relative URI within the widget deployment area where the resource MUST be placed in order for the widget to work properly. It defaults to the value of the corresponding src attribute on the given element.

Widget developers SHOULD NOT specify a target attribute when the src attribute is an absolute URI. For various reasons, the developer tools 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. Developer tools are not required to support such an operation.

Developer tools can adopt various approaches for where the widget's referenced files are deployed onto the run-time Web site. Developer tools MAY deploy the widget's files such that the widget root folder is equivalent to the web site's root directory or MAY deploy the widget's files elsewhere. In all cases, however, developer tools MUST ensure that any relative URIs within src and target attributes on <library> and <require> elements will function correctly at run-time.

To illustrate ../ references, assume the source area for the widget has the following layout:

<somedir>/js/mywidget.js
<somedir>/css/mywidget.css
<somedir>/libs/foolib/foolib.js
<somedir>/libs/foolib/foolib.css
<somedir>/libs/openajax/oam/mywidget_oam.xml

and suppose that the widget metadata file mywidget_oam.xml contains the following content:

<require type="javascript" src="../../../js/mywidget.js"/>
<require type="css" src="../../../js/mywidget.css"/>
<library name="foolib" src="../../foolib" version="1.0" copy="false">
  <require type="javascript" src="foolib.js"/>
  <require type="css" src="foolib.css"/>
</library>

When the web application is deployed, the developer tool MUST ensure that the ../ references will work correctly at run-time, which in the above case includes three parent folder levels (i.e., ../../../).

Examples

Example 1: No target paths

In this example, the <library> element and <require> elements do not contain any target attributes. As a result, the default value for target is used, which is the same value as the src attribute on the given element.

If the original source file/folder structure is:

<somedir>/js/mywidget.js
<somedir>/css/mywidget.css
<somedir>/libs/foolib/foolib.js
<somedir>/libs/foolib/foolib.css
<somedir>/libs/openajax/oam/mywidget_oam.xml

If the mywidget_oam.xml metadata file contains the following:

<require type="javascript" src="../../../js/mywidget.js"/>
<require type="css" src="../../../css/mywidget.css"/>
<library name="foolib" src="../../foolib" version="1.0" copy="false">
  <require type="javascript" src="foolib.js"/>
  <require type="css" src="foolib.css"/>
</library>

If the developer tool decides to deploy the widget files and the foolib library to match the original source folder structure at the Web site root (i.e., /), then the deployed folder structure will look like this:

/js/mywidget.js
/css/mywidget.css
/libs/foolib/foolib.js
/libs/foolib/foolib.css
Example 2: target on <library> and widget-level <require> elements

Assume the same original source file/folder structure as in Example 1 and assume that the mywidget_oam.xml metadata file contains the following:

<require type="javascript" src="../../../js/mywidget.js" target="mywidget-1.0/js/mywidget.js" />
<require type="css" src="../../../css/mywidget.css" target="mywidget-1.0/css/mywidget.css" />
<library name="foolib" src="../../foolib" version="1.0" copy="false" target="foolib-1.0" >
  <require type="javascript" src="foolib.js"/>
  <require type="css" src="foolib.css"/>
</library>

Assuming the developer tool sets the widget deployment folder to the root of the web site, then the deployed folder structure will be:

/mywidget-1.0/js/mywidget.js
/mywidget-1.0/css/mywidget.css
/foolib-1.0/foolib.js
/foolib-1.0/foolib.css
Example 3: target on <require> children of <library>

Assume the same original source file/folder structure as in Example 1 and assume that the mywidget_oam.xml metadata file contains the following:

<require type="javascript" src="../../../js/mywidget.js"/>
<require type="css" src="../../../css/mywidget.css"/>
<library name="foolib" src="../../foolib" version="1.0" copy="false">
  <require type="javascript" src="foolib.js" target="jsFiles/foolib.js" />
  <require type="css" src="foolib.css" target="cssFiles/foolib.css" />
</library>

Assuming the developer tool sets the widget deployment folder to the root of the web site, then the deployed folder structure will be:

/js/mywidget.js
/css/mywidget.css
/libs/foolib/jsFiles/foolib.js
/libs/foolib/cssFiles/foolib.css
Example 4: target on <library> and <require> children of <library>

Assume the same original source file/folder structure as in Example 1 and assume that the mywidget_oam.xml metadata file contains the following:

<require type="javascript" src="../../../js/mywidget.js" target="mywidget-1.0/js/mywidget.js" />
<require type="css" src="../../../css/mywidget.css" target="mywidget-1.0/css/mywidget.css" />
<library name="foolib" src="../../foolib" version="1.0" copy="false" target="foolib-1.0" >
  <require type="javascript" src="foolib.js" target="jsFiles/foolib.js" />
  <require type="css" src="foolib.css" target="cssFiles/foolib.css" />
</library>

Assuming the developer tool sets the widget deployment folder to the root of the web site, then the deployed folder structure will be:

/mywidget-1.0/js/mywidget.js
/mywidget-1.0/css/mywidget.css
/foolib-1.0/jsFiles/foolib.js
/foolib-1.0/cssFiles/foolib.css


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 that 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(s) that correspond to the children of the <library> element that is the parent of the given <preload> or <postload> element.


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 must ignore that <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 to 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 = (
  type?  &  format?  &  name  &  publish?  &  subscribe?
)

Child content

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

A <topic> element MAY contain <property> or <properties> sub-elements only when the 'type' attribute is set to or allows the value type "object". In this case, the <property> elements provide descriptive detail about the various properties on the JavaScript data object that will be passed whenever the message is published.

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Topic name String yes none
publish Whether this widget publishes messages on the given topic Boolean no false
subscribe Whether this widget subscribes to messages on the given topic Boolean no false
type The raw JavaScript datatype for the message's payload String no "*" (the asterisk character)
format Supplemental, higher-level datatype information. See write-up on 'format' attribute in Datatypes chapter.

Attribute details

'name' attribute

The name for this topic. The name MUST conform to the topic name rules defined in the OpenAjax Hub 2.0 Specification. The name MUST be globally unique within the context of current container object.

'publish' attribute

Boolean attribute that indicates whether the widget publishes messages on the given topic. Default is false.

'subscribe' attribute

Boolean attribute that indicates whether the widget subscribes to messages on the given topic. Default is false.

'type' attribute

The raw JavaScript datatype for the message's payload.

The 'type' attribute on the <topic> element can take a subset of the values that are allowed on the datatype attribute (described in the Datatypes chapter). Allowable values for the 'type' attribute include:

  • string
  • number
  • boolean
  • array
  • object
  • null
  • * (asterisk character) - indicates any datatype is allowed (this is the default)

For more information on 'type', see the "Additional information" below.

Additional information

Background information on publish/subscribe messaging can be found in the OpenAjax Hub 2.0 Specification.

A published message consists of a topic name (specified by the name attribute) and a message payload (whose datatype is specified by the type attribute). This specification assumes that message payloads will be passed by value to other widgets. The message payload MUST be a JSON-serializable JavaScript object, which means that:

  • the message payload MUST NOT contain JavaScript executable logic (e.g., Function objects)
  • any <property> elements that are descendant of a <topic> element MUST NOT have datatype="Function"

At least one of publish or subscribe MUST be true.

Examples

The following snippet shows two <topic> elements for a single widget. The first element indicates that this widget subscribes to the topic "org.example.request_random_number", which receives the payload of a JavaScript Number that provides the seed for the random number generator, and the second indicates that the widget publishes the topic "org.example.new_random_number", whose payload is the generated random number:

<topic name="org.example.request_random_number" type="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"" type="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>

The following example shows how to use descendant <property> elements to describe a message payload that consists of a JavaScript object. Assume that the object has nested properties as follows:

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

The <topic> element would describe this object as follows:

<topic subscribe="true" name="org.example.geolocation" type="object">
  <property name="coordinates" datatype="atring"/>
  <property name="values" datatype="object">
    <property name="lat" datatype="number"/>
    <property name="long" datatype="number"/>
    <property name="height" datatype="number"/>
  </property>
</topic>


<category>

The <category> element provides a single keyword that can help a developer tool decide how to group widgets onto submenus or palettes. (OpenAjax Alliance has a wiki page on which the alliance is working to produce common widget category names in order to promote interoperability: http://www.openajax.org/member/wiki/OpenAjax_Widget_Categories.)


Schema

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

Child content

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

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Category name String yes none

Attribute details

'name' attribute

The name attribute defines a grouping name for the widget that a tool might use to organize widgets within a widget palette or within a menu. For example, all widgets with category "Basic" might appear within the "Basic" section within the widget palette. The name MUST be globally unique within the context of current container object.

Some tools may have nested grouping levels for widgets. For example, perhaps there will be a first-level tab which shows "Basic" widgets, and then a sub-tab within the "Basic" tab for widgets that represent "Buttons". The recommended convention for identifying hierarchical widget groups is to use a double-colon sequence ("::") as the token separator string. For example, name="Basic::Buttons".

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



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