OpenAjax Metadata Specification Widget Metadata
From MemberWiki
Notes:
- 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 is the proposed way for the IDE WG to edit this specification:
- All textual content that has normal text properties (i.e., black) and has no colored status text (e.g., does not say Tentatively approved, Draft consensus or Approved) represents preliminary proposed text that requires further review and discussion.
- Members of OpenAjax Alliance are encourage to place inline comments into this document, preferably by identifying your name or initials before your comment, such as "Mary: This bullet should be moved above previous bullet".
- When an item has been deemed complete by the WG chair due to committee consensus, then the annotation Approved will be placed at the end of an approved block of text (e.g., paragraph or bullet). Note that during the development phase of this specification, the group can change its mind and "un-approve" text that was previously approved.
- When an item has been deemed near complete by the WG chair due to committee consensus, but further review is necessary (e.g., review final wording), then the annotation Tentatively approved or , Draft consensus will be placed at the end of given block of text (e.g., paragraph or bullet).
2 Widget Metadata
Introduction
This chapter defines the XML format for standard metadata for Ajax "widgets", where we are targeting the following two definitions of the term "widget":
- UI controls - Some Ajax libraries provide a set of user interface building block components such as combo boxes, menu bars, or charts
- Mashup components (aka "widgets" and "gadgets") - Mashup frameworks allow for pre-packaged mini-applications (sometimes called "widgets" or "gadgets") to 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 which causes a different component to display an updated map that shows the given address.
Note that this specification does not focus on a third definition of "widget", where the term refers to a desktop-installed mini-application that runs outside of the browser, such as the "widgets" or "gadgets" that run inside of Apple's Dashboard, the Microsoft Vista Sidebar, or launch from a mobile phone. Other standards organizations, such as the W3C's Widgets specification, are focused on desktop-installed scenarios. Although this specification is separate from the W3C specification, in recognition of the technology and marketplace overlap, there has been considerable active coordination between the W3C effort and this effort to maximize compatibility.
2008-04-29 Draft consensus: (Not sure where to put this, so putting this here for now) We decided that in IDE workflows the tool loads a set of metadata files and these files can reference the datatypes defined in other files, but for mashup workflows, each widget file is self-contained except for any dependencies that are explicitly listed by its <require> elements.
Feature overview
Proposed editorial strategy: this section would be concise and provide a bulleted list of the kinds of features that widget metadata describes (e.g., properties, icons, topics, dependencies, ...), with links to the elements that correspond to those features, and then the main body of the chapter would be the detailed reference section. 2008-04-22: Draft consensus. Reasonable approach.
Example
The following is an example for a clock widget:
NOTE: The example below was copied/pasted from previous work, may not be appropriate, and almost certainly needs changing.
<widget
xmlns="http://openajax.org/metadata"
name="Clock"
version='1.0'
spec='1.0' <!-- i.e., version of IDE metadata spec -->
>
<title>Clock widget</title>
<description>Clock widget with several configuration options for size and styling</description>
<icons>
<icon src=images/dojo-clock.jpg"/>
</icons>
<content>
<![CDATA[
<div>(time visualization markup goes here)</div>
]]>
</content>
<properties>
<property name="clockType" datatype="String" default="black">
<description>A clock widget</description>
<options>
<option value='Plain' label='plain'/>
<option value='Black' label='black'/>
<option value='Black Texture' label='textured black'/>
<option value='Gray' label='gray'/>
<option value='Gray Plastic' label='plastic gray'/>
</options>
</property>
<property name="timeZoneOffset" datatype="Number" default="0">
<description>The time Offset."</description>
</property>
<property name="label" datatype="String" default="">
<description>The label at the top of the clock.</description>
</property>
<property name="labelColor" datatype="String" format="color" default="#000">
<description>The color of the label.</description>
</property>
<property name="topLabelColor" datatype="String" format="color" default="#efefef">
<description>The color of the label at the top of the clock.</description>
</property>
<property name="handColor" datatype="String" format="color" default="#788598">
<description>The color of the clock hand.</description>
</property>
<property name="handBorderColor" datatype="String" format="color" default="#6f7b8c">
<description>The color of the borders around the minute and hour hands.</description>
</property>
<property name="secondHandColor" datatype="Array" arrayType="Number" default="[201, 4, 5, 0.8]">
<description>The color of the second hand in [R,G,B, opaicity] format.</description>
</property>
<property name="showAMPM" datatype="Boolean" default="true">
<description>Where or not to show an AM/PM with the clock</description>
</property>
</properties>
<requires>
<require type="library" name="dojo" minVersion="0.9">
<preload>
parseOnLoad: false, isDebug: true, extraLocale: ['en-us', 'ar-sy', 'es-es', 'zh-cn']
</preload>
</require>
</requires>
</widget>
Widget metadata
Need to add short intro
The <widget> element
Tentative decision on 2008-08-12 to allow inline message bundles, but we are still working out the details. Latest proposal is to add a <messagebundle> element to our grammar.
2008-09-23: We are considering an enhancement to allow for a declarative mechanism to describe the parameter list to the widget constructor so that for some widgets there is no need to create a wrapper class.
widget_element = element widget {
widget_content & widget_attributes & foreign_nodes
}
widget_content = (
descriptive_elements & compatibility_elements & inclusion_elements &
author_element* & authors_element* & category_element* & categories_element* &
childProperties_element* & content_element* & contents_element* &
icon_element* & icons_element* & javascript_element* & javascripts_element* &
license_element? & property_element* & properties_element* &
require_element* & requires_element* & topic_element* & topics_element*
)
widget_attributes = (
aboutUri? & height? & id_attribute & jsClass? &
name? & sandbox? & scrolling? & singleton? &
spec? & version? & width?
)
The <widget> element is the root element of a widget description file. Each widget description file describes a single widget.
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 (using the http: protocol) id="http://openajax.org/widgets/latestnews". If the javascript: protocol is used, then the value after javascript: should be in the form of a JavaScript object (i.e., uses dot notations as in javascript:MyLibrary.aaa.bbb), where the first token preferably is a JavaScript global object that is listed in the OpenAjax Registry. To illustrate with the same example (i.e., an OpenAjax news widget), the id attribute might look like this: javascript: protocol) id="javascript:OpenAjax.widgets.latestnews". (Note that the "OpenAjax" object is registered in the OpenAjax Registry.)
The name attribute specifies the widget name. 20080520 Tentatively approved: Yes, have 'name'. Name attribute does not have to be globally unique. Eg, We expect possibility of multiple widgets with name of 'tooltip'. There is implicit namespacing for widgets within a library because the library has an implicit namespace. OK for tools to manufacture a namespace from author if needed. Need to say that a name must match construction for JavaScript identifiers. Remove the restriction on the name, the name is OPTIONAL and drop the suggestion regarding using the title attribute if the name attribute is not specified.
The aboutUri attribute specifies the URI of a web page that contains descriptive information about this widget. 2008-05-13 Tentatively approved
The height attribute is a positive integer that specifies the preferred height of the area in which the gadget runs. The default height is 200 pixels. 20080520 Tentatively approved: height means preferred height. Tool can use the value or ignore it. No default value. Up to user agent/host.
The jsClass attribute, if provided, is a String that defines the JavaScript class that corresponds to the given widget. For example,
jsClass="fooLib.widgets.barWidget" would say that this widget (named "barWidget") which might come from a particular Ajax library (e.g., "fooLib", which installs itself on global object "fooLib") has its JavaScript class at window.fooLib.widgets.barWidget".
2008-02-21: Tentatively approved. We decided that we needed a 'jsClass' attribute, but we are planning to work on the details as part of a more comprehensive look at Gadget APIs. 2008520: Tentatively approved. If specified, then that constructor MUST be used. If not specified, the environment may invoke a constructor that it supplies or not invoke a constructor at all.
The scrolling attribute is a boolean that is a hint to the widget's container about whether the container should provide scrollbars if the widget's height is greater than the area provided for the widget. The attribute value true indicates that the container should provide scrollbars when the containing area is not as large as the widget. The value false indicates that the container should not provide scrollbars. The default is false. 2008-05-29 Tentatively approved
The version attribute specifies the version number that the widget developer has assigned to this widget. For example, version 2 of a combo box widget might have differences from version 1 of a combo box widget. (See the section titled "Version number attributes" within the "Compatibility" chapter for rules on version number attributes.) 2008-05-29: Tentatively approved
The spec attribute specifies the version number of the OpenAjax Metadata spec to which this metadata file conforms. (See the section titled "Version number attributes" within the "Compatibility" chapter for rules on version number attributes.) 2008-05-29: Tentatively approved
The width attribute is a positive integer that specifies the preferred width of the area in which the gadget runs. The default height is 200 pixels. 20080520 Tentatively approved: width means preferred height. Tool can use the value or ignore it. No default value. Up to user agent/host.
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. 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)
The singleton attribute provides an optional boolean that specifies whether users can add a gadget multiple times from a directory. The default is false, meaning that by default, gadgets can be added more than once. Directories can handle this attribute however they choose. For example, the content directory handles singleton="true" by graying out and displaying the text "Added" for gadgets that have already been added. Note that changes to this attribute may not be picked up by directories right away. This attribute doesn't prevent users from adding gadgets multiple times through the developer gadget or Add by URL. Consequently, you still need to write your gadget to support multiple instances. 2008-06-24 Tentatively approved Editor: clean this up
For getterPattern, setterPattern, onchangePattern, see the description under the The <property> element.
Editor: the list below isn't correct. Missing author[s] and probably others
The following subelements and attributes are defined elsewhere:
-
<childProperties>,<properties>: "Properties" chapter -
<authors>,<description>,<examples>,<icons>,<license>,<remarks>,<title>: "Descriptive elements and attributes" chapter -
<topics>: "Topics" chapter -
<useragents>,<available>,<deprecated>: "Compatibility" chapter
2008-07-23 Jon: Phil has proposed a <childProperties> element, such as when a child element needs to pass information to parent to help control layout. I have done some due diligence on this. It is common that layout containers utilize some sort of "property" (e.g., XML attribute or JSON property) on the child objects that lie inside. Dojo put a 'layoutAlign' attribute on <div> elements that are the children of container elements. ExtJS defines layout hierarchies in JSON where there is a parent container JavaScript object which has a list of "items" (each of which is a JavaScript object), and each item can pass layout information to its parent via JavaScript properties such as 'layout'. XAML's <DockPanel> container looks for DockPanel.Dock attributes on its child elements. (I didn't see anything like this in Spry, but I might not have been looking in the right place. 2008-07-23 Draft Consensus: Yes, there will be a new <childProperties> element that has <property> elements as children. This is used to tell the tool that it needs to add all of "child properties" to the property editors for any child widgets. Editor: Need to fix schema and spec. Then remove red-colored comment.
Subelements defined in this chapter
Category elements
The <category> element
2008-05-13: Draft consensus. We resolved that there will be <categories> and <category> elements along with a built-in list of category names (e.g., "basic", "mapping", "container") along with an extensibility strategy (e.g., use QNames).
category_element = element category {
category_content & category_attributes & foreign_attributes
}
category_content = (
empty
)
category_attributes = (
name
)
The <category> element provides a single keyword that can help an IDE or mashup editor decide how to group widgets onto submenus or palettes. 2008-05-13 Tentative approval: We resolved that there a built-in list of category names (e.g., "basic", "mapping", "container") along with an extensibility strategy (e.g., use QNames). Need more details
The name attribute specifies the category name.
Example:
<widget ...>
...
<categories>
<category name="basic"/>
<category name="layout"/>
</categories>
...
</widget>
2008-05-29 Tentatively approved
The <categories> element
categories_element = element categories {
categories_content & categories_attributes & foreign_nodes
}
categories_content = (
descriptive_elements & inclusion_elements &
category_element*
)
categories_attributes = (
name?
)
The <categories> element holds zero or more <category> child elements.
The optional name attribute is meant to allow for providing a unique name for this particular <categories> element in case multiple <categories> are specified.
2008-05-29 Tentatively approved
Content elements
The <content> element
2008-04-24: Tentatively approved. We have agreed to supporting macro expansion per Lori's proposal, where macro expansion looks for every property "p" and replaces all occurrences in the content of @@p@@ with the property value.
2008-04-29: Tentatively approved. We decided that we would support macro expansion from both the property bag and from the localization files, but that we would use different syntax for the two in order to prevent collisions. Use @@foo@@ for property expansion and %%bar%% for localization expansion.
2008-06-24: We accepted the Gadgets TF recommendation the following: "A processing engine MUST apply localization transformation to <content>, <javascript>, <description>, <title>, <remarks>, <example>, <license>, <author>. The <include> element references an external file whose content is to be transcluded into the current document; therefore included content MUST also be processed following the same localization transformations." Also our new elements <aboutMe> and <quote>
2008-08-12: Tentatively approved Variable substitution also applies to preload, postload and inline require.
2008-08-19: Jon needs to edit spec about when the transformations occur exactly and whether they occur once or multiple times. (In red in case this raises issues to discuss.).
Editor: need to make sure there are appropriate warnings about XSS in property values and other user-entered strings.
Editor: need to include text about __WID__ macro expansion, where __WID__ holds the name of the JavaScript object for the widget instance object. For example, "__WID__" might become "wid004682988", where the numeric part is a random number.
The __WID__ feature has been driven from the Gadgets TF, but the IDE folks need to know how the feature impacts them. What happens if an Ajax library creates a widget that includes __WID__ inside of a <content> or <javascript> element? It seems like we are expecting that the IDE will replace __WID__ with the widget's JavaScript object, but which object is that exactly?
2008-08-19 Tentative Approval: The following elements are subject to localization substitution: Localization substitutions:inline <content>, inline <javascript>, inline <require>, <preload> (always inline), <postload> (always inline), <author>, <description>, <example>, <include> (i.e., after the inclusion, then process the included elements), <license>, <remarks>, <title>, <aboutMe>, <quote>. The following elements are subject to property substitution and __WID__ substitution: inline <content>, inline <javascript>, inline <require>, <preload>, <postload>. Need to update spec to reflect this decision.
2008-08-19 Tentative Approval: Within an @@foo@@ (property reference) or a %%bar%% (localization reference), you can specify either @@entityencode(foo)@@ or @@escapequotes(foo)@@ (similarly for %%bar%%). The entityencode is typically used to escape HTML content and replaces all occurrences of <, >, &, " and ' with the corresponding entities. The escapequotes is typically used to escape JavaScript content and escapes all backslash, single quote and double quote characters. These constructs require strict case-sensitive character string matching where the front part must exactly match "@@entityencode(" [or "%%entityencode("] and the back part must exactly match ")@@" [or "<code>)%%"].
content_element = element content {
content_content & content_attributes & foreign_attributes
}
content_content = (
plain_text_or_html
)
content_attributes = (
locid? & src? & type? & view?
)
The <content> element specifies the markup (usually HTML) that provides the widget's presentation.
The Ajax content and logic that initializes the widget and provides its visual rendering can be specified using a combination of declarative markup and/or procedural JavaScript logic. Declarative markup (usually HTML) is either in an external file (referenced by the src attribute) or placed within the <content> element. JavaScript can be located either as <script> elements within the <content> or contained within one or more separate <javascript> elements.
The following shows the options for the <content> element:
<widget ...>
...
<content src="<uri>" type="fragment|page" view="default|edit|help">
...widget markup (if 'src' attribute is not present)...
</content>
..
</widget>
Developers SHOULD bracket any markup that is not well-formed or properly-namespaced XML within a CDATA section (2008-04-22: Approved), as in:
<widget...>
...
<content>
<![CDATA[
...widget markup...
]]>
</content>
...
</widget>
The type attribute supports two values, fragment and page:
- If
type="fragment"(the default), then the content MUST be suitable for inclusion within an HTML<div>element. - If
type="page", then the content MUST be contained within an external file referenced by thesrcattribute. The referenced URL MUST produce a complete Web page (e.g., an HTML file that begins with an<html>element) and therefore suitable as the target for an HTML<iframe>element.
The src attribute, if present, specifies the URL of an external file that contains the content. 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. 2008-04-22: Draft consensus: the folder holding the widget xml file is the base URL. Also, no need to require support for xml:base.
The view attribute allows for multiple alternate <content> elements for a particular widget. The view attribute specifies a comma-separated list of named views. The following named views are defined by this specification:
- default - The default standard rendering for the widget when instantiated onto a Web page.
- edit - Custom user interface that provides a property editor for the widget's properties.
- help - Custom user interface that help information about the widget.
- insert - Custom user interface that should be shown when the widget is inserted. [lorihc 07.10.08] I thought we approved the addition of view="insert" a few meetings ago, but I just noticed it wasn't listed here. [jon 07.11.08] yes, lori, you are right. In a week or so, I'll remove these colored comments.
Additional information about the view attribute:
- Custom named views (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 named views is provided, then the given
<content>element must be used for all view modes that are named within the list. For example, ifview="default,edit", then this content must be used for both the default view and the edit view. - A
<content>element does not have aviewattribute is functionally equivalent to<content>element that hasview="default". - When attempting to find the appropriate content for a particular view mode, he user agent MUST use the first
<content>element whoseviewattribute matches that mode. - If none of the
<content>element match the current view mode, then the user agent should use the first<content>element (if any) that supports the default view.
JavaScript can be included within the <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>
The <contents> element
contents_element = element contents {
contents_content & contents_attributes & foreign_nodes
}
contents_content = (
descriptive_elements & inclusion_elements &
content_element*
)
contents_attributes = (
name?
)
The <contents> element holds zero or more <content> child elements.
The optional name attribute is meant to allow for providing a unique name for this particular <contents> element in case multiple <contents> are specified.
2008-07-08 Tentatively approved
Javascript elements
The <javascript> element
2008-02-21: Tentatively approved. We agreed on but have not had a second review yet of the '<javascript>' element.
javascript_element = element javascript {
javascript_content & javascript_attributes & foreign_attributes
}
javascript_content = (
text
)
javascript_attributes = (
location? & src?
)
The <javascript> element specifies a block of JavaScript logic that MUST be included in the runtime Web page for the widget to run.
The location attribute indicates when the JavaScript logic MUST be executed at runtime for the widget to run properly. Possible values are: The following writeups need to be reworded to take into account dynamic JavaScript insertion such as is found in some post-onload mashup scenarios, where what matters is the timing of SCRIPT tag insertion rather than the location of the script within the DOM tree.
- '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.
Any JavaScript logic that contains (or might contain) characters that are significant to XML parsers, such as < or < symbols, SHOULD be palced within a CDATA section, as in:
<javascript>
<![CDATA[
...JavaScript logic...
]]>
</javascript>
The <javascripts> element
javascripts_element = element javascripts {
javascripts_content & javascripts_attributes & foreign_nodes
}
javascripts_content = (
descriptive_elements & inclusion_elements &
javascript_element*
)
javascripts_attributes = (
name?
)
The <javascripts> element holds zero or more <javascript> child elements.
The optional name attribute is meant to allow for providing a unique name for this particular <javascripts> element in case multiple <javascripts> are specified.
2008-07-08 Tentatively approved
Require elements
The <require> element
require_element = element require {
require_content & require_attributes & foreign_nodes
}
require_content = (
(preload_element? & postload_element?) | text
)
require_attributes = (
copy? & includeRef? & library? & version? & name? & src? & target? & type
)
The <require> element describes Editor: clean this up a file or other asset on which this widget depends.
Here is an overview of the relevant parent/child element structure for <require> and its attributes:
<widget xmlns ="http://openajax.org/metadata" ...>
...
<requires>
<require [type=""] [library=""] [name=""] [version=""] [src=""]
[target=""] [includeRef=""] [copy=""]>
[<preload>
...JavaScript to execute before the asset is loaded...
</preload>]
[<postload>
...JavaScript to execute after the asset is loaded...
</postload>]
</require>
</requires>
...
</widget>
2008-07-22 Draft Consensus: 'target' works fine as is. Add a 'copy' attribute (boolean) with default=true that says whether the given <require> element should result in file copying. This is meant to take care of a situation where you copy a library but then also need to reference one of the files from that library in the HEAD. Then copy=false prevents the redundant file copy from occurring. Editor: Need to update the schema and the spec.
2008-08-12 Draft Consensus: Enable macro substitution on <preload> and &preload> and for inline <require>. <preload> and &preload> only available when there is a 'src' attribute. <require> can have inline content when type=javascript|css. If same resource is used by multiple widgets in the same frame, the asset is only included in the HEAD once. Editor: Need to update spec per these decisions. Need to talk about ordering of the elements within the resulting HTML file and what happens if two widgets in the same frame reference the same resource but in different orders (which produces undefined result). Guarantee that each preload will precede its resource and postload will succeed its resource. But no guarantee what order will result if multiple preloads exist in same frame for same asset. Need to include appropriate introductory text that the intent here is to initialize a widget and its properties.
The type attribute is an an enum: library | javascript | image | css | folder, where
- 'library' indicates an Ajax library. If provided, then attribute
srcmust also be provided. - 'javascript' indicates either a reference to a single external JavaScript file (if the
srcattribute is supplied) or an embedded snippet of JavaScript (i.e., the content of the<require>element, for when thesrcattribute is not supplied). A referenced JavaScript file should be converted into an HTML<script>element with asrcattribute 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
srcattribute is supplied) or an embedded CSS stylesheet (i.e., the content of the<require>element, for when thesrcattribute is not supplied). A referenced CSS stylesheet should be converted into an HTML<link>element. An embedded CSS stylesheet that 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
- 'image' indicates a single image file that is needed by the widget (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
- 'other' indicates a file that is needed by the widget which doesn't fall into any of the above types
The name attribute is used in conjunction with type="library" or the library attribute to provides a reference to an Ajax library. The value must be an Ajax library prefix that matches the library's entry within the OpenAjax Registry. For example, "dojo" or "jQuery".
The version attribute is used only for <require> elements that include a type="library" value or specify a library attribute, in which case version specifies the version number for the referenced JavaScript library. When used on the <require> element, only a single version number value is allowed; it is invalid to specify a version range. (See the section titled "Version number attributes" within the "Compatibility" chapter for the general rules on version number attributes.) 2008-08-19 Tentative resolution: Changed minVersion to version
The library attribute indicates that this resource represents an asset that is part of an Ajax library which (it is assumed) will be available to the widget due to other actions, such as a separate <require type="library"> element that results in the inclusion of the given Ajax library onto the Web site where the widget ultimately will be deployed. If the library attribute is specified, the asset referred to by this <require> element should not copied into the deployment target area; however, an entry to the asset should be included within the resulting HTML content (e.g., a LINK element for a CSS file, a SCRIPT element for a JavaScript file) in accordance with the value (or default value) of the <includeRef> attribute.
The src attribute holds the URL for the given resource, where relative URLs are relative to the location of the widget metadata file.
The target attribute holds the relative URL within the deployed package where the resource should be placed. Defaults to the same as 'src'.
The includeRef attribute is an enum that says whether the document needs to directly reference the given resource via insertion of a new element, such as inserting a <script> element into the document for a JavaScript resource. Possible values:
- 'auto' is the default. For 'css', 'xsl' and 'javascript', 'auto' has the same meaning as 'true'. For 'folders' and 'other', 'auto' has the same meaning as 'false'.
- 'true' says 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' says that tools MUST NOT insert an element into the document that references the given resource.
The copy attribute is a boolean that says whether the given asset should be copied into the deployment area. The default is "true". Need much more detail here. The main purpose of this attribute is when you have a major Ajax library and a widget only needs a few files, so you don't want to copy everything, but you do want to identify which asset belongs to which library so that asset sharing can happen between widgets.
Need to enhance and cleanup these writeups, particular regarding the 'library' attribute.
Tools MUST insert any new elements (e.g., a new <script> element) into the document in a manner such that the processing order for the new elements matches the order of the <require> elements. If a tool's workflow involves a preprocessing step on the web page content before the page is rendered, then typically within the preprocessing step the new elements (e.g., a new <script> element) will be inserted into the target web page's HEAD in the same order as the <require> elements.
Need to rewrite this paragraph to take into account dynamic script insertion, such as in various mashup scenarios
If the tool is unable to perform actions indicated by the a given <require> element, such as when insufficient attributes are provided (e.g., the <require> element has no attributes at all), then the tool SHOULD notify the user that it was unable to process the given <require> element.
Example adding the following to the requires section:
<requires>
<require src="YUI/build/button/assets/skins/sam/button.css" type="css" includeRef="true"/>
<require src="YUI/build/yahoo-dom-event/yahoo-dom-event.js" type="javascript" includeRef="true"/>
<require src="YUI/images/yahooIcon.gif" />
</requires>
Would generate the following in the head of the html document the widget is inserted in. Note there is no reference to the yahooIcon.gif file within the head of the html document. The assumption in the above example is that this image file is referenced indirectly by the other YUI assets that are used in this page.
<head>
<link href="YUI/build/button/assets/skins/sam/button.css" rel="stylesheet" type="text/css" />
<script src="YUI/build/yahoo-dom-event/yahoo-dom-event.js" type="text/javascript"></script>
</head>
The <requires> element
requires_element = element requires {
requires_content & requires_attributes & foreign_nodes
}
requires_content = (
descriptive_elements &
require_element*
)
requires_attributes = (
name?
)
The <requires> element holds zero or more <require> child elements.
The optional name attribute is meant to allow for providing a unique name for this particular <requires> element in case multiple <requires> are specified.
The <preload> element
preload_element = element preload {
preload_content & preload_attributes & foreign_attributes
}
preload_content = (
text
)
preload_attributes = (
empty
)
The <preload> element is an optional child of <require> and contains JavaScript logic to execute before the asset is loaded Editor: clean this up.
The <postload> element
postload_element = element postload {
postload_content & postload_attributes & foreign_attributes
}
postload_content = (
text
)
postload_attributes = (
empty
)
The <postload> element is an optional child of <require> and contains JavaScript logic to execute after the asset is loaded Editor: clean this up.
Widget APIs
Need to document how the "this" object works. The reference implementation now sets the "this" object to be the widget wrapper object, which is either an instance of jsClass (if specified) or the default widget wrapper class.
The use of widgets in a dynamic browser based mashup environment introduces the requirement for life cycle callbacks and property related callbacks on the gadgets.
Widget API
The process of dynamically adding and removing widgets to a page as well as loading and unloading the containing canvas are important events related to the functioning of widgets in a browser based live assembly canvas. Below are a list of APIS that a widget wrapper MUST implement.
What's the class name for the widget wrapper class? The text below says "OpenAjax.widgets.WidgetWrapper" but the reference implementation uses "OpenAjax.widget.Widget"./span>
<class name="OpenAjax.widgets.WidgetWrapper">
<methods>
<method name="getHubConnectionHandle">
<description>
Returns an object that is a connection handle to the OpenAjax Hub.
This connHandle can be used to invoke Hub 1.1 APIs, such as
connHandle.publish(), connHandle.subscribe() and connHandle.unsubscribe().
</description>
<returns datatype='Object' />
</method>
<method name="registerCallback">
<description>
Allows the registration of event listeners on the event target. An event target may be a node in a document, the document itself, a window, or an XMLHttpRequest.
</description>
<parameters>
<parameter name="type" datatype='String'>
<description>A string representing the event type to listen for.</description>
</parameter>
<parameter name="listener" datatype='Function'>
<description>The a Function object that is invoked when an event of the specified type occurs.</description>
</parameter>
</parameters>
</method>
<method name="unregisterCallback">
<description>
</description>
<parameters>
<parameter name="type" datatype='String'>
<description>A string representing the event type to listen for.</description>
</parameter>
<parameter name="listener" datatype='Function'>
<description>The a Function object that is invoked when an event of the specified type occurs. </description>
</parameter>
</parameters>
</method>
<method name='getAvailableDimensions'>
<description>
Returns the available width and height which the widget can request in the adjustDimensions method.
</description>
<return datatype="Object">
<description>
The return value is an object with a width and a height property representing the available pixels for use.
NOTE: If the container does not return a width or a height this signifies the widget can ask for whatever size it would like when using the adjustDimensions method.
</description>
</return>
</method>
<method name='getDimensions'>
<description>
Returns the current width and height in an Object which the widget occupies in the container.
</description>
<return datatype="Object">
<description>
The return value is an object with a width and a height property representing the current dimensions of the widget.
</description>
</return>
</method>
<method name='adjustDimensions'>
<description>
</description>
<parameters>
<parameter name="dimensions" datatype="Object">
<description>
This parameter is an object that contains a width and a height property which are integers. The width and height properties specify the requested with and height to adjust the widget to.
NOTE: If either property, width or height, are not present the dimension is not changed.
</description>
</parameter>
</parameters>
</method>
</methods>
<method name='getPropertyValue'>
<description>
Returns the current value of the requested property name.
</description>
<parameters>
<parameter name='name' datatype='String'>
This is the name of the property to retrieve
</parameter>
</parameters>
<return datatype='*'>
<description>The current value of the property named name</description>
</return>
</method>
<method name='setPropertyValue'>
<description>
Sets the current value of the requested property name to the value passed in via the value property.
</description>
<parameters>
<parameter name='name' datatype='String'>
This is the name of the property whose value is to be updated
</parameter>
<parameter name='value' datatype='*'>
The new value of the property
</parameter>
</parameters>
</method>
<method name="getPropertyNames">
<description>
Returns an array the property names on the gadget.
</description>
<returns datatype="[String]">
</method>
<method name="getSupportedViews">
<description>
Returns an associative array whose key is the value of the view attribute of a content node contained in the widget metadata and whose value is an instance of an
OpenAjax.widgets.View class.
</description>
<returns datatype="Object">
<description></description>
</returns>
</method>
<method name="requestNavigateTo">
<parameters>
<parameter name="view" dataType="OpenAjax.widgets.View">
<description>
The view parameter specifies the view instance to be displayed. If the container grants the request
a viewChange is triggered.
</decription>
</parameter>
</parameters>
</method>
</class>
The OpenAjax.widgets.View class is used to represent the various content type supported by a widget. Instances of the OpenAjax.widgets.View class are returned by the getSupportedViews method of the OpenAjax.widgets.WidgetWrapper class.
<class name="OpenAjax.widget.View">
</class>
Supported Callbacks
The WidgetWrapper support registering callbacks for a variety of lifecycle events. The list of event types is listed below:
| Event Type | Description | Event Object |
|---|---|---|
| load | This event name signals that the aggregation canvas has completely loaded all widgets on the page and that the event firing has been completed. | N/A |
| unload | This event name signals that the page is about to unload. | N/A |
| remove | This event name signals that the widget has been removed from the canvas. | N/A |
| insert | This event name signals that the widget has been inserted into the aggregation canvas. This event is only triggered once when the widget is placed onto the canvas, subsequent loading of the canvas does not trigger this event. | N/A |
| viewChange | This event signals that the view for the widget instance has changed (default, edit and help views). | The callback handler receives an Object with the following properties:
|
| resize | This event signals that the widget has just been resized by the container. | The callback handler receives an Object with the following properties:
|
Widget properties and widget constructor arguments
2008-08-13 JON: This section is out of date and might need to be removed and replaced by something very much different. It is significantly different than how the reference implementation works.
Widgets usually have a set of widget parameters that represent all of the various types of data fields that hold either the configuration information particular to a given widget instance or any run-time state information about that widget instance. The term "widget parameters" can be broken down into the following sub-categories:
- widget properties - Many widgets allow the author-time and/or run-time manipulation of various widget properties (e.g., size, color, instance-specific labels), often via some form of property inspector dialog.
- widget arguments - In the case where a widget has an associated JavaScript class, the logic that creates an instance of the widget often will pass a set of widget arguments to the widget's constructor.
Note that it is common that the list of widget properties and widget arguments overlaps to a large extent or perhaps may even be identical. One common workflow using IDEs is that an author-time dialog allows the developer to set widget properties, which are then passed as widget arguments to the widget constructor at run-time.
Because it is common that a given widget parameter will serve
as both a widget property (e.g., appear in a property inspector) and
as a widget argument (e.g., passed to the widget constructor),
OpenAjax Metadata unifies both into the the same elements,
<properties> and <property>, and
uses additional attributes on the <property> to indicate
whether the given parameter should not appear in a property inspector dialog.
When used within an OpenAjaxWidget.xml, the <properties> is a child of the <widget> element:
<widget xmlns="...">
...
<properties>
<property name="..." datatype="..." default="..."/>
<!-- etc. for other properties -->
</properties>
...
</widget>
</pre>
- Within an
OpenAjaxAPI.xml, as a child of the ??? element (<class> element?)
...example is not yet ready...
The formal definition of the <properties> and <property> elements can be found in the Properties and Datatypes chapter.
The spec needs to include a write-up on what parameters are passed to the constructor and how to handle 'default'. At the 2008-01-24 teleconference, here is what was discussed: "'required' means user SHOULD provide a value. Tools MAY choose to report an error if a value is not provided, but there MUST be an ultimate default for each datatype.". The logical conclusion of this approach is that each datatype needs to have an ultimate default, such as Number has ultimate default of zero, String has ultimate default of "", Array has ultimate default of [], Boolean has ultimate default of false, Object has ultimate default of null, Any has ultimate default of null. Not sure about RegExp, Date, and Error.
Subelements defined in other chapters
The following short sections list the subelements of <widget> that are defined in other chapters.
<author>/<authors>
Defined in the "Descriptive elements and attributes" chapter.
<available>
Defined in the "Compatibility" chapter.
<deprecated>
Defined in the " Compatibility" chapter.
<description>
Defined in the "Descriptive elements and attributes" chapter.
<enum>/<enums>
Defined in the "Datatypes" chapter.
<example>/<examples>
Defined in the "Descriptive elements and attributes" chapter.
<icon>/<icons>
Defined in the "Descriptive elements and attributes" chapter.
<include>
Defined in the "Inclusion" chapter.
<license>
Defined in the "Descriptive elements and attributes" chapter.
<option>/<options>
Defined in the "Datatypes" chapter.
<property>/<properties>
Defined in the "Properties" chapter.
<reference>/<references>
Defined in the "Descriptive elements and attributes" chapter.
<remarks>
Defined in the "Descriptive elements and attributes" chapter.
<title>
Defined in the "Descriptive elements and attributes" chapter.
<topic>/<topics>
Defined in the "Topics" chapter.
Other things that we might not have fully addressed
- Namespace extensibility and JSON - If someone uses an XML namespace to extend our metadata format, how would that map into JSON? 2008-05-13 Tentatively approved: Will express QNames for elements and attributes as JavaScript properties that contain a colon. This means you have to avoid dot notation and use foo["a:b"] syntax instead. Need to include section in spec about serialization into JSON. Still some open questions, such as what to do about xmlns attributes and whether it is necessary to distinguish between child elements and attributes. Probably best to start working on an XSLT from XML to JSON and see what is needed.
2008-07-08: Jon agreed to make proposals to resolve the open questions. Lori said that Dreamweaver sometimes does use the same name for elements and attributes. However, this might be a bit tricky. Researching what exists today for XML-to-JSON, nothing seems to do a truly robust job, such as addressing text nodes and possibilities of repeated elements in random order where order matters. But to address arbitrary XML to JSON will result in very ugly JSON. Therefore, maybe what we need are restrictions on custom XML subelements where we say that the custom subelement can only be a singleton, and we just store the equivalent of innerHTML for that singleton's attributes and children. - No support for xml:base - Need to include a note that xml:base is not supported
- Some other TODOs:
<!-- IBM identifies the issue of managing CSS from widget and parent container(s) -->
<!-- IBM identifies messaging for page to page, page to widget, and widget to widget -->
<!-- IBM identifies the need for predefined events -->
<!-- dijit integrates data binding via leverage of features such as dojo.data and dojo.connect -->
<!-- dijit has a few features for container elements. Phil Berkland agreed to make proposals during 2008-07-08 phone call-->
<!-- dijit allows for 'extension points' which pretty much are widget class methods,
but leverages Dojo's equivalence between events and functions -->
<!-- dijit has cross-widget features for 'value', 'disabled', 'intermediateChanges', 'tabindex',
'focus', 'getValue', 'setDisabled', 'setValue', 'undo', and 'onChange' -->
<!-- W3C has moveTo, moveBy, resizeTo, resizeBy APIs -->
