...

iWidget Specification v2.1

by user

on
Category: Documents
10

views

Report

Comments

Transcript

iWidget Specification v2.1
iWidget v2.1 Specification
1 of 35
file:///C:/iwidget-spec-v2.1.html
iWidget Specification v2.1
Abstract:
A number of browser based frameworks, each with their own component model, have been independently developed
to address the desire for highly interactive pages that aggregate pre-built components. This has resulted in a direct tie
of components to the framework defining the component model. This loss of interoperability between components and
frameworks introduces an unnecessary issue for users seeking to direct one another to useful components or seeking
to migrate their usage of a component to a different framework. This specification defines a simple component model
and how it can be extended such that interoperability is enhanced without the loss of more powerful extended features
some frameworks will choose to support.
Table of Contents
1 Introduction
2 Terminology
2.1 Defining terms
3 Design
3.1 Model
3.2 Concepts
3.3 Extensibility
3.4 Data Types
4 Base Types
4.1 ItemSet
4.2 ManagedItemSet
4.3 ShareableItemSet
5 iWidgets
5.1 iWidget attributes
5.2 iDescriptor
6 iContext Type
6.1 Event Types
6.1.1 iEventDescription Type
6.1.2 iEvent Type
6.1.3 Predefined iEvents
6.1.4 Event Flow and WIdget Lifecycle
7 IO Type
8 Constants
9 Declarative syntax
9.1 iWidget definition syntax
9.2 Including iWidgets
9.3 Initializing Shared ItemSets
10 Nesting iWidgets
11 Schema
Appendix A: Conformance statements
Appendix B: References
Appendix C: Contributors
6/7/2010 1:33 PM
iWidget v2.1 Specification
2 of 35
file:///C:/iwidget-spec-v2.1.html
1 Introduction
This specification defines a simple, extensible browser-based component model for frameworks presenting such
components to a user. We will call these components "iWidgets" though frameworks implementing this model may call
them by other names. There are a number of frameworks implementing this paradigm today with significant overlap in the
concepts embedded within their component models. Due to the lack of open standards, these shared concepts are all
surfaced in different manners, eliminating interoperability of the components between frameworks. This specification seeks
to remedy this situation by defining an open standard that surfaces these shared concepts as well as an extensibility model
for surfacing other more advanced concepts.
This specification accounts for the fact that varying technologies could be used for related server-side componentry and
actively seeks to be independent of any particular such technology, as is appropriate for such web-oriented standards. It is
also noted that a number of significant script libraries have become popular. This specification will not favor any such
library over another, but will seek to address any implementation concerns regarding implementing the standard by
leveraging these libraries.
Various places throughout this specification use "id" or "name" to provide matching either within the iWidget or across
multiple iWidgets. Unless specified differently, all such matching is case sensitive.
2 Terminology
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED,
MAY, and OPTIONAL in this document are to be interpreted as described in [RFC2119].
Locales are described/defined in [RFC3066] and its successors.
Items which have been deprecated from previous versions of the specification are indicated like this.
2.1 Defining terms
The following terms will be used with the supplied definitions:
page: The larger entity being composed for presentation to a user. This may include both display and non-display
items, each of which may come from a different source. The composition could be changed while it is being
presented (e.g. new items added to the composition) such that the exact definition of when a transition to a new
page occurs is a policy decision left to the implementation that is managing the composition.
iWidget: A browser-oriented component, potentially extending a server-side component, that provides either a
logical service to the page or a visualization for the user (normally related to a server-side component or a
configured data source).
iContext: Those components that provide the overall management of the page, or some portion thereof. This
includes any page level controls, page layout, coordination between the various items on the page and providing the
services defined in this specification to items on the page.
Encapsulation wrapper: The portion of the overall iContext that encapsulates a particular iWidget. Whether or
not this conceptual portion of the overall model results in any actual implementation depends in a large measure on
the implementation choices of the particular iContext. Examples where no explicit encapsulation layer is needed
include when each iWidget is loaded into its own IFrame or operating system process (e.g. XULRunner or other
Desktop platforms). Other implementation choices may result in some object at this level of the conceptual model
(e.g. merging iWidgets into a single page's DOM). Logically, all interactions of the encapsulated iWidget with the
iContext are provided to the iWidget by this component. All support provided by the iContext for assisting the
iWidget in dealing with its encapsulation issues are also provided by this component.
Markup fragment: A view that the iWidget produces for the user. While it is possible for an iWidget to
simultaneously present multiple fragments to the user, this specification only deals with how the primary view gets
incorporated into the overall page.
URI: Uniform Resource Identifiers are defined in [RFC2396] and its successors. Of particular note given the nature
of the environment, relative URIs (those not starting with a protocol scheme (such as http) and not starting with '/')
6/7/2010 1:33 PM
iWidget v2.1 Specification
3 of 35
file:///C:/iwidget-spec-v2.1.html
MUST be resolved relative to the widget definition URI. Full URIs (those starting with a '/' and relative URIs starting
with '..' are discouraged as they can easily reference outside of the deployment scope of the iWidget and thereby
be disallowed by some deployment topologies. For both relative and full URIs, [xml:base] can be used to override
the widget definition file location as the basis for resolving the URI.
alias: Various places in this specification define ids which are unique within an iWidget and provide the name by
which an item is known. There is a need for more unique identifiers which the iWidgets prefers to not use for
normal reference to the item. The concept of an alias is used to cover such use cases. This can be used to refer
to an alternate name for the item, including semantically equivalent items that are defined elsewhere (e.g. defined
by a different component).
3 Design
The major design goals for this specification are:
1. Simplicity: It should be simple to write a base level iWidget and adding more advanced features to it should be an
incremental process.
2. Extensibility: There needs to be a well-defined means for iWidgets to determine what optional feature an
iContext supports. There also needs to be a well-defined means for an iContext, which dynamically loads
advanced features as they are needed, to detect what features an iWidget can leverage.
3. Independence: The iContext requirements should be straight forward to implement using available script libraries,
browser extension frameworks or application frameworks. The iWidget should not need to know what technology
was used to implement the iContext.
4. Style: This specification will define both javascript (a.k.a. EcmaScript) interfaces and at least one declarative
markup that can be used to author iWidgets.
3.1 Model
The following diagram depicts how the various components defined in this specification relate to the user's visual page:
6/7/2010 1:33 PM
iWidget v2.1 Specification
4 of 35
file:///C:/iwidget-spec-v2.1.html
This specification seeks to enable the nesting of iWidgets, but only requires minor assistance of iContext
implementations (see Section 10).
3.2 Concepts
This specification uses the following concepts:
iWidget Attribute: The attributes of an iWidget typically control both its look/feel and data sources. An example
of the first would be an attribute named "bgColor" for controlling the background color of the iWidget. An example
of the later would be an attribute named "feedURL" for controlling the ATOM feed the iWidget connects to/renders.
There is a special class of attributes (i.e. idescriptor) described in [Section 5.2] that the iContext also needs to
understand, an example of which is "title".
Mode: This is a per iWidget piece of iContext managed state that tells the iWidget what type of markup to
generate for the user. Examples of the types include "view": normal user markup; "edit": markup for editing the
iWidget's attributes; and "help": markup providing the user with assistance in using the iWidget.
Coordination: This specification defines two means by which coordinated behavior can be achieved; namely:
1. Events: This mechanism provides a transitory means of sharing information. It is particularly appropriate
when either just a signal needs to be communicated (e.g. the "onLoad" event specified in [Section 6.1.3]) or
the information supplied in the payload has meaning only when the event is being distributed (e.g. the
"onItemSetChanged" event specified in [Section 6.1.3]). Information meaningful over a longer time period can
also be shared using this mechanism, but it loses the querability and tolerance to fault recovery that is
naturally available in the shared state mechanism.
2. Shared State: This mechanism provides means (i.e. ItemSet definition) that an iWidget can use to declare
state that is sharable with other components on the page. Whether or not they actually are shared will
depend on the ability of other components to consume them (either as state or via events) and any policy the
iContext applies to the sharing. An iWidget can become informed when other components change its
shared state by registering a listener on its ItemSets.
3.3 Extensibility
This specification reserves the term "iContext" as the base for its provided functionality. Those defining extensions to this
functionality SHOULD define the extension relative to this global term and identify the extension by naming it in the following
manner:
Use '_' as the first character as this will eliminate potential conflicts with later versions of this specification
Define a single object off iContext for holding all extensions defined by the same group.
Name the extension.
An example of using this methodology is; suppose the JSR 286 (portlet API v2) Expert Group wishes to define extensions
relative maintaining the Java portlet coding model as portions of both the portlet and portal components execute on the
client. One such extension might relate to the URLGenerator concept. This extension could be named:
iContext._jsr286.urlGenerator
3.4 Data Types
Data types are referenced by several places throughout the specification. To assist in resolving potential naming conflicts,
a serialized QName approach is used to identify the different categories of type enumerated below. Note that these names
are case sensitive. The following namespaced types are allowed in such places with earlier items in this list being
encouraged over later ones:
6/7/2010 1:33 PM
iWidget v2.1 Specification
5 of 35
file:///C:/iwidget-spec-v2.1.html
The following JavaScript defined types (namespace="text/javascript", transfer as Objects): "String",
"Number", "Boolean", "Date" and "Object". These will be the easiest to share across components and are
encouraged whenever appropriate. For example:
{text/javascript}Date
XML Schema types (namespace="http://www.w3.org/2001/XMLSchema", transfer as Strings): Note the
overlap of these datatypes with the JavaScript defined ones. Use of the JavaScript types where possible can
increase interoperability. For example:
{http://www.w3.org/2001/XMLSchema}anyURI
"json" (namespace="text/jav ascript", transfer as Strings): This value means the described value will be a
string suitable for using the Javascript eval method to generate an Object representation. While it should not be
necessary, an iWidget receiving such a type is encouraged to protect itself from the actual Object representation
being used rather than the string representation as this is a common error. For example:
{text/javascript}json
XML Schema defined types (or equivalent) (namespace=URI to load the schema, transfer as Strings):
There are a number of schema languages that could be used to define more complex types. A reference to the
machine readable type definition is required in these cases. For example:
{URI of the schema definition}your_type
6/7/2010 1:33 PM
iWidget v2.1 Specification
6 of 35
file:///C:/iwidget-spec-v2.1.html
4 Base Types
This specification uses the following types in various places. Note that the definitions for ItemSetDescription and
ItemDescription have been removed as a survey found they had not been useful.
4.1 ItemSet Type
This definition provides an interface to a simple abstraction of a datastore. This provides a base from which more
sophisticated data stores can be built.
module ItemSet
{
ItemSet
ItemSet
ItemSet
Object
Object
Object
ItemSet
ItemSet
ItemSet
ItemSet
String[]
String[]
setLocalizedItemValue(in String itemName, in Object value,
in String locale);
setItemValue(in String itemName, in Object value);
setItemValue(in String itemName, in Object value,
in boolean readOnly,
in String locale); /* Deprecated */
getLocalizedItemValue(in String itemName,
in String locale);
getItemValue(in String itemName);
getItemValue(in String itemName,
in String locale); /*Deprecated*/
removeItem(in String itemName);
removeLocalizedItemValue(in String itemName,
in String locale);
removeItemValue(in String itemName);
removeItem(in String itemName,
in String locale); /* Deprecated*/
getAllNames();
getLocalesWithValues(in String itemName);
}
Members:
setLocalizedItemValue: This method sets an item within the ItemSet, creating or replacing an existing entry as
needed. Since only one value is allowed for any one name/locale combination, the supplied value replaces any
existing value for the supplied name/locale. When successful, this method MUST return a handle to the ItemSet
while on failure it MUST return null.
setItemValue: This method sets an item within the ItemSet, creating or replacing an existing entry as needed.
Since only one non-localized value is allowed for any one name, the supplied value replaces any existing value for
the supplied name/locale. When successful, this method MUST return a handle to the ItemSet while on failure it
MUST return null.
getLocalizedItemValue: This method returns the value for the named item, in the specified locale, from the set.
On failure this method MUST return null.
getItemValue: This method returns the non-localized value for the named item from the set. On failure this method
MUST return null.
removeItem: Removes the entire named item from the set. When successful, this method MUST return a handle to
the ItemSet while on failure it MUST return null.
removeLocalizedItemValue: Removes the localized value for the supplied locale from the named item. When
successful, this method MUST return a handle to the ItemSet while on failure it MUST return null.
removeItemValue: Removes the non-localized value for the named item. When successful, this method MUST
return a handle to the ItemSet while on failure it MUST return null.
getAllNames: This method returns an array of strings, providing the name each item currently in the set. This
method returns the identifiers by which the iWidget references the items and not any aliases. If the set contains no
6/7/2010 1:33 PM
iWidget v2.1 Specification
7 of 35
file:///C:/iwidget-spec-v2.1.html
items, this method MUST return null.
getLocalesWithValues: This method returns an array of strings, each providing a locale where a value is defined.
If the set does not contain localized values for the named item, this method MUST return null.
4.2 ManagedItemSet Type
This definition provides the variant on the ItemSet interface that is used for those ItemSets which the iContext
manages. While systems providing persistence for such items may support localization, resolving these into the appropriate
locale for the user happens before being exposed through this interface and therefore all items are not localized in the API.
Items in a ManagedItemSet are scoped to the iContext encapsulation wrapper and the iWidget and the sharing concept
for the more general ShareableItemSets does not apply. Also, some items in the defined ManagedItemSets have
specialized events defined in [Section 6.1.3] (e.g. mode) and therefore do not generate the more general
onItemSetChanged event. Any persistence provided by the iContext SHOULD be done in a manner consistent with the
current mode. For "view" and custom modes, the persistence of a value SHOULD apply to the first supported from the
following list; (the current mode), personalize, edit, config.
module ManagedItemSet
{
ManagedItemSet
setItemValue(in String itemName, in Object value);
Object
getItemValue(in String itemName);
ManagedItemSet
removeItem(in String itemName);
String[]
getAllNames();
boolean
isReadOnly(in String itemName);
String
boolean
addListener(in Function listener);
removeListener(in Function listener | String listenerID);
void
void
save(in Function callbackFn /*optional*/); /*Deprecated*/
commit(in Function callbackFn /*optional*/);
}
Members:
setItemValue: This method queues setting an item within the ManagedItemSet, creating or replacing an existing
entry as needed, with the actual setting/processing of the change happening when commit() is invoked. Since
only one value is allowed for any one name, the supplied value replaces any existing value for the supplied name.
Note that while an arbitrary Object can be specified for the value, the iContext will only persist data fields and
therefore any functions defined on the Object will be lost. It is also likely that any specific type used will also be lost
across the persistence operation. As ManagedItemSet are controlled by the iContext, some items MAY be read
only to the iWidget. When successful, this method MUST return a handle to the ManagedItemSet while on failure it
MUST return null.
getItemValue: This method returns the value for the named item from the set. On failure this method MUST return
null.
removeItem: This method removes the named item from the set. When successful, this method MUST return a
handle to the ManagedItemSet while on failure it MUST return null.
getAllNames: This method returns an array of strings, providing the name each item currently in the set. If the set
contains no items, this method MUST return null.
isReadOnly: This method returns a boolean indicating whether or not the item specified by the supplied name can
be modified by the user (or code acting on their behalf).
addListener: This method returns "listenerID" if the request to add a listener to changes in the ManagedItemSet
was successful and null if the request fails. The result of this invocation is immediately in effect. When a
ManagedItemSet undergoes changes (new items, changed values, etc), it will source an onItemSetChanged event
to all registered listeners other than the iWidget which originated the change. Note that the signature for such a
listener is:
module
{
6/7/2010 1:33 PM
iWidget v2.1 Specification
8 of 35
void
file:///C:/iwidget-spec-v2.1.html
listener(in iEvent ev);
}
removeListener: This method returns a boolean indicating whether or not the request to remove a listener was
successful. The result of this invocation is immediately in effect. Either the original function handle
(Deprecated) or the "listenerID" returned by the invocation of addListener can be supplied to reference the
listener to remove.
save (Deprecated - use commit): This method requests the iContext persist the current state of the
ManagedItemSet. The iContext MAY also choose to persist the ManagedItemSet at times other than when
iWidgets invokes this method. The iContext will need to serialize any JavaScript Objects used for the value of
items within the ManagedItemSet and is likely to just recursively walk the data fields of such an Object to achieve
this serialization. This method MAY operate asynchronously. The iContext MUST invoke any supplied callbackFn
upon completion of the save attempt. The signature for the function is:.
function(in String managedItemSetName, in boolean success);
commit: This method requests that queued changes be processed. This includes simultaneous changes to mulitple
items (e.g. change mode and windowState) and any persistence or other propagation of the values. The iContext
MAY also choose to persist the ManagedItemSet at times other than when iWidgets invoke this method. The
iContext will need to serialize any JavaScript Objects used for the value of items within the ManagedItemSet and
is likely to just recursively walk the data fields of such an Object to achieve this serialization. This method MAY
operate asynchronously. The iContext MUST invoke any supplied callbackFn upon completion of the commit
attempt. The signature for a function to receive information about the success/failure of this request is:
function(in String managedItemSetName, in boolean success);
4.3 ShareableItemSet Type
This definition provides a variant on the ItemSet with some restrictions and extensions to better cover sharing situations,
particularly across IFrame boundaries. Either the id or alias can be used as the name to reference an item in a
ShareableItemSet. Any item created using the following methods will specify just one identifier, which will then be used
for the value of the id.
module ShareableItemSet
{
ShareableItemSet
setItemValue(in String itemName, in String value);
String
getItemValue(in String itemName);
ShareableItemSet
removeItem(in String itemName);
String[]
getAllNames();
String
boolean
addListener(in Function listener);
removeListener(in String listenerID);
void
commit(in Function callbackFn /*optional*/);
}
Members:
setItemValue: This method queues setting an item within the ShareableItemSet, creating or replacing an existing
entry as needed. The actual setting to the shared set happens when commit is invoked. Since only one value is
allowed for any one name, the supplied value replaces any existing value for the supplied name. If there is no item
corresponding to the supplied name, an item is created with the supplied name being used for the id. When
successful, this method MUST return a handle to the ShareableItemSet while on failure it MUST return null.
getItemValue: This method returns the value for the named item from the set. On failure this method MUST return
null.
removeItem: This method removes the named item from the set. When successful, this method MUST return a
6/7/2010 1:33 PM
iWidget v2.1 Specification
9 of 35
file:///C:/iwidget-spec-v2.1.html
handle to the ShareableItemSet while on failure it MUST return null.
getAllNames: This method returns an array of strings, providing a name for each item currently in the set. If the set
contains no items, this method MUST return null.
addListener: This method returns a listenerID corresponding to this request. This value can be supplied to the
removeListener method to stop processing change notifications with the supplied method. The result of this
invocation is immediately in effect. When the ShareableItemSet undergoes changes (new items, changed values,
etc), it will source an onItemSetChanged event to all registered listeners other than the iWidget which originated
the change. These listerners need to have been connected up to the right scope (for example, using the equivalent
of dojo.hitch) prior to being supplied as the listening function. The signature for the listener is:
module
{
void
}
listener(in iEvent ev);
removeListener: This method returns a boolean indicating whether or not the request to remove the listener was
successful. The result of this invocation is immediately in effect.
commit: This method requests that queued change events be distributed to listeners. The iContext is allowed to
queue changes relative to any underlying structure where they will be visible to other components and thereby
change notifications until this method is invoked. In general, such queueing can improve performance significantly
when IFrame boundaries have to be crossed to apply the changes. This method MAY operate asynchronously. The
iContext MUST invoke any supplied callbackFn upon completion of the commit attempt. The signature for a
function to receive information about the success/failure of this request is:
function(in String shareableItemSetName, in boolean success);
6/7/2010 1:33 PM
iWidget v2.1 Specification
10 of 35
file:///C:/iwidget-spec-v2.1.html
5 iWidgets
This specification does not require iWidgets to conform to a specific interface. All iContext initiated interactions with the
iWidget are modeled either as an event or are mediated by an ItemSet. Of particular concern are the customization
attributes of the iWidget. When managed by the iContext, these are modeled as an ManagedItemSet. When managed
directly by the iWidget, these are unknown to the iContext.
5.1 iWidget attributes
We use the term "iWidget attributes" to refer to the customization points of the iWidget. These are often exposed to the
user to provide reasonable default behavior (e.g. an iWidget that displays weather for the US might define an attribute for
'zipcode' and then use it as the default location for the displayed weather forecast). The persistence and lifecycle for these
attributes are managed by the iContext and therefore they are exposed through a ManagedItemSet. The actual items
within this set are determined entirely by the iWidget.
5.2 iDescriptor
To increase interoperability and eliminate potential conflicts with attribute names, this specification defines those
attribute-like items that the iContext needs to understand in a special ManagedItemSet called idescriptor. Requests
for items within this set that do not have a value will return null as is normal for a ManagedItemSet. The iContext
SHOULD NOT persist idescriptor items. Note that the definition for globalAttributes and size have been removed
as a survey found they had not been useful.
Note: A number of the items in this ManagedItemSet have specialized events defined in [Section 6.1.3] (e.g. mode) and
therefore do not generate the more general onItemSetChanged event. These specialized events have been defined for
frequently occuring use cases to cause the iContext to directly invoke the iWidget method handling that type of update.
The following names are defined for read only items in this ManagedItemSet:
1. displayLocale: The locale appropriate for those items the iWidget displays to the user in order to do things like
properly formatting dates and currency. In determining this value, the iContext will take into account the locales for
which the iWidget has declared it has messages, the locale in use in the overall environment (e.g. a web page) and
the user indicated locale preferences. The value for this item is determined by the iContext and it is read only for
iWidgets.
2. messageLocale: The locale, from the set the iWidget has declared are supported, for displaying messages to the
user. This could be used, for example, to load the proper message bundle for localizing the strings in the user
interface. In determining this value, the iContext will take into account the locales for which the iWidget has
declared it has messages, the locale in use in the overall environment (e.g. a web page) and the user indicated
locale preferences. The value for this item is determined by the iContext and it is read only for iWidgets.
3. author: The name(s) of the iWidget author(s). This item can be set in the iWidget definition.
4. email: The email(s) of the iWidget author(s). This item can be set in the iWidget definition.
5. website: A URI for the iWidget author's website. This item can be set in the iWidget definition.
6. version: The version number of the iWidget implementation in the form of n.m where 'n' is the major version
number and 'm' is the minor version number. This item can be set in the iWidget definition.
The following names are defined for potentially writeable, subject to iContext policy, items in this ManagedItemSet.
Writing these items provides the means to request a change in the item. Some failure reasons (e.g. not authorized to
changed the item) can result in null being returned from the invocation, but a callback function has to be provided to learn if
the requests passing any initial checks was honored or not. The item names are:
1. title: This attribute suggests a title that could be used in any decoration (e.g. titlebar) around the iWidget. This
item can be set in both the iWidget definition and the microformat placing an iWidget instance on a page.
2. name: A short name for the iWidget. This is likely to be used if the iWidget is offered on a pallette of iWidgets
for placing on the page. This item can be set in both the iWidget definition and the microformat placing an iWidget
instance on a page.
3. description: A longer description (markup allowed) of the iWidget, suitable for displaying on a tooltip. This item
6/7/2010 1:33 PM
iWidget v2.1 Specification
11 of 35
file:///C:/iwidget-spec-v2.1.html
can be set in both the iWidget definition and the microformat placing an iWidget instance on a page.
4. defaultHeight: For those iWidgets needing a specified size, this item provides a means to inform the iContext
of a preferred initial height. This item does not get updated by the iContext and therefore any value will just be that
set by the iWidget. This item can be initialized in both the iWidget definition and the microformat placing an
iWidget instance on a page.
5. defaultWidth: For those iWidgets needing a specified size, this item provides a means to inform the iContext
of a preferred initial width. This item does not get updated by the iContext and therefore any value will just be that
set by the iWidget. This item can be initialized in both the iWidget definition and the microformat placing an
iWidget instance on a page.
6. mode: The mode saying what markup the iWidget SHOULD be currently displaying. Writing this item provides the
means to request a change in mode. After the iContext processes a change in the mode for an iWidget, the
on{mode} event is generated to inform the iWidget of the need to render itself in the new mode. See [Section 8] for
predefined values for mode.
7. windowState: The windowState indicates what fraction of the display is allocated to the iWidget. After the
iContext processes a change in the windowState for an iWidget, the onWindowStateChanged event is
generated to inform the iWidget of the need to rerender itself. See [Section 8] for predefined values for
windowState.
8. availableMessageLocales: A space delimited list of the locales for which the iWidget has localized messages
for displaying to the user. This item can be set in the iWidget definition.
9. icon: URI of an image could be displayed in places such as title bar decoration, recommended size is 20 pixels by
20 pixels. This item can be set both in the iWidget definition and the microformat placing an iWidget instance on a
page.
10. thumbnail: URI of an image could be displayed in places such as a gallery of available iWidgets, recommended
size is 120 pixels by 60 pixels. This item can be set both in the iWidget definition and the microformat placing an
iWidget instance on a page.
The title, name, and description items can be localized in both the definition ([Section 9.1]) and microformat ([Section
9.2]) syntax.
6/7/2010 1:33 PM
iWidget v2.1 Specification
12 of 35
file:///C:/iwidget-spec-v2.1.html
6 iContext Type
This interface defines methods that the iWidget can use to interact with the iContext. Note that they will in general be
provided by some wrapper type in order to specialize the functionality to the iWidget as part of proper encapsulation
support.
module iContext
{
ManagedItemSet
ManagedItemSet
ManagedItemSet
ItemSet
getiWidgetAttributes();
getUserProfile();
getiDescriptor();
getItemSet(in String name, in Boolean private /*Deprecated*/);
ShareableItemSet getShareableItemSet(in String name);
String
getWidgetId();
Object
iScope();
String
void
processMarkup(in String markup);
processiWidgets(in DOMNode node);
Element
Element[]
Element
getElementById(in String id);
getElementByClass(in String className);
getRootElement();
void
requires(in
in
in
in
in
iEvents
IO
xml
iEvents;
io;
xml;
String globalid,
String version, /*optional*/
String uri,
Function callbackFn, /*optional*/
String mimeType /*optional*/ );
}
Members:
getiWidgetAttributes: This method returns the ManagedItemSet that provides access to the iWidget's
customization attributes. If there is no ManagedItemSet related to the iWidget's customization attributes, this
method MUST create an empty set and return it.
getUserProfile: This method returns the ManagedItemSet that provides access to the user's profile data. If there
is no ManagedItemSet related to the user's profile, this method creates an empty set and returns it. If access to
the user's profile is denied, this method returns null. While it is a matter left to the iContext's policy, it is likely that
most items within the user profile will be marked as "readOnly".
getiDescriptor: This method returns the ManagedItemSet that provides access to attributes that both the
iContext and the iWidget need to understand. If there is no ManagedItemSet related to the iWidget's
descriptive items this method MUST create an empty set and return it.
getItemSet: This method returns an ItemSet corresponding to the requested name, using either the id or alias.
If it does not already exist, an ItemSet will be created with the supplied name used as the id. If access to the
desired ItemSet is denied or the ItemSet can not be created, null is returned.
getShareableItemSet: This method returns an ShareableItemSet corresponding to the requested name, using
either the id or alias. If it does not already exist, a ShareableItemSet will be created with the supplied name
used as the id. If access to the desired ShareableItemSet is denied or the ShareableItemSet can not be
created, null is returned.
getWidgetId: This method returns the unique identifier for this instance of the iWidget in the current evironment
(usually a web page).
iScope: This method returns an instance of type Object which was initialized prior to the loading of the iWidget
(either as a generic Object or an instance of the encapsulation Object referenced by declarative means (see
6/7/2010 1:33 PM
iWidget v2.1 Specification
13 of 35
file:///C:/iwidget-spec-v2.1.html
Section 9)). Its purpose is to support proper encapsulation of the iWidget's assets (variables and methods) such
that multiple instances of the iWidget can be loaded into a single page's DOM without stepping on each other.
processMarkup: This method requests the iContext to process the markup such that it can be inserted into the
iWidget's markup and properly interact with the page (i.e. logically extends the processing related to loading the
page). Where, when and how the markup is inserted into the page is the responsibility of the iWidget. This method
does not do any rendering of the markup, such as processing script or style tags, as that is domain of the user
agent when the markup is inserted into the page. On success this method MUST return the processed markup while
on failure it MUST return null.
processiWidgets: This method requests the iContext to process the subtree under the supplied node for the
purpose of resolving and instantiating any referenced iWidgets and their properties such as wires. This method
takes care of the lifecycle and attributes of any given iWidget that resides within the subtree. It is allowed to call
this method multiple times through the calling iWidget's lifecycle. The lifecylce for iWidgets contained in the
subtree for instance includes calling onLoad and onUnload when appropriate, i.e. onUnload would be called in case
an iWidget stops being referenced within the subtree.
getElementById: This method provides the same semantics as the DOM method by the same name with the
distinction that this method will restrict the search to the iWidget's markup rather than the entire page.
getElementByClass: This method returns an array of Elements within the iWidget's markup which have the
supplied value as one of those specified by the Element's "class" attribute.
getRootElement: This method returns the iContext supplied element containing the content for the current mode
of the iWidget such that the iWidget can easily do things such as searching its own markup.
requires: This method provides the means for an iWidget to dynamically declare a dependency on a resource,
including optional iContext functionality, such as:
io
xml
For these items, no uri should be specified as the iContext is responsible for loading any dynamic portions of
itself. In addition, sharable resources (e.g. "dojo.js") can be loaded just once for all iWidgets using the resource via
this method. As there may be issues with having mulitple versions of such resources loaded at the same time, this
method includes a version parameter to inform the iContext of any version dependency. If no value is supplied for
the required version, the iWidget author in indicating that any version is acceptable. As iContexts are likely to do
such dynamic loads in an asynchronous manner, the callbackFn provides a means for the iWidget to become
aware that either the required resource is available or that attempt to load the resource failed (indicated by the
supplied statusCode). It should be noted that the callbackFn may be invoked prior to the return from this request,
especially for those resources already loaded. The callbackFn signature is of the form
function(in
in
in
in
String globalid,
String id,
String uri,
int statusCode /*see Section 8*/ )
iEvents: This field contains an object that provides access to event services in a manner allowing the iWidgets on
the page to interact in a loosely coupled manner while also providing control to whomever is defining the overall
page/application. Types related to eventing are defined in a separate section below.
io: This optional field contains an object that provides access to io services in a manner allowing the page as a
whole to remain consistent, particularly in the face of server-side coordination between related application
components.
xml: This optional field is a placeholder for future definitions providing explicit support for XML-oriented processing.
This version of the specification provides no such definitions, but they are expected in future versions.
Extensions supported by more advanced iContexts SHOULD follow the pattern (defined in Section 3.3) used for the
iEvents and IO portions of these definitions. This allows iWidgets to determine the support for a "foo" extension defined
by a group named "bar using a construct of the form:
var fooSupported = (iContext._bar && iContext._bar.foo);
6/7/2010 1:33 PM
iWidget v2.1 Specification
14 of 35
file:///C:/iwidget-spec-v2.1.html
6.1 iEvents Types
This section contains the definition of the types involved in event distribution. The model used for event distribution has the
iWidget declare what events it can both originate and consume and the iContext then wires these events together in
whatever manner it chooses (examples include a backplane design that simply connects all matching events and an explicit
wiring model where the page author selects the event flows that are enabled). In addition to distributing the events
between iWidgets (or other items on the page), the iContext MAY choose to provide a mapping between certain
events. This is frequently useful when two distinct event definitions contain the same semantic fields, but with different
names at either the field or event level (or both).
Note that this interface supports the dynamic definition of events. The iContext MAY choose to persist these definitions
and SHOULD do any such peristence in a manner consistent with the current mode. For "view" and custom modes, the
persistence of a value SHOULD apply to the first supported from the following list; (the current mode), personalize, edit,
config.
The iEvents type has the following signature:
module iEvents
{
void
fireEvent(in String name, /* event name, preferrably a serialized QName *
in String type, /* optional reference to type,
preferrably a serialized QName */
in Object payload /* optional ... the event's data */);
boolean
boolean
setEvent(in iEventDescription eventDesc);
setEvents(in iEventDescription[] eventDescs);
boolean
boolean
removeEvent(in String eventName);
removeEvents(in String[] eventNames);
iEventDescription[] getEvents(in Object condition);
iEventDescription
createEventDescription(in JSON descriptionItems);
}
Members:
fireEvent: This method informs the iContext that distributing an event of the type described by the parameters is
appropriate. See [Section 3.4] for a discussion on preferred types. Whether of not such an event will actually be
created and distributed will depend on whether the iContext has any handlers for that event.
setEvent: This method informs the iContext of an event of interest to the iContext. If the supplied event name is
already known to the iContext, the existing information is overwritten with the information supplied on this
invocation. Details within the supplied iEventDescription include whether this interest is related to publishing or
handling the event (or both). The returned boolean indicates whether or not the request added the described event
to the set related to this iWidget. When setting multiple events, it is preferrable to use the setEvents method as
the iContext could be persisting the definitions per invocation. If successful, this method immediately exposes the
event definition for wiring and distribution.
setEvents: This method is logically equivalent to calling setEvent for each of the members in the supplied array.
Using this method will potentially allow optimizations to occur within the iContext. The returned boolean indicates
whether or not the request added all the described events to the set related to this iWidget. In the case of some
failures, getEvents can be used to determine which were successfully added.
removeEvent: This method requests the named event be removed from the set of events related to this iWidget.
Invoking this method will allow any persistence of the information to be properly cleaned up. If successful, this
method immediately removes the event definition and any wires for distributing it relative to this iWidget.
removeEvents: This method requests the set of named event be removed from the set of events related to this
iWidget. The returned boolean indicates whether or not the request removed all the described events from the set
related to this iWidget. In the case of some failures, getEvents can be used to determine which were successfully
removed. Invoking this method will allow any persistence of the information to be properly cleaned up.
getEvents: This method queries the iContext for events defined by this iWidget which match the supplied
conditions object. The conditions object is normally supplied as a JSON string specifying a set of field names/values,
but can also be a javascript object where the fields/values are set programatically. The field names specify which
6/7/2010 1:33 PM
iWidget v2.1 Specification
15 of 35
file:///C:/iwidget-spec-v2.1.html
items are required to match and the supplied value for each field is used to evaluate that a particular event matches
the conditions. Field names within the conditions object are first matched against the top level iEventDescription
fields. If no top level match is found, then a field name match is sought from the localized attribute set. If the
conditions object defines a "locale" field, then its value will be used to restrict matching against the attribute set.
createEventDescription: This method is the factory for the iContext implementation of the iEventDescription
type. The supplied JSON is used to supply values consistent with what can be read from a widget definition as
defined in [Section 9.1] to create an event description, namely;
{
name: "",
alias: "",
type: "", /*See [Section 3.4]*/
lang: "",
handlingFn: "" | Function,
isHandled: true | false,
isPublished: true | false,
localizedAttributes: [<locale>: {<attName>: <attValue>}, ...],
attributes: {<attName>: <attValue>, ... }
}
While the name is the unique identifier within this structure, the iContext will treat a supplied alias as providing
this value if name is missing.
Note that the separate "attributes" member provides the means for defining non-localized values.
The iWidget SHOULD use this factory when needing to define additional events.
The above provides an ability for an iWidget to create an event description using advanced features such as anonymous
functions and a multiplicity of attributes (both localized and not) which the iContext will not always be able to persist. A
mixed model for re-establishing these events is therefore used; the iContext will persist what information it can and the
iWidget is responsible to query/update partial iEventDescriptions in a manner such as:
/* get handled events without a handler */
var partialEventDescs = getEvents({handlingFn: null, isHandled:true});
for (i=0; i<partialEventDescs.length; i++) {
/* update the returned iEventDescriptions */
}
setEvents(partialEventDescs);
Typically such processing will happen in the iWidget's onLoad handler, but it is allowed anywhere in the iWidget
lifecycle as the availability of the information to reset these fields could occur at other times.
6/7/2010 1:33 PM
iWidget v2.1 Specification
16 of 35
file:///C:/iwidget-spec-v2.1.html
6.1.1 iEventDescription Type
This object contains various pieces of information describing an event.
module iEventDescription
{
String
name;
String
alias; /* optional */
String
type;
String
lang; /* optional */
String
handlingFn;
boolean isHandled; /* default is false */
boolean isPublished;
String
getDescription(in String locale); /* deprecated */
// new methods
void
setAttribute(in String name, in String value,
in String locale);, /* create or overwrite */
String
getAttribute(in String name, in String locale);
}
Members:
alias: An alternate name for the event, such as a semantically equivalent event defined elsewhere.
name: The name of the event, represented in the declarative markup as the "id", preferrably a QName serialized as
"{URI}localName"
type: The type of any payload. If this is set to null, no information is being provided. This is useful for both simple
signals or events with opaque payloads (i.e. a minor attempt at making it private). See [Section 3.4] for a discussion
on preferred types.
lang: The default locale for use on any localized items when a locale is not provided.
getDescription (Deprecated - use getAttribute): This method returns a user-oriented description (markup
allowed) of the event in the requested locale. If no locale is supplied, the default locale of the iWidget is used (with
"en" being the default iWidget locale). The description is likely to be displayed when a user is wiring event flow
between iWidgets. This has been deprecated in favor of the more general style of localizing values provided by the
attribute mechanism.
handlingFn: Used only when describing what events an iWidget can handle. This provides the name of a callback
function with the following signature and no return value.
function(ievent)
isHandled: The isHandled and isPublished fields provide a convenient means to indicate the directionality of the
event flow. The default value for isHandled is false, i.e. the iWidget is not set up to receive and process the
defined event. The value for isHandled is considered to be true if a handlingFn is supplied regardless of the
supplied value. This combination supports deferred definition of the actual handling function while informing any
tooling that the event can be handled by the iWidget.
isPublished: The isHandled and isPublished fields provide a convenient means to indicate the directionality of
the event flow. The value for isPublished is considered to be true if neither isPublished nor isHandled are
specified, i.e. the iWidget might publish the defined event.
setAttribute: This method provides a means for the iWidget to store localized values. If the attribute name
specified does not exist, it will be created. If the attribute name already exists, the supplied value will replace any
value already stored for the supplied locale. See [Section 8] for reserved attribute names.
getAttribute: This method provides a means for the iWidget to retrieve previously stored localized values.
Those values may have been supplied either in declarative form or by previous invocations of setAttribute. If no
value has been stored for the name and locale requested, null is returned. See [Section 8] for reserved attribute
names.
6/7/2010 1:33 PM
iWidget v2.1 Specification
17 of 35
file:///C:/iwidget-spec-v2.1.html
6.1.2 iEvent Type
This type carries various pieces of information when an event flows at runtime.
module iEvent
{
String name;
String type;
Object payload;
String source;
}
Members:
name: The name used by the receiving iWidget for the event, preferrably a QName.
type: The type of any payload. If this is set to null, no information is being provided. This is useful for both simple
signals or events with opaque payloads (i.e. a minor attempt at making it private)
payload: The data, if any, being provided by the source of the event.
source: The iWidget supplied name for the source iWidget. Note that some iContexts will consistently null this
field for security reasons.
6.1.3 Predefined iEvents
In order to enhance interoperability. the following events are defined by this specification. By convention, iWidget provided
methods with the same name as one of these events will be considered the handler for that event unless the iWidget
explicitly specifies a different event handler. The iContext MUST inspect iWidgets once they are fully loaded and
support this pattern for default mapping of event handlers to the predefined events.
onLoad: This event signals that the iWidget has finished loading, including any invocations of requires() (or the
declarative equivalent iw:resource). As a simple notification, it carries no predefined payload. The iContext
MUST support the "onLoad" event. This event is sourced only by the iContext.
onUnload: This event signals that the iWidget is about to be unloaded (commonly due to a page transition). This
notification is intended to allow the iWidget to store any transient data such that it can be recovered by future uses
of the iWidget. As a simple notification, it carries no predefined payload. The iContext MUST support the
"onUnload" event. This event is sourced only by the iContext.
onModeChanged (Deprecated, use on{mode} event and mode item within the idescriptor
ManagedItemSet): This event signals that the mode for the iWidget has changed. In JSON syntax, this event's
payload is:
{
"newMode": ""
}
This event is sourced only by the iWidget.
onWindowStateChanged: This event signals that the windowState for the iWidget has changed. In JSON syntax,
this event's payload is:
{
"newWindowState": "",
"oldWindowState": "" /* null if there is no previous windowState */
}
This event is sourced only by the iContext.
onSizeChanged This event signals that the size for displaying the current mode of the iWidget has changed. In
JSON syntax, this event's payload is:
{
"newWidth": "",
"newHeight": ""
6/7/2010 1:33 PM
iWidget v2.1 Specification
18 of 35
file:///C:/iwidget-spec-v2.1.html
}
This event is sourced only by the iContext.
onNavStateChanged: This event can be generated by either the iWidget, supplying a new value for its
"navigational state", or by the iContext, signaling that some user action (e.g. activating a previously bookmarked
page) has changed the iWidget's "navigational state" to a previously defined value. "Navigational state" is defined
to be that portion of the iWidget's state that is required to rerender the current view at some later point in time
(e.g. a weather iWidget might define some state that allows the user to return to a detail view of the weather
forecast for a particular location). The payload of this event is the string representation of the "navigational state".
How the actual state is serialized/deserialized relative to this string is the responsibility of the iWidget author. This
event can be sourced both by the iContext and iWidget.
onItemSetChanged: This event signals that a set of Items within an ItemSet has changed (i.e. an invocation of
commit() has caused changes to be processed and distributed) and carries the type of change within the event
payload. This event is only delivered to those iWidgets having registered a listener with the ItemSet the event
references, excluding the iWidget which originated the change. In JSON syntax, this event's payload is:
{
itemSetName: "{setName}",
alias: "{alias}",
"changes": [{
id: "{itemName}",
alias: "{alias}",
changeType: "{changedValue | newItem | removedItem}",
oldVal: "{oldValue}",
newVal: "{newValue}" }]
}
where:
itemSetName provides the id of the ItemSet that has changed.
alias provides the alias, if once is defined, for the ItemSet that has changed.
changes is an array carrying the set of changes that have occurred to the ItemSet, each member of which
is an object with the following fields:
itemName is the id of a single item that has changed.
alias provides the alias, if one is defined, for the item that has changed.
changeType is one of:
"changedValue": The value for an item has been changed.
"newItem": A new item has been added to the set.
"removedItem": An item has been removed from the set.
oldVal carries the previous value for this item.
newVal carries the new value for this item.
This event is sourced only by the iContext.
onRefreshNeeded: This event signals that the iContext considers the iWidget to be stale. Examples when this
state could occur include when server-side coordination between components resulted in the component behind the
iWidget to receive some coordination activity. Since the iContext can be aware of such states, but has no
knowledge of the impacts on what the iWidget is presenting to the user, it generates this event to signal the
situation to the iWidget. This event is sourced only by the iContext. How the iContext becomes aware that this
event needs to be distributed is an implementation-specific question outside the scope of this specification.
onNewWire: This event signals that the event to which it is related has a new listener that it has been "wired" to.
This event is distributed to both ends (source and target) of the new wire. In JSON syntax, this event's payload is:
{
"targetWidget": {targetWidgetInstanceID},
"targetEvent": {targetEventName},
"sourceWidget": {sourceWidgetInstanceID},
"sourceEvent": {sourceEventName}
}
This event is sourced only by the iContext.
onRemoveWire: This event signals that the event to which it is related has a listener removed. This event is
distributed to both ends (source and target) of the removed wire. In JSON syntax, this event's payload is:
6/7/2010 1:33 PM
iWidget v2.1 Specification
19 of 35
file:///C:/iwidget-spec-v2.1.html
{
"targetWidget": {targetWidgetInstanceID},
"targetEvent": {targetEventName},
"sourceWidget": {sourceWidgetInstanceID},
"sourceEvent": {sourceEventName}
}
This event is sourced only by the iContext.
on{mode}: This event requests that the iWidget render itself in the indicated mode. Common causes which trigger
this event are transitions to a new mode (either using the controls provided by iContext or due to a request from
the iWidget) and loading/reloading of the iContext environment. This pattern (the name of the mode used as part
of the event name (first letter upper cased)) provides a simple means for the iWidget to do mode dependent
processing. This event is sourced only by the iContext. In JSON syntax, this event's payload is:
{
"oldMode": "" /* null if there is no previous mode */
}
onIncompleteEventDescription: This event requests that the iWidget supply missing information (usually the
original event used an anonymous function as an event handler) such that the iContext can delivery an event. In
JSON syntax, this event's payload is:
{
"eventDescription": eventDescription
}
This event is sourced only by the iContext.
6.1.4 Event Flow and Widget Lifecycle
The following details out how the lifecycle and event flow work together:
1. onLoad: First lifecycle event, all resources have been loaded. The iWidget needs to do any component level
initialization that is needed for processing other events before returning from handling this event.
2. onNavStateChanged: If the environment supports the concept of navigational state, this event will provide the initial
value for it.
3. on{mode}: Normally this will be onView, but could be for other modes if the page starts the iWidget in some other
mode. This event is when the iWidget should render the requested markup.
4. Any events queued during init processing: Events targeted to the iWidget by processing up to this point will
have been queued and are now delivered to the iWidget.
5. Normal operation ...
6. onUnload: Last lifecycle event, the iWidget is about to be removed from the browser. This is a good time to save
relevant state.
6/7/2010 1:33 PM
iWidget v2.1 Specification
20 of 35
file:///C:/iwidget-spec-v2.1.html
7 IO Type
This interface defines support the iContext is supplying regarding IO operations.
module IO
{
XMLHttpRequest
URI
XMLHttpRequest();
rewriteURI(in URI uri, in boolean isXhr /* optional, default=true */);
/* Simple accessors */
XMLHttpRequest request(in
in
in
in
in
XMLHttpRequest
String requestVerb,
URI uri,
Function callbackFn,
String message /*optional*/,
[{headerName: value}] requestHeader /*optional*/);
xhrReq(in Object args);
}
Members:
XMLHttpRequest: This object wraps the native XMLHttpRequest support to provide a consistent page in the face of
asynchronous updates, especially those which may cause server-side coordination between the server-side
components related to multiple iWidgets on the page. Note that the need to proxy URIs to domains outside the
domain that sourced the page MAY also need the iContext to modify the specified URI prior to supplying it to the
native XMLHttpRequest implementation. Note that either the iContext or proxy implementation MAY refuse to
activate the requested URI due to security or policy reasons. All of the semantics/syntax of the native support apply
with the exceptions/additions noted below:
None at this time.
rewriteURI: This method takes a URI as a parameter and returns a URI which the browser can resolve for
accessing the supplied URI. Examples of usage include resolving a relative URI against the source of the
iWidget's definition and resolving other URIs to address any intermediate gateways, such as a proxy server. The
isXhr parameter has been added to enhance performance when the uri will be accessed using a technique other
the xhr. For example; the src attribute for an image may need to be rewritten for access relative to the iWidget's
definition, but the browser will load it from an absolute uri without the cross-domain issues that apply when a uri is
accessed using xhr. Specifying false in this case allows a proxy server to be bypassed and potentially improves the
overall usage of http caching. The default value for this parameter is true.
request: This convenience method creates a new XMLHttpRequest, registers any supplied callbackFn, sets it to
asynchronous only if a callbackFn is provided, sets any supplied request headers and sends the supplied message
as the request body if the requestVerb is "post" or "put" and executes the supplied requestVerb against the supplied
URI. If the requestVerb is not one of "get", "post", "put" or "delete" then "get" will be used.
xhrReq: This convenience method creates a new XMLHttpRequest and sets any supplied arguments on the new
XMLHttpRequest before sending the request to the supplied URI. The supported fields within the arguments object
include:
{
"requestVerb": {"get" | "post" | "put" | "delete"},
"url": {url},
"handleAs": {handleAs},
"sync": {boolean},
"preventCache": {boolean},
"content": {content},
"headers": {headers},
"timeout": {int},
"user": {user},
"password": {password},
"form": {form},
6/7/2010 1:33 PM
iWidget v2.1 Specification
21 of 35
file:///C:/iwidget-spec-v2.1.html
"msgData": {msgData},
"load": {load},
"error": {error},
"handle": {handle}
}
The following provides the semantics for these fields:
requestVerb [required]: The http verb to use. If the requestVerb is not one of "get", "post", "put" or
"delete" then "get" will be used.
url [required]: The URL to request data from.
handleAs [required]: This parameter specifies how to handle the data returned from the server. It usually
takes values of 'text', 'xml', or 'json'. What those values do is instruct it to try and hand the data to the
callback function in that format. Naturally if you specify a format that doesn't match what the server sends
you will likely get an error.
The currently supported options are:
text (default)
json
json-comment-optional
json-comment-filtered
javascript
xml
sync [optional]: A boolean value that says whether or not the xhrReq() function should block until data is
returned or return immediately and rely on callbacks for data handling. The default value is false
Note: As a matter of best practice, you should avoid using synchronized xhr calls unless there is no
alternative. Synchronized xhr calls block all other activity in the browser and can make it appear hung.
preventCache [optional]: A boolean value that tells xhrReq() to append a unique query parameter to each
request. The purpose of this parameter is to keep the browser from caching the results. While it is generally
good practice to let the server tell your browser how to cache and when to clear, sometimes it is necessary
to force the browser to not cache.
content [optional]: A JavaScript object of name/string value pairs. These items are converted to query
parameters (or the post body) and passed on as part of the url. Example request made by the browser:
?key1=value1&key2=value2&key3=value3..
headers [optional]: A JavaScript object of name/string value pairs. These are the headers to send as part
of the request. For example, you can use the headers option to set the Content-Type, X-Method-Override, or
Content-Encoding headers of the HTTP request.
timeout [optional]: Number of milliseconds to wait until timing out the request. Default is '0', which means
infinite (no timeout).
Note: This parameter is ignored when 'sync is set. Browser limitation.
user [optional]: If your end point requires BASIC web authentication, then you can pass the user name
using this parameter.
Note: This does NOT work for FORM based authentication. FORM based authentication is a use of POST,
where the POST body contains the credentials. FORM authentication is server implementation specific.
password [optional]: If your end point requires BASIC web authentication, then you can pass the
password using this parameter.
Note: This does NOT work for FORM based authentication. FORM based authentication is a use of POST,
where the POST body contains the credentials. FORM authentication is server implementation specific.
form [optional]: For posting FORM data, you can provide either the DOM node of your form or the ID of
the form. xhrReq will convert this into proper POST format and send it with the post data. If a url is not set in
the args, then it tries to extract the url from the form 'action' attribute.
This parameter only applies when requestVerb has a value of 'post'.
msgData [optional]: A string of data you wish to send as the body on a POST or PUT. There will be no
processing of this, it is merely passed through as the body. If particular processing is required (examples
include specifying an encoding), headers to specify that processing will also need to be set.
This parameter only applies when requestVerb has a value of 'post' or 'put'.
6/7/2010 1:33 PM
iWidget v2.1 Specification
22 of 35
file:///C:/iwidget-spec-v2.1.html
load [optional]: The function that should invoked when the data is returned from the server. The function
should expect to receive at at least one parameter, the data returned from the url. The format of the data is
controlled by the previously mentioned handleAs parameter. A second available parameter is the args object,
from which you can get the status code and determine success or failure.
error [optional]: Sometimes xhrReq calls will fail. Often these are 404 errors or server errors such as 500.
The error parameter is another callback function that is only invoked when an error occurs. This allows you to
control what happens when an error occurs without having to put a lot of logic into your load function to check
for error conditions. The first parameter passed to the error function is a JavaScript Error object indicating
what the failure was.
handle [optional]: Sometimes you want to do something regardless of whether a call completes or fails.
Thats where handle comes it, it will be invoked by xhrReq regardless. The first parameter passed to this
callback is the response (or error) and the second parameter is the args object, from which you can get the
status code and determine success or failure.
The second parameter always passed to the 'load', 'error', and 'handle' functions is the 'args' parameter. It contains
the original request arguments and a lot of detail about the xhr request, including a reference to the actual native xhr
object.
6/7/2010 1:33 PM
iWidget v2.1 Specification
23 of 35
file:///C:/iwidget-spec-v2.1.html
8 Constants
Constants
iContext.constants.mode.VIEW = "view"
iContext.constants.mode.EDIT = "edit"
iContext.constants.mode.PERSONALIZE = "personalize"
iContext.constants.mode.CONFIG = "config"
iContext.constants.mode.HELP = "help"
iContext.constants.windowstate.NORMAL = "normal"
iContext.constants.windowstate.MAXIMIZE = "maximize"
iContext.constants.windowstate.MINIMIZE = "minimize"
iContext.constants.ATTRIBUTES = "attributes"
iContext.constants.IDESCRIPTOR = "idescriptor"
iContext.constants.USERPROFILE = "userprofile"
iContext.constants.keys.SHIFT = 1
iContext.constants.keys.ALT = 2
iContext.constants.keys.CTRL = 4
iContext.constants.keys.META = 8
iContext.constants.keys.CAPSLOCK = 16
iContext.constants.event.TITLE = "title"
iContext.constants.event.DESCRIPTION = "description"
iContext.constants.status.SUCCESS = 200
iContext.constants.status.TIMEOUT = 408
iContext.constants.status.NOTFOUND = 404
iContext.constants.status.INTERROR = 500
iContext.constants.status.OTHER = 303
iContext.constants.changeType.CHANGEDVALUE = "changedValue"
iContext.constants.changeType.NEWITEM = "newItem"
iContext.constants.changeType.REMOVEDITEM = "removedItem"
Members:
iContext.constants.mode.VIEW: The generated markup fragment(s) should reflect normal interaction with the
iWidget. All iWidgets MUST define content for the "view" mode.
iContext.constants.mode.EDIT: The generated markup fragment(s) should reflect iWidget interactions for
editing iWidget attributes scoped to this instance on the iWidget, but applicable to all users.
iContext.constants.mode.PERSONALIZE: The generated markup fragment(s) should reflect iWidget
interactions for editing iWidget attributes scoped to this instance on the iWidget for this user.
iContext.constants.mode.CONFIG: The generated markup fragment(s) should reflect iWidget interactions for
editing iWidget attributes scoped to all instances of the iWidget for all users.
iContext.constants.mode.HELP: The iWidget should generate markup fragment(s) to assist the user with
interacting with the iWidget
iContext.constants.windowstate.NORMAL: WindowState is an optional concept reflecting the portion of the
display allocated to the iWidget. The default is "normal" meaning that the display is shared with other components.
iContext.constants.windowstate.MAXIMIZE: A windowState of "maximize" means most of the display is
allocated to the iWidget. The iContext could still be providing a wrapper around the iWidget.
iContext.constants.windowstate.MINIMIZE: A windowState of "minimize" means none of the display is
allocated to the iWidget.
iContext.constants.ATTRIBUTES: Name for the ManagedItemSet holding the customization attributes.
iContext.constants.IDESCRIPTOR: Name for the ManagedItemSet holding the items describing the iWidget.
6/7/2010 1:33 PM
iWidget v2.1 Specification
24 of 35
file:///C:/iwidget-spec-v2.1.html
iContext.constants.USERPROFILE: Name for the ManagedItemSet holding data about the user. It is expected
that most of the items in this ManagedItemSet will be read only for most users.
iContext.constants.status.*: A subset of status codes copied from the http specification, with the same
semantics as defined there.
iContext.constants.changeType.CHANGEDVALUE: The value for an item has been changed.
iContext.constants.changeType.NEWITEM: A new item has been added to the set.
iContext.constants.changeType.REMOVEDITEM: An item has been removed from the set.
Note that not all iWidgets will support all modes, but they are defined here for interoperability of those leveraging these
modes.
9 Declarative syntax
This section defines declarative syntaxes for an iWidget. At a minimum, this defines what is needed to properly initialize
the iWidget. This purpose is met via tag definitions that form a relatively thin layer on top of the iContext interface
methods a script based iWidget would use to accomplish the equivalent initialization. Note that most of the tags are
optional as they provide means to access iContext functionality that an iWidget is not required to access. The following
table uses italics for optional items and encloses within curly braces (i.e. '{' and '}') descriptions of the values that are to be
replaced (e.g. readOnly="{boolean}" gets replaced to be readOnly="true" or readOnly="false").
9.1 iWidget definition syntax
This section defines a declarative syntax for defining an iWidget that can be consumed by any application providing a
compliant iContext implementation (e.g. a web page that has loaded such support). Since there are items within the
definition that may want to be specified for multiple locales, authors are encouraged to use either UTF-8 or UTF-16
encoding for their definitions. Either the "lang" or "xml:lang" attributes can be used to specify the locale, below will just use
"lang".
<iw:iwidget xmlns:iw="http://www.ibm.com/xmlns/prod/iWidget"
id="{iWidgetName}"
allowInstanceContent="{boolean}" supportedModes="{list of modes}"
supportedWindowStates="{list of windowStates}"
{[Section 5.2 items]}="{value}" {attributeName}="{value}"
iScope="{objectName}" {eventName}="{handlerName}"
sandbox="{boolean}" lang="{locale}" >
<!-- one per described event -->
<iw:eventDescription id="{eventDescName}"
lang="{locale}" payloadType="{payloadType}"
description="{description}" title="{title}">
<!-- one per additional locale -->
<iw:alt description="{description}" title="{title}"
lang="{locale}" />
</iw:eventDescription>
<!-- one per event -->
<iw:event id="{eventName}" alias="{alias}"
eventDescName="{eventDescName}"
published="{boolean}" handled="{boolean}"
onEvent="{handlerName}" onNewWire="{handlerName}"
onRemoveWire="{handlerName}" />
<!-- one per instantiated ItemSet -->
<iw:itemSet id="{setName}" private="{boolean}"
alias="{alias}" onItemSetChanged="{handlerName}">
<!-- one per Item in the ItemSet -->
<iw:item id="{itemName}" alias="{alias}" lang="{locale}"
readOnly="{boolean}" value="{value}" >
<!-- one per additional locale -->
<iw:alt lang="{locale}" value="{value}" />
</iw:item>
6/7/2010 1:33 PM
iWidget v2.1 Specification
25 of 35
file:///C:/iwidget-spec-v2.1.html
</iw:itemSet>
<!-- one per resource -->
<iw:resource id="{resourceName}" globalid="{resourceName}"
src="{uri}" blockInit="{boolean}" version="{version}"
mimeType="{mimeType}" callback="{function name}" skipLoad="{javascript
expression}" >
<iw:skipLoad>
<![CDATA[
<!-- more complex javascript expressions -->
]]>
</iw:skipLoad>
</iw:resource>
<!-- one per supported mode -->
<iw:content mode="{mode}" uri="{uri}" >
<![CDATA[
<!-- default content for this mode -->
]]>
</iw:content>
</iw:iwidget>
Element descriptions:
Component metadata (iw:iwidget - required element))
This specification defines a number of metadata items at the iWidget-level that can be specified using attributes on the
iw:iwidget element, namely;
id [required]: This xml attribute provides a non-localized name for textually representing the iWidget to a user.
One example of such a usage would be on a tooltip when the mouse is hovering over a representation of the
iWidget on a mashup tool's pallete of components.
allowInstanceContent [optional]: This attribute provides control over whether the placement of an instance of
the iWidget is allowed to replace the content specified in this definition file. Usage is commonly related to the
nesting of iWidgets and is described in Section 10. The default value is "false".
supportedModes [optional]: This metadata item provides a means for the iWidget to inform the iContext of
the "modes" for which it can generate markup. If this is not supplied, the iContext will presume the only supported
mode is "view". If it is supplied, the iContext might generate means in any decoration around the iWidget to
assist the user in switching to one of these modes. These values are specified using a space-delimited list and has
a default value of "view".
supportedWindowStates [optional]: This metadata item provides a means for the iWidget to inform the
iContext of the "windowStates" for which it can generate markup. If this is not supplied, the iContext will
presume a default set of values, most likely only the value "normal". If it is supplied, the iContext might generate
means in any decoration around the iWidget to assist the user in switching to one of these windowStates. These
values are specified using a space-delimited list and has a default value of "normal".
Descriptive items (Deprecated; set these using the "idescriptor" ManagedItemSet): Values for the items
defined in [Section 5.2] can be registered using attributes whose names match the defined iDescriptor name.
iWidget attributes (Deprecated; set these using the "attributes" ManagedItemSet): These provide
standard means for the iWidget to provide a customized presentation for the user (e.g. user-set background color,
prefered zipcode, etc). Note that there are two means of defining iWidget attributes; in addition to the one
specified here, full definitions can be defined using the ItemSet technique defined further down for the set named
"attributes". The short-hand technique does not allow specifying the read-only flag.
iScope [optional]: This provides the name of an object that is to be used instantiating an encapsulation object
instance for the iWidget. The iContext will first try to resolve this from the set of referenced script files and then
from the global context. If it fails to resolve, the generic Object class will be used to create an encapsulation object
instance.
Event handlers [optional]: Event handlers for the events defined in [Section 6.1.3] and others using the
convention of having the event's name start with "on" followed by an upper case letter can be registered using
attributes on the whose names match the event name. These method names are first resolved against the iScope
instance for the iWidget and then the global context.
sandbox [optional]: This attribute indicates whether or not the iWidget needs to be placed in an IFrame (or
6/7/2010 1:33 PM
iWidget v2.1 Specification
26 of 35
file:///C:/iwidget-spec-v2.1.html
equivalent) in order to properly execute when multiple instances of it are placed on the same page. Default value is
false.
lang [optional]: This attribute provides the default locale for everything specified in-line without an accompanying
locale specification.
Event metadata (iw:eventDescription - optional element))
This specification defines a number of event metadata items using attributes on the iw:eventDescription element,
namely;
id [required]: This provides the name that defines the semantics of the event and becomes the means by which it
is refered to elsewhere.
lang [optional]: This item specifies the locale of values supplied in-line for the title and description attributes.
payloadType [optional]: This description of the payload type uses types as discussed in [Section 3.4].
description [optional]: This item provides a localized, user-oriented description of the semantics of the event.
Intended uses include display on a tooltip while the user's pointer is hovering of over some display of the event
relative to the iWidget. The locale of the description is specified using the "lang" attribute. Descriptions for
additional locales can be supplied using child <iw:alt> elements.
title [optional]: This item provides a localized, user-oriented short name for the event. Intended uses include some
display of the event relative to the iWidget. The locale for the supplied title is specified using the "lang" attribute.
Titles for additional locales can be supplied using child <iw:alt> elements.
iw:alt - optional child elements: This child element provides a means to specify values for additional locales,
reusing the attributes from the iw:eventDescription element.
Event specification (iw:event - optional element))
Events can be specified relative to both those an iWidget publishes and those it can process, including the case where
the same event is both published and processed. Events are declared using the <iw:event> element with separate
attributes for "published" and "handled" declaring the direction(s) the event can flow.
While the metadata concerning an event has been separated into a different descriptive element (iw:eventDescription),
there can only be one event for each description due to the semantics carried as part of the metadata.
The semantics of the attributes on the iw:event element are:
id [required]: This item refers to both the name the event will specify at runtime and the name provided in any
accompanying iw:eventDescription. If no iw:eventDescription is provided, it MUST be assumed that the
event is opaque and any issues related to processing it become the responsibility of the receving component.
alias [optional]: The "alias" attribute provides for an alternate name for the event.
eventDescName [optional]: This attribute refers to the id of an iw:eventDescription for connecting metadata
items to the event definition.
published [optional]: This boolean (will be considered to be "true" if neither published nor handled are specified)
declares whether or not this event is one the iWidget generates for distribution to other components.
handled [optional]: This boolean (default value is "false") declares whether or not this event is one the iWidget
can processs.
onEvent [optional]: This attribute specifies the name of the method for processing this event. It is not valid on
declarations of events that are only published. The supplied value will be dereferenced as a method name, first from
the iWidget's iScope instance and then from the global javascript namespace. Note that if the value supplied can
be dereferenced into a method, the value of "handled" is considered to be "true" regardless of what is supplied as
its value.
onNewWire [optional]: This attribute specifies the name of the method for processing this predefined event
relative to this event definition. The supplied value will be dereferenced as a method name, first from the iWidget's
iScope instance and then from the global javascript namespace.
onRemoveWire [optional]: This attribute specifies the name of the method for processing this predefined event
relative to this event definition. The supplied value will be dereferenced as a method name, first from the iWidget's
iScope instance and then from the global javascript namespace.
6/7/2010 1:33 PM
iWidget v2.1 Specification
27 of 35
file:///C:/iwidget-spec-v2.1.html
ItemSet specification (iw:itemSet - optional element))
Multiple ItemSets can be instantiated such that an iWidget can cleanly separate state into separate categories (or
"buckets"). The following details the attributes for this element:
id [required]: This provides the unique identifier for this ItemSet. If the identifier matches one of the named
ManagedItemSets, it will take precedence over other potential matching and result in a ManagedItemSet being
used. This will cause attributes and child elements which are not relevant to this variant of the ItemSet concept to
be ignored.
private [optional]: This boolean (default value is "true") controls whether or not the ItemSet is sharable with
other components. If the ItemSet is not a ManagedItemSet and it is marked as not private, then a
ShareableItemSet will be instantiated. This will cause attributes and child elements which are not relevant to this
variant of the ItemSet concept to be ignored.
alias [optional]: The "alias" attribute provides for an alternate name for the ItemSet.
onItemSetChanged [optional]: This attribute provides the method name for a listener to changes to the
ItemSet. The iContext will first attempt to dereference this method from the iWidget's iScope instance and
then from the global javascript namespace. When an ItemSet undergoes changes (new items, changed values,
etc), it will source an onItemSetChanged event to all registered listeners other than the component which originated
the change unless a more specific event is defined in [Section 6.1.3] for the item. Listeners can be registered either
from the declarative markup (indicate a listener using the onItemSetChanged attribute/class) or by invoking the
addListener method on the ItemSet.
iw:item - optional child elements: Each child iw:item element specifies an item to place into the ItemSet
during initialization. Relevant attributes are:
id [required]: The unique identifier for the item
alias [optional]: The "alias" attribute provides for an alternate name for the Item.
lang [optional]: This attribute specifies the locale for which the value applies (including a missing or empty
locale meaning the supplied value is not a localized value).
readOnly [optional]: This attribute requests the iContext to set whether the user is allowed to update this
item to the supplied value. This request is subject to implementation-specific policy and is unlikely to be
honored if write access is requested (value of "false") for an item where the policy already denies such
access. The default value is false (i.e. allow the user to update the item unless policy restricts otherwise).
value [optional]: An initial value for the item. This attribute is ignored for ShareableItemSets as initial
values can only be set at the shared scope (normally a web page). Where and how such initialization is done
is outside of the scope of this specification.
iw:alt - optional child elements: This child element provides a means to specify values for additional
locales, reusing the attributes from the iw:item element.
Example: setting the title item within the iDescriptor ManagedItemSet.
<!-- id=idescriptor => ManagedItemSet -->
<iw:itemSet id="idescriptor" >
<iw:item id="title" lang="en-us" value="My English Title" >
<iw:alt lang="de" value="Mein Deutscher Titel" />
</iw:item>
</iw:itemSet>
Example: defining a location field within a ShareableItemSet:
<!-- private=false => ShareableItemSet -->
<iw:itemSet id="sharedLocation" private="false">
<iw:item id="location" />
</iw:itemSet>
Note that various attributes will control what variant of ItemSet is instantiated (i.e. private="false" will instantiate a
ShareableItemSet while certain named ItemSets (in particular; "attributes", "idescriptor" and "userprofile") will result in
access to a ManagedItemSet). Attributes not applicable to the ItemSet variant instantiated will be ignored (e.g. value and
lang for items in a ShareableItemSet); namely:
Attribute
id
ManagedItemSet
required
ShareableItemSet
required
ItemSet
required
6/7/2010 1:33 PM
iWidget v2.1 Specification
28 of 35
file:///C:/iwidget-spec-v2.1.html
alias
optional
optional
optional
private
ignored
required (value is 'false') optional (missing or value is'true')
onItemSetChanged
optional
optional
ignored
On iw:item child elements:
id
required
required
required
alias
optional
optional
optional
(1)
lang
optional
ignored
optional
readOnly
optional
ignored
optional
value
optional
ignored
optional
ignored
optional
iw:alt child element(s) optional(1)
Notes from table:
1. A number of ManagedItemSet items can be localized in the iWidget definition (and inclusion microformat) though
only one of these values will be selected by the iContext for use at runtime (usually based on the user's preferred
locales).
Resource references (iw:resource - optional element))
Common markup resources include scripts, css definitions, images, etc. While these can be referenced in the standard
HTML/XHTML manner, there is also a provision for referencing resources not predefined by the (X)HTML specifications.
This may also be useful for resource used in a dynamic manner. Resource types the iContext MUST support loading as
part of the iWidget initialization are javascript (application/javascript), css (text/stylesheet) and SHOULD support loading
images (image/*). For javascript and css resources, loading includes insertion into the environment for immediate use by
the iWidget while other types simply include causing the resource to be preloaded (e.g. placed into the browser's cache).
The order in which resources are processed MUST match the document order in the definition file.
The following attributes specify an iWidget resource:
id (Deprecated - use globalid):
globalid [optional]: This provides a generic means to refer to a resource regardless of the URI from which it is
loaded. The preferred form of this name is a serialized QName where the URI portion of the name provides the
originating source for the resource and the local part provides the short name of the resource. For example, the
preferred resourceName for dojo.js is "{http://www.dojotoolkit.org}/dojo.js". This form of reference allows sharable
resources to be loaded once by the iContext and used by any iWidget referencing them.
src [required]: This specifies a URI from which the resource can be fetched. Note that for shared resources, it
might be fetched from a different URI (i.e. one provided by some other component).
blockInit [optional]: This attribute allows the iWidget author to specify whether or not the iContext MUST load
the resource prior to invoking the iWidget's onLoad handler. Default value is true. Note that the iContext MAY
block init for all resources rather than support this attribute.
version [optional]: This potentially allows the iContext to distinguish requirements for different versions of a
shared resource. Loading distinct versions of some resources might not be possible due to issues it would cause in
the underlying environment (e.g. name clashes on loading two version of most script libraries in a browser
environment).
mimeType [optional]: This item tells the iContext how to request (and process) the resource, and can be given
precedence over any mimetype specified on the response returning the resource. When missing, a mimetype of
"application/javascript" will be assumed for uris ending in ".js" and "text/stylesheet" for those ending in ".css".
callback [optional]: This item allows the iWidget author to specify a method that the iContext will invoke once
the resource load attempt has completed. Whether or not the resource was successfully loaded is indicated by the
supplied statusCode. It is resolved in the same manner as event handlers. The signature for the callback method is
defined in the section for the requires method.
skipLoad [optional]: This item exists both as an attribute and an optional child element. This allows compact
expressions when they make sense and full Javascript at other times. If the child element is used, the actual
Javascript has to be placed in a CData section to ensure it coexists well with the XML parsing of the overall
document. Which ever form is used, the supplied Javascript expression is evaluated, using the eval method, in the
6/7/2010 1:33 PM
iWidget v2.1 Specification
29 of 35
file:///C:/iwidget-spec-v2.1.html
same context where the iWidget will be placed (i.e. if the iWidget will be in an IFrame, the expression is
evaluated from within that IFrame). The return of the expression will be treated as a boolean, using the standard
Javascript mapping to determine whether to proceed with loading the resource. As an example, this allows a test
for an Object's existence to just be the Object's name using the attribute style. When this boolean evaluation returns
the value true, the loading of the resource will be skipped.
Markup (iw:content - optional element)
The iWidget definition can include markup for the modes that it declared to be supported. Regardless of whether a mode
change happens due to an iContext provided means or by iWidget actions, these different markup sections will be
hidden or shown depending on whether they apply to the current mode or not. The supplied markup for in-line content
MUST be contained within a "CDATA" section such that HTML markup can be supported without undue complications and
MUST be in a decoded form that can be directly passed to a user-agent (typically a browser) for rendering. The different
markup sections are specified using:
mode [optional]: Provides the mode where the contained content applies, default value is "view".
uri [optional]: The uri attribute can be used to reference external content. If the uri attribute is present as well as
in-line content, the content fetched from the supplied uri MUST be used, though the in-line content MAY be
displayed while the content is fetched from the uri.
It should be noted that the concept of modes can be used for values not defined in this specification. For example, an
iWidget supporting ordering items may define a "viewCart" mode for the markup to show when the user wants to see
what they have placed into their shopping cart already. The iContext might not provide a means for the user to switch
into this mode, but will do the hide/show logic when the iWidget sources a change in the mode (i.e. changes the value of
the mode item within the iDescriptor set (see [Section 5.2])).
Since the iWidget's markup is likely to reference relative resources (e.g. an <img> element referencing an image relative
to the deployment of the iWidget) and these relative URI are not likely to resolve correctly relative to the base URI of the
page (i.e. what the browser will try), a javascript URL leveraging the rewriteURI() method off the "io" field of iContext
(e.g. src="javascript:iContext.io.rewriteURI(relativeURI)").
Localization
Various parts of an iWidget's definition support localization. In general these parts carry a "lang" or "xml:lang" attribute
and support having <iw:alt> children, each one providing values for a particular locale. It is preferrable, but not required, to
collapse all values for a single locale onto a single element (e.g. an EventDescription can have localized values for both
title and description and it is preferred that these be on a single element for any one locale). Values provided with the
empty string ("") as the locale will be treated as if no locale was provided and used to set the non-localized value.
Examples:
1. <iw:item id="company" value="IBM" />
2. <iw:item id="company" value="IBM" lang=""/>:
Both #1 and #2 do not provide what appears to be a locale, they are equivalent.
3. <iw:item id="company" value="IBM" lang="en"/>
4. <iw:item id="company">
<iw:alt lang="en" value="IBM"/>
</iw:item>:
Both #3 and #4 provide a value for the generic "en" locale (i.e. not a specific variant such as "en-us") and therefore
are equivalent.
9.2 Including iWidgets
This section defines a declarative syntax for placing an instance of an iWidget into a broader set of markup (e.g. a web
6/7/2010 1:33 PM
iWidget v2.1 Specification
30 of 35
file:///C:/iwidget-spec-v2.1.html
page), including which items from an iWidget's definition can be overridden (including definition of non-existence items) as
part of the instance placement. The keys in the syntax below are the class names as these identify what is being supplied.
The elements chosen to carry the attributes supplying the needed values were selected for basic match on the semantics
involved (e.g. <a> for referring to other definitional items), but the match will be against class and attribute names, not
element names.
<div class="iw-iWidget iw-Sandbox" id="{instanceID}" sandbox="{boolean}">
<a class="iw-Definition" href="{uri}"></a>
<!-- one per described event -->
<span class="iw-EventDescription" title="{eventDescName}">
<span class="iw-PayloadType">{payloadType}</span>
<span class="iw-Description">
<span class="iw-Value" lang="{locale}"> {value} </span>
</span>
<span class="iw-Title">
<span class="iw-Value" lang="{locale}"> {value} </span>
</span>
</span>
<!-- one per event -->
<span class="iw-Event iw-Published iw-Handled" title="{eventName}">
<a class="iw-DescRef" href="#{eventDescName}">{payloadType}</a>
<span class="iw-Handler">{handlerName}</span>
<span class="iw-NewWire">{handlerName}</span>
<span class="iw-RemoveWire">{handlerName}</span>
</span>
<!-- Override values from iWidget definition -->
<span class="iw-ItemSet" title="attributes|{setName}">
<!-- one per item value supplied -->
<a class="iw-Item" lang="{locale}" href="#{itemName}" > {value}
<span class="iw-Value" lang="{locale}"> {value} </span>
</a>
</span>
<!-- one per event to receive -->
<span class="iw-ReceivedEvent" >
<a class="iw-SourceEvent" href="#{sourceWidgetID}">
{sourceEventName}
</a>
<span class="iw-TargetEvent" > {targetEventName} </span>
</span>
<!-- IF ALLOWED BY THE iWidget DEFINITION! -->
<div class="iw-Content {mode}">
<!-- content for this mode -->
</div>
</div>
The following table provides comments on the semantics of the syntax shown above.
Class
iw-Widget
Attribute
id
This class marks the beginning of the microformat for placing an iWidget instance on a
page. The "id" attribute provides a unique identifier for this iWidget instance on the
page.
The presence of this class instructs the iContext to place the iWidget instance in a
separate JavaScript sandbox (usually by placing it in an IFrame). The absence of this
class permits, but does not require, in-line inclusion of the iWidget instance with other
components.
iw-Sandbox
iw-Definition
Comments
href
iw-EventDescription title
The URI to the iWidget's definition
The element with this class wraps the description of a single event. The "title" attribute
specifies the name of this description.
iw-PayloadType
The content of this element provides type information ,as per [Section 3.4], for the
payload of the runtime event.
iw-Description
This element contains a set of localized values for the displayable description
6/7/2010 1:33 PM
iWidget v2.1 Specification
31 of 35
iw-Value
file:///C:/iwidget-spec-v2.1.html
lang
iw-Title
iw-Value
iw-Event
The content of this element provides a value for the locale specified using the "lang"
attribute
This element contains a set of localized values for the displayable title
lang
The content of this element provides a value for the locale specified using the "lang"
attribute
title
The element with this class wraps the definition of a single event. The "title" attribute
specifies the name of this event.
iw-Published
This class marks that the iWidget sources this event
iw-Handled
This class marks that the iWidget handles this event
This element carries two pieces of information, though usually only one of them will be
provided:
iw-DescRef
href
The href attribute carries an optional reference to an event description (either from
the iWidget definition of in this instance of the iWidget placement microformat.
The value of this element optionally carries the type , as per [Section 3.4], of the
payload for this event. Typically this will be used only if there is no event
description being referenced.
iw-Handler
The content of this element provides the name of the method which handles this event. It
will be dereferenced first from the iWidget's iScope instance and then from the global
JavaScript namespace.
iw-NewWire
The content of this element provides the name of the method which handles the
onNewWire predefined event related to this event. It will be dereferenced first from the
iWidget's iScope instance and then from the global JavaScript namespace.
The content of this element provides the name of the method which handles the
onRemoveWire predefined event related to this event. It will be dereferenced first from
the iWidget's iScope instance and then from the global JavaScript namespace.
iw-RemoveWire
iw-ItemSet
title
This element provides a wrapper for initializing a single ItemSet with the "title" attribute
defining which set is being initialized
iw-Item
href
This element provides the initialization values, potentially in a localized manner, for the
item referenced using the "href" attribute.
lang
The content of this element provides a value for the locale specified using the "lang"
attribute
iw-Value
This element provides a wrapper for describing a wire that delivers the described event
to this iWidget instance.
iw-ReceivedEvent
iw-SourceEvent
iw-TargetEvent
href
This element describes the source endpoint of the wire. The "href" attribute refers to the
"id" attribute of the iWidget instance sourcing the event while the content of the element
provides the event name that iWidget instance will use.
This element describes the target endpoint of the wire. Since it is contained within the
microformat placing the target iWidget instance, no reference to that is needed. The
event name to deliver could be different from what the source iWidget instance
generated and the content of this element provides the event name to use.
iw-Content
The markup to display, supplied in a decoded form that can be directly passed to a
user-agent (typically a browser) for rendering.
iw-Standalone
Reserved class
6/7/2010 1:33 PM
iWidget v2.1 Specification
32 of 35
file:///C:/iwidget-spec-v2.1.html
10 Nesting iWidgets
There are three significant use cases related to the nesting of iWidgets and two flags for use in providing information to
the iContext about required support:
1. Simple container: This type of iWidget is not interested in being involved in the control flow relative to the
iWidgets it contains. The kinds of functionality provided include things such as laying out the contained iWidgets
according some pre-defined rules. Due to the nature of these containers, the content can not reasonably be defined
until an instance is placed on a page. In order to have the iContext allow this content to be specified within the
instance placed on the page, the "iw-AllowInstanceContent" CSS class or "allowInstanceContent" attribute have to
be set on the root element of the iWidget definition. Note that this use case has the iContext managing both the
container iWidget and any nested iWidgets.
2. Defined container: This type of iWidget is frequently derived by a user deciding to save a set of iWidgets and
any wiring between them. As a result, this type of containers differs from the Simple Container in that the content is
defined in the iWidget definition rather than in the instance placed on a page. As a result, neither of the flags
related to nesting iWidgets is set. Note that this use case has the iContext managing both the container iWidget
and any nested iWidgets.
3. Composites: This type of iWidget is the logical component for the content it contains and the nature of the
contained iWidgets is not directly visible outside the composite. While it is expected that composites will normally
specify their content within their definition, the composite is also allowed to set the flag allowing instance content.
Note that this use case has the iContext managing the composite iWidget and the composite managing any
nested iWidgets. While this version of the specification provides for no assistance from the iContext relative to
managing the nested iWidgets, it is expected future versions will define such assistance.
Some of the differences resulting from the above use cases include:
When a Simple Container is dragged off a pallete and placed on a page, it usually arrives empty and other
iWidgets have to be dragged off the pallete to populate its content. When iWidgets are placed within the Simple
Container, they are exposed to the overall management provided by the iContext in the same manner as if they
were placed outside the context of a container.
When a Defined Container or a Composite is dragged off a pallete and placed on a page, the full set of referenced
iWidgets are also placed on the page. For the Defined Container, these iWidgets will be separately managed,
just as they are for the Simple Container while the nested iWidgets of a Composite will only have their attributes
and internal wiring exposed only if the Composite chooses to do that exposure.
The semantics of the flag from the above discussion:
1. allowInstanceContent: This flag tells the iContext to replace view mode content from the iWidget definition
with the equivalent content from the instance on the page. This flag may only be set in the definition of an iWidget.
11 Schema
The normative copy of the schema for the definitions within this specification can be found at http://www-10.lotus.com
/ldd/mashupswiki.nsf/xsp/.ibmmodres/domino/OpenAttachment/ldd/mashupswiki.nsf
/6B347C11548059218525772E005883AF/attach/iWidgetXML_v2_1.xsd.
All iContext implementations MUST accept all iWidget definitions that validate against this schema.
An iWidget SHOULD NOT require a particular iContext policy on optional items. For example, an iContext policy could
prevent distribution of a particular event to an iWidget. While this will certainly change the user experience for the
placement of an instance of that iWidget in the environment (e.g. a web page), the functionality of the iWidget should not
break due to this policy choice.
6/7/2010 1:33 PM
iWidget v2.1 Specification
33 of 35
file:///C:/iwidget-spec-v2.1.html
Appendix A: Conformance statements
#
Section Conformance statement
CS047
2.1
Of particular note given the nature of the environment, relative URIs (those not starting with a
protocol scheme (such as http) and not starting with '/') MUST be resolved relative to the widget
definition URI.
CS003
4.1
When successful, this method (setLocalizedItemValue) MUST return a handle to the ItemSet
while on failure it MUST return null.
CS001
4.1
When successful, this method (setItemValue) MUST return a handle to the ItemSet while on
failure it MUST return null.
CS004
4.1
When successful, this method (removeValue) MUST return a handle to the ItemSet while on
failure it MUST return null.
CS002
4.1
When successful, this method (removeLocalizedItemValue) MUST return a handle to the ItemSet
while on failure it MUST return null.
CS039
4.1
When successful, this method (removeItemValue) MUST return a handle to the ItemSet while on
failure it MUST return null.
CS005
4.1
On failure this method (getLocalizedItemValue) MUST return null.
CS029
4.1
On failure this method (getItemValue) MUST return null.
CS006
4.1
If the set contains no items, this method (getAllNames) MUST return null.
CS030
4.1
If the set does not contain the named item, this method (getLocalesWithValues) MUST return null.
CS035
4.2
Any persistence provided by the iContext SHOULD be done in a manner consistent with the
current mode. For "view" and custom modes, the persistence of a value SHOULD apply to the first
supported from the following list; (the current mode), personalize, edit, config.
CS007
4.2
As ManagedItemSet are controlled by the iContext, some items MAY be read only to the
iWidget.
CS008
4.2
When successful, this method (setItemValue) MUST return a handle to the ManagedItemSet while
on failure it MUST return null.
CS009
4.2
When successful, this method (removeValue) MUST return a handle to the ManagedItemSet while
on failure it MUST return null.
CS010
4.2
On failure this method (getItemValue) MUST return null.
CS011
4.2
If the set contains no items, this method (getAllNames) MUST return null.
CS012
4.2
This method (save) MAY operate asynchronously.
CS013
4.2
The iContext MUST invoke any supplied callbackFn upon completion of the save attempt.
CS040
4.2
This method (commit) MAY operate asynchronously.
CS050
4.2
The iContext MAY also choose to persist the ManagedItemSet at times other than when
iWidgets invoke this method.
CS041
4.2
The iContext MUST invoke any supplied callbackFn upon completion of the commit attempt.
CS031
4.3
When successful, this method (getItemValue) MUST return a handle to the ShareableItemSet
while on failure it MUST return null.
CS032
4.3
On failure this method (getItemValue)MUST return null.
CS033
4.3
When successful, this method (removeItem) MUST return a handle to the ShareableItemSet
while on failure it MUST return null.
CS034
4.3
If the set contains no items, this method (getAllNames) MUST return null.
CS042
4.3
This method (commit) MAY operate asynchronously.
CS043
4.3
The iContext MUST invoke any supplied callbackFn upon completion of the commit attempt.
CS014
5.2
The iContext SHOULD NOT persist iDescriptor items.
CS015
5.2
The mode saying what markup the iWidget SHOULD be currently displaying.
6/7/2010 1:33 PM
iWidget v2.1 Specification
34 of 35
file:///C:/iwidget-spec-v2.1.html
CS016
6
If there is no ManagedItemSet related to the iWidget's customization attributes, this method
(getiWidgetAttributes) MUST create an empty set and return it.
CS017
6
If there is no ManagedItemSet related to the iWidget's descriptive items this method
(getiDescriptors) MUST create an empty set and return it.
CS018
6
On success this method (processMarkup) MUST return the processed markup while on failure it
MUST return null.
CS019
6
Extensions supported by more advanced iContexts SHOULD follow the pattern (defined in
Section 3.3) used for the iEvents and IO portions of these definitions.
CS036
6.1
The iContext MAY choose to persist these definitions and SHOULD do any such peristence in a
manner consistent with the current mode. For "view" and custom modes, the persistence of a value
SHOULD apply to the first supported from the following list; (the current mode), personalize, edit,
config.
CS020
6.1
In addition to distributing the events between iWidgets (or other items on the page), the
iContext MAY choose to provide a mapping between certain events.
CS025
6.1
The iWidget SHOULD use this factory when needing to define additional events.
CS021
6.1.3
The iContext MUST inspect iWidgets once they are fully loaded and support this pattern for
default mapping of event handlers to the predefined events.
CS022
6.1.3
The iContext MUST support the "onLoad" event.
CS023
6.1.3
The iContext MUST support the "onUnload" event.
Note that the need to proxy URIs to domains outside the domain that sourced the page MAY also
need the iContext to modify the specified URI prior to supplying it to the native XMLHttpRequest
implementation. Note that either the iContext or proxy implementation MAY refuse to activate the
requested URI due to security or policy reasons.
CS051
7
CS046
9.1
All iWidgets MUST define content for the "view" mode.
CS037
9.1
If no iw:eventDescription is provided, it MUST be assumed that the event is opaque and any
issues related to processing it become the responsibility of the receving component.
CS026
9.1
This item allows the iWidget author to specify whether or not the iContext MUST load the
resource prior to invoking the iWidget's onLoad handler. Default value is true. Note that the
iContext MAY block init for all resources rather than support this attribute.
CS027
9.1
Resource types the iContext MUST support loading as part of the iWidget initialization are
javascript (application/javascript), css (text/stylesheet) and SHOULD support loading images
(image/*).
CS028
9.1
The order in which resources are processed MUST match the document order in the definition file.
CS038
9.1
The supplied markup MUST be contained within a "CDATA" section such that HTML markup can
be supported without undue complications.
CS024
9.1
If the uri attribute is present as well as in-line content, the content fetched from the supplied uri
MUST be used, though the in-line content MAY be displayed while the content is fetched from the
uri.
CS044
11
All iContext implementations MUST accept all iWidget definitions that validate against this
schema.
CS045
11
An iWidget SHOULD NOT require a particular iContext policy on optional items.
Appendix B: References
Reference Description
[RFC2119]
[RFC2396]
[xml:base]
[RFC3066]
Key words to Indicate Requirement Levels
Uniform Resource Identifiers
XML Base definition
Tags for the Identification of Languages
6/7/2010 1:33 PM
iWidget v2.1 Specification
35 of 35
file:///C:/iwidget-spec-v2.1.html
Appendix C: Contributors
The following individuals were active in the production of this specification:
Robert Desbiens (mailto:[email protected])
John Gerken III (mailto:[email protected])
Stephan Hesmer (mailto:[email protected])
Rafah Hosn (mailto:[email protected])
Tong Li (mailto:[email protected])
David Osofsky (mailto:[email protected])
Shikha Srivastava (mailto:[email protected])
Rich Thompson - editor (mailto:[email protected])
Li Xu (mailto:[email protected])
6/7/2010 1:33 PM
Fly UP