From MemberWiki

About this wiki page

2009-04-01 The resolutions from this wiki page are now being merged into the mainline OpenAjax Metadata spec. In particular:

• jsclass, sandbox, singleton, scrolling, mode: [1]
• designonly: [2]
• __WID__: [3]
• APIs and events: [4]

This wiki page therefore is quickly transitioning from a working document into a historical document. Most of the remaining spec development activity will happen in the mainline OpenAjax Metadata spec.

This wiki page contains various features that were originally defined in the OpenAjax Metadata Specification, but have been separated out temporarily into this supplemental document per decisions at the [http://www.openajax.org/member/wiki/2008_October_Membe= About this wiki page =

This wiki page contains various features that were originally defined in the OpenAjax Metadata Specification, but have been separated out temporarily into this supplemental document per decisions at the OpenAjax face-to-face meeting in October 2008. The reasons for splitting these features out:

• The IDE features from OpenAjax Metadata Specification were farther along that the mashup-related features. The members of OpenAjax Alliance decided that the IDE-related features (both the JavaScript APIs and the widgets) were mature and ready for finalization on an aggressive schedule, and these features should not have to wait for completion of the mashup-related features.
• The members of OpenAjax Alliance decided it was appropriate to work towards better alignment with Google Gadgets due to its marketplace momentum and the technical merit of its technologies. However, there is uncertainty about the exact nature of the technical changes that will be made and the timeframe for making those changes.

The decision on the exact list of features to split off was decided during a teleconference [5], based on the proposal in [6].

This wiki page is the working document used by the Gadgets Task Force (gadgets@openajax.org) to define mashup-related widget features that for the most part represent extensions to the widget features found in the OpenAjax Metadata Specification. The starting point for these mashup-related extensions came from a cut/paste operation, where features from an earlier draft OpenAjax Metadata Specification were cut from that document and pasted onto this wiki page. The Gadgets TF has subsequently modified those features.

Once the mashable widget features are near completion and stable, the Gadgets TF will make a recommendation to the members of OpenAjax Alliance about what to do with these features. One strong possibility would be to re-integrate the mashup-related features back into the OpenAjax Metadata Specification, perhaps as a dot release.

Need to produce picture(s) of widget lifecycle

Markup

Gadget-related attributes on the <widget> element

(KEPT) jsClass attribute

The jsClass attribute specifies the JavaScript class name for the given widget, such as MyWidgetClass or com.example.abc.MyWidgetClass. If provided, then the user agent must invoke the class constructor for each instance of this widget. Typically, the class constructor is invoked using a JavaScript new operator, such as: new com.example.abc.MyWidgetClass(). If not provided, then the user agent must still create an object instance for the widget, such as by invoking new Object().

RESOLUTION 2009-03-09: Keep 'jsClass'

(KEPT) sandbox attribute

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

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

RESOLUTION 2009-03-09: Keep 'sandbox'

(KEPT) scrolling attribute

The scrolling attribute is a boolean that is a hint to the widget's container about whether the container should provide scrollbars if the widget's height is greater than the area provided for the widget. The attribute value true indicates that the container should provide scrollbars when the containing area is not as large as the widget. The value false indicates that the container should not provide scrollbars. The default is false.

RESOLUTION 2009-03-09: Keep 'scrolling'

(KEPT) singleton attribute

The singleton attribute provides an optional boolean that specifies whether users can add a gadget multiple times from a directory. The default is false, meaning that by default, gadgets can be added more than once. Directories can handle this attribute however they choose. For example, the content directory handles singleton="true" by graying out and displaying the text "Added" for gadgets that have already been added. Note that changes to this attribute may not be picked up by directories right away. This attribute doesn't prevent users from adding gadgets multiple times through the developer gadget or Add by URL. Consequently, you still need to write your gadget to support multiple instances. Editor: clean this up

RESOLUTION 2009-03-09: Keep 'singleton'

(DEFERRED) designtime attribute

The designtime attribute provides an optional boolean that specifies whether this widget should appear only when the container application is in design mode (in contrast to runtime mode). Default is false.

RESOLUTION 2009-03-09: Probably don't add a 'designtime' at this time, but include it on the wiki page for the time being to give us a chance to think about it more

Gadget-related attributes on the <content> element

(DROPPED) type attribute

RESOLUTION 2009-03-16: Drop type=page from first release, which means drop 'type' attribute entirely.. Too problematic. To get it to work such that Hub and Widget APIs were available, would need to invent a new protocol.

The type attribute supports two values, fragment and page:

• If type="fragment" (the default), then the content MUST be suitable for inclusion within an HTML <div> element.
• If type="page", then the content MUST be contained within an external file referenced by the src attribute. The referenced URL MUST produce a complete Web page (e.g., an HTML file that begins with an <html> element) and therefore suitable as the target for an HTML <iframe> element.

NOTE: IDE WG decided at 2009-02-24 telecon that 'src' could be used with fragments.

(DROPPED) view attribute

RESOLUTION 2009-03-09: After studying OpenSocial Gadgets, we came to the conclusion that their 'views' feature was a whole different thing from our default|edit|help feature. Therefore, we will drop the 'view' attribute (which we might add in the future, in which case we very well might copy what Gadgets is doing) and add an alternate 'mode' attribute that has values view|edit|help. See new section on the mode attribute below.

The view attribute allows for multiple alternate <content> elements for a particular widget. The view attribute specifies a comma-separated list of named views. The following named views are defined by this specification:

• default - The default standard rendering for the widget when instantiated onto a Web page.
• edit - Custom user interface that provides a property editor for the widget's properties.
• help - Custom user interface that help information about the widget.
• insert - Custom user interface that should be shown when the widget is inserted.

(ADDED) mode attribute

RESOLUTION 2009-03-16: Add the 'mode' attribute RESOLUTION 2009-03-23: Accept similar approaches as old 'view' attribute, where no value defaults to the normal view and QNames for extensibility. No 'insert' mode. Accept comma-separated list. Canvas is in charge of causing the mode changes, and can ignore custom modes. 'onModeChanged' event gets sent with every mode change, whether using widget's edit/help or not. Need to have a parameter on event object indicates whether using the widget's edit/help rendering or not.

EDITORIAL: Need to add text about how it is OK for canvas to ignore edit modes, and explain why it is optional: difficult to implement, doesn't provide desired UI experience.

The mode attribute allows for multiple alternate display modes for a particular widget. The mode attribute specifies a comma-separated list of named display modes. The following display modes are defined by this specification:

• view - The default standard rendering for the widget when instantiated onto a Web page.
• edit - Custom user interface that provides a property editor for the widget's properties.
• help - Custom user interface that provides help information about the widget.

Additional information about the mode attribute:

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

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

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

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

For widgets that have <content type="page">, the widget will be an opaque object that will be loaded into an IFRAME. For this case, the mashup environment typically will not be able to control content within that IFRAME. Therefore, metadata files that use <content type='page'> should only have a single <content element. This single content element may support multiple modes. For example:

<content type="page" src="..." mode="view,edit"/>

The above metadata indicates that the URL in the 'src' attribute supports both view and edit modes. Since the same content applies to two different editing modes, the mashup environment does not have to make any changes to the presention when changing modes between view and edit, except send an onModeChanged event to the widget.

(CLARIFICATION) Gadget-related issues associated with the <javascript> element

RESOLUTION 2009-03-23: Proposal accepted for simply concatenation SCRIPT, CONTENT, SCRIPT, SCRIPT as described below. Editorial: Need to update spec per this resolution.

PROPOSAL: Here are proposed rules for what happens in mashup workflows with the 'location' attribute on the <javascript> element:

In the mashup case, the mashup app should simply concatenate a SCRIPT tag (with the JAVASCRIPT location=beforeContent inside), then the CONTENT, then another SCRIPT tag (with the JAVASCRIPT location=beforeContent inside), then another SCRIPT tag (with the JAVASCRIPT location=atEnd inside) and plunk the whole thing into a DIV.

I think that it is unreasonable to tell mashup app developers that they need to collect all of the "atEnd" logic for all of the widgets when a mashup is loaded. Besides being unreasonable to require this, it's just not a good idea. We don't want different logic paths for when a widget is added to a page and when the mashup is reloaded. Keep it simple. Furthermore, you can't collect all of the "atEnd" logic easily unless all widgets are inline. (

Gadget-related attributes on the <property> element

(ADDED) designonly attribute

ISSUE: Should we add a designtime attribute which indicates a property whose value can be changed within a property editor but whose value must not be changed during runtime logic? The key impact of this attribute is that attempts to invoke setPropertyValue() on the given attribute would fail. One scenario for this attribute is when you have a property foo which is used only in conjunction with macro substitution (@@foo@@). The 'designtime' attribute would prevent any attempts to change the property at runtime, which would make the runtime value of the property out of sync with the string that was substituted for @@foo@@.

RESOLUTION 2009-03-23: Accept and change 'designtime' to 'designonly'. Just advisory. Tool decides when "design time" is. Need to include picture that shows various workflows. No restriction on invoking setPropertyValue() Editorial: Need to update spec per this resolution.

(MODIFIED) __WID__ macro expansion

PROPOSAL: Keep __WID__, but with some differences. __WID__ holds a unique (unquoted) string for a given widget. __WID__ must be suitable for use within an XML ID, CSS classname and JS identifier. One difference from previously is that __WID__ will not be the name of a JavaScript global; instead, we will add a getter function off of the window.OpenAjax object that takes __WID__ as a parameter and returns the JavaScript object for the widget.

Editor: The following elements are subject to property substitution and __WID__ substitution: inline <content>, inline <javascript>, inline <require>, <preload>, <postload>.

RESOLUTION 2009-03-23: Accept the proposal to make __WID__ a string that is unique for a particular widget, but unlike previously, it is no longer the name of a JavaScript global object. Instead, we will have a getter for retrieving the JS object. Must start with a letter and only include letters, numbers, underscore and dash. Include explanation that these restrictions are necessary so that the __WID__ string can be used within an ID, a CSS classname, and a JS name. Editorial: Need to update spec per this resolution. Jon promised to check on which API returns the widget object. Isn't that "this"?

APIs

(MODIFIED) Widget construction and initialization

• Get rid of OpenAjax's widget constructor. Instead, rely on the presence of an onLoad callback to take care of initialization logic. To illustrate, previously a widget looked like this within our open source project:

// WHAT WE HAD BEFORE
function MyWidgetClass(id, wrapper) {...}
MyWidgetClass.prototype.init = function() { ... }

and you had to include the following code in your XML file:

<javascript>
  // WHAT WE HAD BEFORE
  this.init();
</javascript>

And note that the above logic doesn't work with the current spec since we decided that the "this" on a <javascript> element is the "window" object. The proposal would remove the need for calling this.init() and remove the need for a constructor. Instead, just provide an onLoad() function on your class prototype:

// PROPOSAL
function MyWidgetClass() {...}
MyWidgetClass.prototype.onLoad = function() { ... }

• RESOLUTION 2009-03-23: Accept the proposal to get rid of initializing via widget constructor.

• Get rid of our old wrapper class and getHubConnectionHandle(). Instead, the mashup application is responsible for putting an 'OpenAjax' subobject on the widget object. To illustrate, previously a widget looked like this within our open source project:

// WHAT WE HAD BEFORE
function MyWidgetClass(id, wrapper) {
  this.id = id;
  this.wrapper = wrapper;
}
MyWidgetClass.prototype.init = function() {
  var hubConnection = this.wrapper.getHubConnectionHandle();
  hubConnection.publish("org.openajax.2008InteropFest.dyndata.newstockprice", stock);
}

With the proposed changes, all of the Widget APIs (e.g., adjustDimensions()) are available from an OpenAjax subobject, and all of the Hub 2.0 client APIs (e.g., publish() and subscribe()) are available on the OpenAjax.hub subobject. 2009-03-30 Jon: Should say that OpenAjax.hub global object is available and the the full set of HubClient interfaces are available on the widgetobject.OpenAjax.hub object.

// PROPOSAL
function MyWidgetClass() {...}
MyWidgetClass.prototype.onLoad = function() {
  this.OpenAjax.hub.publish("org.openajax.2008InteropFest.dyndata.newstockprice", stock);
}

The widget APIs (e.g., getPropertyValue() and adjustDimensions()) would be available on the OpenAjax subobject. The Hub 2.0 HubClient APIs (e.g., publish() and subscribe()) would be available on the OpenAjax.hub subobject:

MyWidgetClass = function() { }
MyWidgetClass.prototype.onLoad = function(...) {
  this.OpenAjax.hub.subscribe(...);        // Using Hub 2.0 APIs
  this.OpenAjax.hub.publish(...);          // Using Hub 2.0 APIs
  this.OpenAjax.getPropertyValue(...); // Invoking standard widget APIs
  this.OpenAjax.adjustDimensions(...); // Invoking standard widget APIs
}

One side effect: we don't need a default wrapper class (e.g., OpenAjax.widgets.WidgetWrapper) anymore.

• 2009-03-16 RESOLUTION: Widget APIs on OpenAjax subobject, Hub APIs on OpenAjax.hub subobject, which implements HubClient interface
• RESOLUTION 2009-03-23: Accept the proposal to get rid of old wrapper class and getHubConnectionHandle() in favor of naming convention for event handler functions, such as onLoad and onUnload.
• 2009-03-16 RESOLUTION: OpenAjax subobject must be unique to each widget instance

• If jsClass not specified, then the widget instance object is a plain old Object.
• RESOLUTION 2009-03-23: Accept the proposal, but change the wording to "a default object that will be provided by the system" or something like that. Editorial: Need to update wording.

(MODIFIED) Widget callbacks

• Get rid of registerCallback() and unregisterCallback(). Instead, rely on naming conventions where an event callback is implicitly registered due to a function with a particular name being on the widget instance subobject. For example, instead of calling registerCallback('unload'), yo simply put an onUnload() function onto the widget class prototype. The naming convention is "on"+EventNameFirstLetterUppercase (e.g., "onLoad")
• RESOLUTION 2009-03-23: Accept the proposal to get rid of old registerCallback() and unregisterCallback() in favor of naming convention for callback function names.

(MODIFIED) Get rid of 'view' APIs, add 'mode' APIs

• Get rid of view APIs and add mode APIs (see discussion above about the 'view' and 'mode' attributes)
• RESOLUTION 2009-03-23: Accept the proposal to get rid of view APIs and add mode APIs.
• RESOLUTION 2009-03-23: Accept 'onModeChanged' event. 'onModeChanged' event gets sent with every mode change, whether using widget's edit/help or not. Need to have a parameter on event object indicates whether using the widget's edit/help rendering or not.

(KEPT) Sizing APIs (on OpenAjax subobject)

• (Probably) Keep the sizing APIs (getAvailableDimensions, getDimensions, adjustDimensions, but they would be available from the OpenAjax subobject)
• RESOLUTION 2009-03-23: Accept the proposal to retain sizing APIs.

      <methods>
         <method name='getAvailableDimensions'>
             <description>
               Returns the available width and height which the widget can request in the adjustDimensions method.
             </description>                  
             <return datatype="Object">
                 <description>
               The return value is an object with a width and a height property representing the available pixels for use.
               NOTE: If the container does not return a width or a height this signifies the widget can ask for whatever size it would like when using the adjustDimensions method.
                  </description>                
             </return>
         </method>
         <method name='getDimensions'>
             <description>
               Returns the current width and height in an Object which the widget occupies in the container.
             </description>                  
             <return datatype="Object">
                 <description>
                     The return value is an object with a width and a height property representing the current dimensions of the widget.
                  </description>                
             </return>
         </method>
         <method name='adjustDimensions'>
             <description>
             </description>
             <parameters>
                 <parameter name="dimensions" datatype="Object">
                     <description>
                       This parameter is an object that contains a width and a height property which are integers. The width and height properties specify the requested with and height to adjust the widget to. 
                       NOTE: If either property, width or height, are not present the dimension is not changed.
                     </description>
                 </parameter>
             </parameters>
         </method>

(KEPT, ENHANCED) Property APIs (on OpenAjax subobject)

• (Probably) Keep the property APIs (getPropertyValue, setPropertyValue, getPropertyNames, but they would be available from the OpenAjax subobject)
• RESOLUTION 2009-03-23: Accept the proposal to retain property APIs.
• Keep existing property change callbacks on the widget instance object (i.e., the instantiation of jsClass) and must use the naming convention of "onChange"+PropertyNameFirstLetterUppercase (e.g., "onChangeDate") (Same as before, except put "onChange" at the front). As a result, both event callbacks (e.g., onLoad) and property change callbacks (e.g., onChangeDate) are located on the widget instance object. For example:
• RESOLUTION 2009-03-23: Accept the proposal to keep existing rules for property change callback names, except put "onChange" at the front.

function MyWidgetClass() {...}
MyWidgetClass.prototype.onLoad = function(...) { ... }
MyWidgetClass.prototype.onChangeDate = function(...) { ... }

• Add a new property change callback (onChange()) that gives widget developers the option of providing a single property change handler that catches all properties.
• RESOLUTION 2009-03-23: Accept the proposal to add a new "onChange" function.

      <methods>
         <method name='getPropertyValue'>
                 <description>
                      Returns the current value of the requested property name.                  
                 </description>
                 <parameters>
                       <parameter name='name' datatype='String'>
                           This is the name of the property to retrieve
                       </parameter>
                 </parameters>
                 <return datatype='*'>
                     <description>The current value of the property named name</description>
                 </return>
         </method>
         <method name='setPropertyValue'>
                 <description>
                      Sets the current value of the requested property name to the value passed in via the value property.
                 </description>
                 <parameters>
                       <parameter name='name' datatype='String'>
                           This is the name of the property whose value is to be updated
                       </parameter>
                       <parameter name='value' datatype='*'>
                           The new value of the property     
                       </parameter>
                 </parameters>
         </method>
         <method name="getPropertyNames">
               <description>
                        Returns an array the property names on the gadget.
               </description>
               <returns datatype="[String]">
         </method>   

(ADDED) Localization APIs

• PROPOSAL: Need APIs to get at message bundle strings. OpenSocial Gadgets has prefs.getMsg(). We need something comparable. Here is a simple proposal.
• RESOLUTION 2009-03-30: Accept the proposed new localization API.

<method name='getMsg'>
  <description>
    Returns the localized version of the given string.
  </description>                  
  <parameter name="name" datatype="String">
    <description>
      The lookup key for the localization string. 
      This parameter must be an exact string match
      with the 'name' attribute on a <msg> element 
      within a message bundle file.
    </description>
  </parameter>
  <return datatype="String">
    <description>
      The localized version of the string.
    </description>                
  </return>
</method>

(ADDED) I/O APIs

• Add XHR proxy APIs. Proposal below..
• RESOLUTION 2009-03-30: Accept the proposed new I/O API.
• ACTION 2009-03-30: Research Gadgets makeRequest to see whether status code is returned.

<method name='getProxyUrl'>
  <description>
    Returns a URL string that is suitable for use with the current proxy server.
    Some environments will use proxy servers and others will not. For environments 
    that do no use proxy server techniques, this method returns the original URL string.
  </description>                  
  <parameter name="url" datatype="String"> 
    <description>
      URL to be proxied
    </description>
  </parameter>
  <parameter name="opt_params" datatype="Object">
    <description>
      Extensible list of parameters.
    </description>
  </parameter>
  <return datatype="String">
    <description>
      A URL string.
    </description>                
  </return>
</method>

<method name='makeRequest'>
  <description>
    Returns a URL string that is suitable for use with the current proxy server.
    Some environments will use proxy servers and others will not. For environments 
    that do no use proxy server techniques, this method returns the original URL string.
  </description>                  
  <parameter name="url" datatype="String"> 
    <description>
      URL to which the request is sent
    </description>
  </parameter>
  <parameter name="callback" datatype="Function"> 
    <description>
      The callback function that is invoked when the request is complete.
    </description>
  </parameter>
  <parameter name="opt_params" datatype="Object">
    <description>
      Extensible list of parameters.
    </description>
  </parameter>
</method>

The opt_params parameter allows for future extensibility and implementation-specific parameters. In order to avoid conflict with future versions of OpenAjax Metadata spec and other implementations, the recommended best practice is to place implementation-specific parameters on a sub-object (e.g., params.ABCOrg.*) where the sub-object's name (ABCOrg) is unlikely to collide with other implementations. One recommended technique to avoid collisions is for the name of the sub-object to reflect the name of the organization associated with the parameters on the sub-object.

(ADDED) Utility APIs

• Add getRootElement() method. Located on the this.OpenAjax subobject for the given widget instance. Returns the DIV or other HTML element that is the container for the widget. Assumes that mashup application will create a container element for each widget into which the content is inserted, where the container element is continuously available during the widget lifecycle between when the widget is loaded and when it is unloaded. This container element is in the same document space as the widget content; therefore, if a widget is isolated into an IFRAME, the container element is also in the IFRAME.

• Add global function OpenAjax.widget.byId(wid) to get widget instance object from __WID__. This function returns the widget instance object given the __WID__ string. Typical usage: var widgetInstance = OpenAjax.widget.byId("__WID__");

• RESOLUTION 2009-03-30: Accept the proposed utility API.

(MODIFIED) Changes to supported events

PROPOSAL: The following summarizes proposed changes to built-in events:

• (REMINDER: Earlier sections proposed that we get rid of registerCallback() for registering event handlers, and instead rely on naming conventions, where an onLoad() function on the widget instance object is the 'load' event handler, etc.)
• Drop everything having to do with 'insert', 'remove', 'reload' events, but keep 'load' and 'unload'
• Drop everything that has to do with views (use 'mode' instead of 'view'). This results in dropping 'viewChanged' and adding 'onModeChanged'
• Add an onChange callback

• Need to review proposed payload for onModeChanged below
• Need to review writeup on onLoad below
• For events with no payloads, presumably it's OK for an implementation to extend the idea of "no payload" to a private payload. What's the best way to express that?

• RESOLUTION 2009-03-30: Accept events listed below with following changes: (a) same payloads for onChange and onChangeFoo, (b) onChange payload is property,old,new, (c) onModeChange is old,new,renderedBy, (d) resize is four values {old|new}{Width|Height}, all notifications are "post" events rather than "pre" events.

• Editorial: make sure all events are clearly defined as post-event, not pre-event.

{
  "property": "",     /* Property's name (same as 'name' attribute on <property> element) */
  "oldValue": "",     /* Any JSON-serializable JavaScript value (e.g., String or Object) */
  "newValue": ""      /* Any JSON-serializable JavaScript value (e.g., String or Object) */
}

{
  "property": "",     /* Property's name (same as 'name' attribute on <property> element) */
  "oldValue": "",     /* Any JSON-serializable JavaScript value (e.g., String or Object) */
  "newValue": ""      /* Any JSON-serializable JavaScript value (e.g., String or Object) */
}

{
  "oldMode": "",      /* view|edit|help|QName */
  "newMode": "",      /* view|edit|help|QName */
  "renderedBy": ""    /* widget|host */
}

{
"oldWidth": "",
"oldHeight": "",
"newWidth": "",
"newHeight": ""

(ADDED) Extensibility

• Extensibility? For example, implementations should use "_" as the first character of any extensions? (This is what we did with the Hub) RESOLUTION 2009-03-30: Implementations should use "_" for implementation-specific private objects and data. Extensions should be namespaced onto a JavaScript object whose name is unlikely to conflict with other names.