From MemberWiki

Notes:

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

Here is the proposed way for the IDE WG to edit this specification:

• All textual content that has normal text properties (i.e., black) and has no colored status text (e.g., does not say Tentatively approved or Approved) represents preliminary proposed text that requires further review and discussion.
• Members of OpenAjax Alliance are encourage to place inline comments into this document, preferably by identifying your name or initials before your comment, such as "Mary: This bullet should be moved above previous bullet".
• When an item has been deemed complete by the WG chair due to committee consensus, then the annotation Approved will be placed at the end of an approved block of text (e.g., paragraph or bullet). Note that during the development phase of this specification, the group can change its mind and "un-approve" text that was previously approved.
• When an item has been deemed near complete by the WG chair due to committee consensus, but further review is necessary (e.g., review final wording), then the annotation Tentatively approved will be placed at the end of given block of text (e.g., paragraph or bullet).

5 Properties

Introduction

OpenAjax Metadata assumes that a "property" is a unit of data that is managed by a property management system that sits outside of any of the components (e.g., the widgets), and that actions on properties might produce side effects that are outside of the control of the component (e.g., the widget). For example, the setter for a property might publish an event so that subscribers can be notified of the change and update themselves accordingly, which is sometimes necessary in order to enable live bindings.

This chapter defines the two key elements having to do with properties (i.e., the <property> and <properties> elements). There is also a section on the getterPattern and setterPattern attributes that exist on the <property> element and other OpenAjax Metadata elements

Elements defined in this chapter

Property elements

<property>

property_element = element property {
  property_content  &  property_attributes  &  foreign_nodes
}
property_content = (
  option_element*  &  options_element*  &  
  descriptive_elements  &  compatibility_elements
)
property_attributes = (
  datatype?  &  default_attribute  &  hidden?  &  name  &  readonly?  &  
  required?  &  scope?  &  transient?  &  urlparam?  &  visibility?  &
  datatype_supplemental_attributes  &  pattern_attributes  &  pubsub_attributes
)

The <property> element describes not yet written.

The name attribute specifies the name of this property. Each different property name must be unique within the scope of its parent. If 'title' is not provided, then [RT] name is {RT] is likely to be used wherever 'title' would be used. (Required, not Localizable) 2008-01-24 Tentatively approved

The default attribute specifies the default value for the property. 2008-01-24 Tentatively approved The default attribute MUST be specified for each property in a metadata file. (Note: the rationale for requiring that widget authors always specify a default is to minimize the chances that auto-generated pages will suffer from syntax errors in cases when the user has not provided a value for a property.)

We are working on clearer text for how to represent default values for various different datatypes. In general, we will use JSON notation, but we need to determine exact spec words and need to analyze all of the different possible datatypes.

The scope attribute. Only applicable to properties on JavaScript classes. Indicates whether this is a static property (i.e., on the object prototype) or an instance property. 2008-02-21 Tentatively approved

The visibility attribute specifies not yet written and can have values "public|private|protected|internal|protected-internal".

The required attribute. A boolean. If true, this property MUST have a value in order for the data set to be valid. This attribute MUST be supported by conforming tools. (JSON Schema has an "optional" property instead. OK with me to use "optional" instead.) 2008-01-?? TENTATIVE APPROVAL: support 'required', with default of false.

The readonly attribute. A boolean. If true, this property SHOULD be visible but read-only to the user. This attribute MUST be supported by conforming tools. 2008-02-15 TENTATIVE APPROVAL: support 'readonly', with default of false.

The hidden attribute. A boolean. If true, this property SHOULD be hidden from the user and therefore tools MUST not show display this property to the user in property editor dialogs. This attribute MUST be supported by conforming tools. 2008-02-15 Tentatively approved.

The transient attribute. A boolean. This indicates that the property will be used for transient/volatile values that should not be persisted. This is false by default. 2008-02-15 Tentatively approved.

The <title> element specifies a short description of this property, typically used as the label within property editor dialogs and/or tooltip within an editing environment. (Note: if not provided, then tools MAY choose to use other available information, such as the property name or the description, to construct the string that is presented in the property editor's UI.) (Localizable, Optional) 2008-05-13: Tentatively approved. <title> element instead of attribute so it can be localized Editor: shouldn't this be removed and instead refer to Descriptive chapter?

Editor: move 'publish', 'subscribe' and 'topic' to Topics chapter and instead refer to Topics chapter

The publish attribute. Boolean. Default value is 'false'. If true, indicates that the widget might publish this topic on the OpenAjax Hub. Attribute 'topic' indicates the name of the topic that is used when that event is published. 2008-01-10 TENTATIVE APPROVAL: Include 'publish', 'subscribe' and 'topic'

The subscribe attribute. Boolean. Default value is 'false'. If true, indicates that the widget might subscribe to the OpenAjax Hub for the topic indicated by the 'topic' attribute. 2008-01-10 TENTATIVE APPROVAL: Include 'publish', 'subscribe' and 'topic' 2008-05-20 TENTATIVE APPROVAL (AGAIN): 'publish' and 'subscribe'

The topic attribute. String. Defaults to NULL. Identifies the topic name that is published to (if 'publish' is true) and/or subscribed to (if 'listen' is true) on the OpenAjax Hub. If the attribute is not specified, or is NULL or the empty string, and if 'publish' is true or 'listen' is true, then the value of the 'name' attribute is used as the topic name. (Note that providing a value to 'topic' has no effect if 'publish' is false and 'listen' is false.) 2008-01-10 TENTATIVE APPROVAL: Include 'publish', 'subscribe' and 'topic'

Attributes getterPattern and setterPattern are described below (see Pattern attributes: getterPattern and setterPattern).

Attributes defined in the Datatypes chapter: datatype, format, isInteger, minimum, maximum, min_length, max_length, min_items, max_items, pattern.

2008-04-24 Tentatively approved: Allow < availability> and <deprecated> across all uses of <property>, even if not likely to be used by tools in the widget space.

The urlparam attribute is not yet written, but it an alternate key name to use when the property is passed via a url parameter, mimicking similar feature in older Google Gadgets spec. 2008-07-08 Tentative resolutions: Yes, we will have urlparam

Note: if a <property> element appears in the metadata file such that it does not have either a <properties> element or a <childProperties> element as its parent, then it represents a normal property (i.e., as if it were a child of <properties>), not a child object property (i.e., as if it were a child of <childProperties>).

<properties>

properties_element = element properties {
    properties_content  &  properties_attributes  &  foreign_nodes
}
properties_content = (
  descriptive_elements  &  
  property_element*
)
properties_attributes = (
  pattern_attributes  &
  name?
)

The <properties> element holds zero or more <property> child elements.

The optional name attribute is meant to allow for providing a unique name for this particular <properties> element in case multiple <properties> are specified.

Attributes getterPattern and setterPattern are described below (see Pattern attributes: getterPattern and setterPattern).

DRAFT CONSENSUS: All of the black text above reflects draft consensus from previous discussion.

Child property elements

<childProperties>

childProperties_element = element childProperties {
    childProperties_content  &  childProperties_attributes  &  foreign_nodes
}
childProperties_content = (
  descriptive_elements  &  
  property_element*
)
childProperties_attributes = (
  pattern_attributes  &
  name?
)

The <childProperties> element to holds zero or more <property> child elements.

The <childProperties> element addresses the case where a parent object adds properties to child objects. One common scenario is for this element is with layout container widgets. Layout container widgets sometimes look at particular properties on child widgets as input into layout calculations.

Tools should add any child properties from the parent object onto the list of properties displayed in the child object's property editor.

The optional name attribute is meant to allow for providing a unique name for this particular <childProperties> element in case multiple <childProperties> are specified.

Attributes getterPattern and setterPattern are described below (see Pattern attributes: getterPattern and setterPattern).

2008-08-22 DRAFT CONSENSUS: We need a <childProperties> element.

Pattern attributes: getterPattern and setterPattern

Outside of mashup scenarios, collections of properties typically are managed internally within an Ajax library or component. The property management system might produce side effects due to property changes, such as sending notifications to other logic within the library or component.

The getterPattern and setterPattern attributes specify the name or name pattern for property getter and setter functions that correspond to a particular property. IDE can identify the getter and setter function names due to pattern recognition, which the IDE might leverage to provide more useful code completion features. getterPattern specifies a string pattern for how to invoke the function that retrieves a given property's value. setterPattern specifies a string pattern for how to invoke the function that sets a given property's value

Detailed processing model

Two key characteristics distinguish these pattern attributes:

• The attributes can contain substitution strings (delimited by braces, as in {{value}})
• The attributes are inheritable

There are five substitution strings, all delimited by double-braces:

• {{property}}: The name of the property (corresponds to the 'name' attribute on the <property> element)
• {{propertyUCFirst}}: Same as {{property}}, except that the first letter of the property name has been transformed into upper case (equivalent to the toUpperCase method in ECMAScript 262)
• {{propertyLCFirst}}: Same as {{property}}, except that the first letter of the property name has been transformed into lower case (equivalent to the toLowerCase method in ECMAScript 262)
• {{value}}: The value of the property. Often, this is a JavaScript literal value, such as null, a String, a Number, a Boolean, an Array literal or an Object literal.
• {{target}}: The JavaScript object from which the getter, setter and/or onchange functions are available. In mashup scenarios, the {{target}} is typically a widget wrapper object supplied by the mashup container.

getterPattern and setterPattern examples

For these example, assume the following:

• The JavaScript variable MyWrapperObject is the target object (i.e., the {{target}})
• The property's name (i.e., the {{property}}) is color
• The value to which the property will be set (i.e., the {{value}}) is the string 'blue'

Example:

<property getterPattern="{{target}}.{{property}}.get()" 
          setterPattern="{{target}}.{{property}}.set({{value}})"
          ...>
  ... 
</property>

In the example above:

• The property getter function has the following signature: MyWrapperObject.color.get();
• The property setter function has the following signature (where 'blue' shows how the value is passed): MyWrapperObject.color.set('blue');

Example:

<property getterPattern="{{target}}.getValue('{{property}}')" 
          setterPattern="{{target}}.setValue('{{property}}',{{value}})"
          ...>
  ... 
</property>

In the example above:

• Runtime JavaScript logic can retrieve the property value via var v = MyWrapperObject.getValue('color');
• Runtime JavaScript logic can set the property value via MyWrapperObject.setValue('color','blue');

Example:

<property getterPattern="{{target}}.get{{propertyUCFirst}}Value()" 
          setterPattern="{{target}}.set{{propertyUCFirst}}Value({{value}})"
          ...>
  ... 
</property>

In the example above:

• Runtime JavaScript logic can retrieve the property value via var v = MyWrapperObject.getColorValue();
• Runtime JavaScript logic can set the property value via MyWrapperObject.setColorValue('blue');

Inheritance and defaults

Attributes getterPattern and setterPattern are inheritable from their ancestor elements and (if an OpenAjaxLibary.xml file exists) from the <library> root element from the OpenAjaxLibary.xml file.

If either of these attributes exists on a given <property> element, then that attribute takes precedence over any inherited values. If a given attribute does not exist on a given <property> element, then find the nearest ancestor element that has the given attribute and use the value from that ancestor. If no ancestors have the given attribute, then if there is a corresponding OpenAjaxLibary.xml file and its <library> root element has the given attribute, then use that attribute. Else, there is no value to inherit, which means that the attribute is unspecified.

If the attribute is unspecified after inheritance, then the user agent shall assume that there is no corresponding function. For example, if getterPattern is unspecified, there is no corresponding getter function.