OpenAjax Metadata 1.0 Specification Properties

From MemberWiki

Jump to: navigation, search

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


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


Contents

Chapter 7: Properties

Introduction

For OpenAjax Metadata, a "property" represents a variable on an object.

The following elements in the OpenAjax Metadata language can have <property> element children (or <properties> element children who in turn have <property> element children):

Additionally, any element for which it is possible to have a datatype="Object" attribute can have <property> elements that describe the properties on the given JavaScript object.

This chapter specifies various elements having to do with properties.

This chapter also includes a Pattern attributes section that describes the rules and processing model for the following "pattern attributes":

  • getterPattern
  • setterPattern
  • registerHandlerPattern
  • unregisterHandlerPattern


<property>

The <property> element defines a single property on a particular object.

Schema

property_element = element property {
  property_content  &  property_attributes  &  foreign_nodes
}
property_content = (
  option_element*  &  options_element*  &  
  parameter_element*  &  parameters_element*  &  property_element*  &  properties_element*  &  
  returnType_element*  &  returnTypes_element*  &  
  descriptive_elements  &  compatibility_elements
)
property_attributes = (
  datatype?  &  defaultValue?  &  hidden?  &  managed?  &  
  name  &  readonly?  &  designonly?  &  
  outputDefault?  &  outputFormat?  &  
  required?  &  scope?  &  sharedAs?  &  transient?  &  
  urlparam?  &  visibility?  &
  datatype_supplemental_attributes  &  pattern_attributes
)

Child content

This element might contain any of the following sub-elements:

This element MAY contain <property> or <properties> sub-elements only when the datatype attribute is set to or allows the value type of "Object". In this case, the <property> sub-elements provide descriptive detail about the various properties on the Object.

This element MAY contain <parameter>, <parameters>, <returnType> or <returnTypes> sub-elements only when the datatype attribute is set to or allows the value type of "Function". In this case, the <parameter> and <returnType> sub-elements provide descriptive detail about the parameters and return types for the Function.

If the <property> element is a descendant of a <topic> element, then the 'datatype' attribute on this <property> element or any descendant element MUST NOT be "Function" because the message payload described by the <topic> element MUST be a JSON-serializable data value.

Attribute summary

AttributeDescriptionTypeRequiredDefault
datatype Allowed datatypes for the property. String (see below) no String
defaultValue Default value for the property. String (see below) no (datatype-specific. See 'datatype' attribute)
designonly Whether the property should appear only in design-time property editors. Boolean no false
hidden Whether the property should be excluded from property editors. Boolean no false
managed (API usage only) Whether this <property> element is managed by getter and setter functions. Boolean no false
name Name of the property. String yes none
outputDefault (Only applicable when datatype="Date") How to format the property value when an explicit value is not provided. String no none
outputFormat (Only applicable when datatype="Date") How to format the property value when an explicit value is provided. String no none
readonly Whether the property should be read-only within property editors. Boolean no false
required Whether the property must have a value. Boolean no false
sharedAs The sharing name for the property. If specified, indicates that this property is managed by the container application and its value is potentially shared across multiple widgets. String no none
transient Whether the property will be used for transient/volatile values that should not be persisted. Boolean no false
urlparam URL parameter name for the property. String no same as 'name' attribute
datatype_supplemental_attributes Various attributes that provide additional information about the datatype, such as min and max values. Defined in Datatypes chapter.
pattern_attributes (Only applies to JavaScript API descriptions.) Attributes 'getterPattern', 'setterPattern', 'registerHandlerPattern' and 'unregisterHandlerPattern'. Defined in Pattern attributes section.
scope (Only applies to JavaScript API descriptions.) Whether the property applies to an object instance or to the class. Defined in Common attributes section.
visibility (Only applies to JavaScript API descriptions.) Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section.

Attribute details

'datatype' attribute

The 'datatype' attribute specifies the allowed datatype(s) for the property's value. See the Datatypes chapter for the detailed definition of this attribute.

'defaultValue' attribute

The defaultValue attribute specifies the default value for the property. If not specified, the default value for the property depends on the 'datatype' attribute. (See the discussion of the 'datatype' attribute in the Datatypes chapter.)

When the datatype is Date, the string value of the defaultValue attribute MUST be expressed using the "Date Time String Format" defined in the ECMAScript5 specification. For example:

2009-01-20T13:00ZJan. 20, 2009, 13:00 in UTC (coordinated universal time)
2009-01-20T08:00-05Jan. 20, 2009, 8:00 in time zone 5 hours after UTC
'designonly' attribute

The designonly attribute is a Boolean value that, when true, indicates that the property SHOULD be visible and changeable within a design-time property editor, but SHOULD NOT be visible or changeable within run-time property editors. The distinction between "design-time" and "run-time" is left to the judgment of the tool provider; however, in some mashup scenarios, there might be a widget that requires two levels of customization, a first level that is done by administrators, and a second level that is done by end-users. Widget properties that are meant to be seen only by administrators should have designonly="true".

'hidden' attribute

The hidden attribute is a Boolean value indicating whether the property should be hidden from the user. If true, tools SHOULD NOT display this property to the user in property editors.

'managed' attribute

The optional managed attribute only applies to the JavaScript API use of properties, and does not apply to widget properties.

The 'managed' attribute is a Boolean value indicating this <property> is managed via getter and setter functions. By default properties are assumed to be unmanaged; that is, their values can be retrieved and set directly.

'name' attribute

The name attribute specifies the name for this property. For widget metadata, each property name MUST be unique within the scope of the current metadata file. For API metadata, each property name MUST be unique within the scope of any classes or singletons in which the property is used. The name MUST be globally unique within the context of current container object.

The value of the name attribute may include JavaScript string escape sequences, such as \n (newline character) or \x20 (hexadecimal representation of a space character). As a result, name="abc\ndef" represents a 7-character name where the fourth character is a newline character.

The special value of "*" (as in name="*") indicates a property whose name is variable.

For the rare case where the static name of a property is the single character "*" (e.g., myobject['*']), then the name attribute SHOULD represent the property name using a JavaScript escape sequence, such as name="\*". Developer tools MUST check for the special value "*" before unescaping the value of the name attribute.

'outputDefault' attribute

The outputDefault attribute only applies when the property's 'datatype' is a JavaScript Date object. The attribute specifies a date/time formatting string for the property value when the user does not supply an explicit value for this property.

See Details about outputFormat and outputDefault attributes below for more information.

'outputFormat' attribute

The outputFormat attribute only applies when the property's 'datatype' is a JavaScript Date object. The attribute specifies a date/time formatting string for the property value when the user supplies an explicit value for this property.

See Details about outputFormat and outputDefault attributes below for more information.

'readonly' attribute

The readonly attribute is a Boolean value indicating whether the property should be visible to the user but not editable by the user.

'required' attribute

The required attribute is a Boolean value indicating whether the property MUST have a value in order for the data set to be valid.

'sharedAs' attribute

The sharedAs attribute is a String that identifies the property name to use for sharing purposes. By default, properties are private to a given widget; however, if a 'sharedAs' attribute is provided, then the property becomes a public property that the host application can choose to share with other widgets with matching 'sharedAs' attribute values.

It is valid to set the 'name' and 'sharedAs' attributes to the same value (e.g., <property name="location" sharedAs="location">), but a recommended approach that minimizes potential name conflicts and that maximizes correct property matching with other components is to set the 'sharedAs' attribute to a value that begins with a registered internet domain expressed in reverse order, such as <property name="location" sharedAs="org.example.properties.geolocation">.

'transient' attribute

The transient attribute is a Boolean value indicating whether the property will be used for transient/volatile values that should not be persisted.

'urlparam' attribute

The urlparam attribute is a String that specifies the alternate name to use within URLs when the property is passed via a URL parameter.


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


Additional information

The optional <title> sub-element specifies a short description of the property, which may be used as the label within a property editor or as a tooltip within an editing environment. If <title> is not provided, then tools MAY choose to use other available information, such as the property name or the description, to construct a string for the user interface.

If a <property> element appears with neither a <properties> element nor a <childProperties> element as its parent, then it is assumed to represent a normal property (i.e., as if it were a child of <properties> with no specified attributes).


<properties>

The <properties> element holds zero or more <property> child elements. For additional information about plural elements such as <properties>, refer to the Plural and Singular Elements chapter.

Schema

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

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Optional name that defines a grouping name for a set of child properties. A tool might use the name attribute to establish property groups within a property editor dialog. String no none
pattern_attributes (API usage only) Attributes 'getterPattern', 'setterPattern', 'registerHandlerPattern' and 'unregisterHandlerPattern'. Defined in Pattern attributes section.

Attribute details

'name' attribute

The optional name attribute defines a grouping name for a set of child properties that a tool might use to establish property groups within a property editor. Each different group of properties might appear within a different tab within the property editor. For example, if name="Layout", then a tool might choose to include all of properties described by child <property> elements within a "Layout" tab in the property editor. The name MUST be globally unique within the context of current container object.


<childProperties>

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

Developer tools should add any properties defined within a <childProperties> element onto the list of properties displayed in the child object's property editor.

Schema

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

Child content

This element might contain any of the following sub-elements:

Attribute summary

AttributeDescriptionTypeRequiredDefault
name Optional name to uniquely identify this properties element String no none


Example

In the following example, the region property will be attached to all widgets that are immediately inside (contained by) the BorderContainer widget.

<widget name="BorderContainer">
  <childProperties>
    <property name="region" datatype="String" defaultValue="center">
      <option name="left"/>
      <option name="right"/>
      <option name="top"/>
      <option name="bottom"/>
      <option name="center"/>
    </property>
  </childProperties>
  ...
</widget>


<config>

The <config> element is a grouping element that provides a detailed definition for a JavaScript object that can be referred to by a 'datatype' attribute. The <config> element lists the properties (via child <property> elements) that can exist on that object.

For example:

<config name="MyClassConfigs">
  <property name="firstname" datatype="String" required="true"/>
  <property name="lastname" datatype="String" required="false"/>
  <property name="email" datatype="String" required="false"/>
</config>
<class name="MyClass">
  <constructor>
    <parameter name="options" datatype="MyClassConfigs"/>
  </constructor>
  <method name="updateOptions">
    <parameter name="options" datatype="MyClassConfigs"/>
  </method>
</class>

It is common in Ajax libraries and widgets for methods and constructors to take an object parameter that describes configuration options. While the properties of such an object can be specified as children of a <parameter> tag with datatype="Object", if the "config" or "options" object is a parameter to more than one method and always has the same properties, specifying those properties as children of a named <config> element makes more sense. The <parameter> element need only reference the name of the <config> element as its datatype, and the <property> elements can be specified in a single place instead of being repeated for every "config" or "options" parameter.

Schema

config_element = element config {
  config_content  &  config_attributes  &  foreign_nodes
}
config_content = (
  descriptive_elements  &  
  property_element*  &  properties_element*
)
config_attributes = (
  name
)

Child content

This element might contain any of the following sub-elements:


Attribute summary

AttributeDescriptionTypeRequiredDefault
name The name by which this <config> element can be referenced. The name MUST be globally unique within the context of a particular JavaScript library. String yes none


Additional information

For API metadata, the developer tool MUST implement scoping logic when searching for <config> elements that a 'datatype' attribute references. If the 'datatype' attribute is within an element that is a descendant of a <class>, <interface>, <mixin> or <singleton> element, then the developer tool MUST first search for <config> elements with the given name attribute that are either direct children of the given ancestor element or the direct children of a <configs> element that itself is a direct child of the given ancestor element. If not found, then the developer tool MUST search for <config> elements with the given name attribute that are either direct children of the root <api> element or the direct children of a <configs> element that itself is a direct child of the root <api> element. The developer tool MUST ignore all other <config> elements in the metadata file, such as <config> elements that descend from other <class>, <interface>, <mixin> or <singleton> elements.

Consider the following metadata structure:

[01] <api ...>
[02]   <config name="config1">...</config>
[03]   <config name="config2">...</config>
[04]   <config name="config3">...</config>
[05]   <class name="class2" ...>
[06]     <config name="config2">...</config>
[07]   </class>
[08]   <class name="class1 ...>
[09]     <config name="config1">...<config>
[10]     <property name="prop1" datatype="config1" .../>
[11]     <property name="prop2" datatype="config2" .../>
[12]     <property name="prop3" datatype="config3" .../>
[13]   </class>
[14] </api>

In the above case, the developer tool MUST do the following:

  • Property prop1 (line 10) MUST use the <config> element from line 09 instead of line 02 because of the rule that the developer tool MUST search the containing <class> element before searching the root <api> element.
  • Property prop2 (line 11) MUST use the <config> element from line 03 and ignore the <config> element on line 06 because of the rule that the developer tool MUST ignore all <config> elements found in other <class>, <interface>, <mixin> or <singleton> elements.
  • Property prop3 MUST use the <config> element from line 04 because there was no <config> element with the name config3 in the containing <class> element.

For widget metadata, the developer tool MUST search for <config> elements with the given name attribute that are either direct children of the root <widget> element or the direct children of a <configs> element that itself is a direct child of the root <widget> element. The developer tool MUST ignore all other <config> elements in the metadata file.

It is important to set the name attribute to a value that will not conflict with other datatypes that might be used in other places within the metadata. Therefore, the name should not match any of standard datatype strings defined in the Datatypes chapter or any other names that might be used as a datatype (e.g., class names).


Details about outputFormat and outputDefault attributes

The outputFormat and outputDefault attributes are applicable only when the property's 'datatype' is a JavaScript Date object. The outputFormat attribute specifies the date/time formatting string when the user supplies an explicit value for this property. The outputDefault attribute specifies the date/time formatting string when the user does not supply an explicit value for this property.

These attributes specify the following date/time substitution patterns that describe how to format the property value when placed into text content:

  • all occurrences of YYYY are replaced with the string representation of the year
  • all occurrences of MM are replaced with the string representation of the month (1-12)
  • all occurrences of DD are replaced with the string representation of the day (1-31)
  • all occurrences of hh are replaced with the string representation of the hour (0-23)
  • all occurrences of mm are replaced with the string representation of the minute (0-59)
  • all occurrences of ss are replaced with the string representation of the second (0-59)
  • all occurrences of ms are replaced with the string representation of the millisecond (0-999)
  • all other characters from the outputFormat string are copied into the result string

To illustrate,

  • If outputFormat="YYYYMMDD" and the date value is March 15, 2009, then the generated string would be "20091503"
  • If outputFormat="YYYY-MM-DD" and the date value is March 15, 2009, then the generated string would be "2009-15-03"
  • If outputFormat="YYYY/MM/DD" and the date value is March 15, 2009, then the generated string would be "2009/15/03"
  • If outputFormat="hello", then the generated string would be "hello" (no substitution matches)

Developer tools MUST put leading zeroes on values. Therefore, March MUST be '03' and not '3'.

If the user specifies a property value and outputFormat is not specified, then the generated string output for a Date value MUST be expressed using the "Date Time String Format" defined in the ECMAScript5 specification. If the user does not specify a property value and outputDefault is not specified, then the developer tool MUST use the date/time formatting string specified for the outputFormat attribute if provided, otherwise MUST be expressed using the "Date Time String Format" defined in the ECMAScript5 specification.

The processing model for outputFormat and outputDefault presumes that the developer tool has a timezone-aware date/time value in hand (for browser-based tools, this would be a JavaScript Date object).

If the user does not supply a property value, and the defaultValue is not specified within the metadata file, then developer tool SHOULD attempt to use the run-time current date and time as the default value. If using the run-time data/time value is not feasible, then developer tools MAY use the design-time date/time value.

Examples

The following examples illustrate the use of the outputFormat and outputDefault attributes, including how they relate to the defaultValue attribute. Each example makes use of the following <javascript> template to illustrate what the final output will be.

<javascript><![CDATA[
var w = new CalendarWidget("div1", { hilightedDate: @@hdate@@ });
]]> </javascript>

The examples assume:

  • A design-time developer tool
  • The design-time date/time is 2007-07-31T10:00:00-08:00 (the 31st day of the 7th month in 2007, 10 o'clock in the -8 UTC time zone)
  • The developer tool uses the design-time date/time value (e.g., 2007-07-31T10:00:00-08:00) as the default date/time
  • In the examples where the user changes the property value, the user's value will be 2011/12/13 (the 13th day of the 12th month in 2011) at 10:20am in the +1 UTC time zone (i.e., 2011-12-13T10:20:00+01:00)

The examples illustrate what code to generate using a specific <javascript> template and a specific combination of property attributes. The code that is generated is not necessarily valid JavaScript.

Example 1

<property name="hdate" datatype="Date">

In this example, the user does not change the value of the property. defaultValue, outputFormat, and outputDefault are not specified. Since the design-time date/time is 2007-07-31T10:00:00-08:00, the result is:

var w = new CalendarWidget("div1", { hilightedDate: 2007-07-31T10:00:00-08:00 });

Example 2

<property name="hdate" datatype="Date" defaultValue="2009-12-25T10:00:00+07:00">

In this example, the user does not change the value of the property. defaultValue is specified, outputFormat, and outputDefault are not. We get a formatted version of the default value using the "Date Time String Format" defined in the ECMAScript5 specification.

var w = new CalendarWidget("div1", { hilightedDate: 2009-12-25T10:00:00+07:00 });

Example 3

<property name="hdate" datatype="Date" outputFormat="MM/DD/YYYY">

In this example, the user does not change the value of the property. outputFormat is specified, but defaultValue and outputDefault are not. Since the design-time date/time is 2007-07-31T10:00:00-08:00, the result is the design-time date/time written out with the format specified by the outputFormat attribute:

var w = new CalendarWidget("div1", { hilightedDate: 07/31/2007 });

Example 4

<property name="hdate" datatype="Date" 
          defaultValue="2009-12-25T10:00:00+07:00" outputFormat="MM/DD/YYYY">

In this example, the user does not change the value of the property. defaultValue and outputFormat are specified, but outputDefault is not. We get the specified date written out in the format specified by the outputFormat attribute:

var w = new CalendarWidget("div1", { hilightedDate: 12/25/2009 });

Example 5

<property name="hdate" datatype="Date" outputDefault="MM/DD/YYYY">

In this example outputDefault is specified, but defaultValue and outputFormat are not. There are actually 2 possible outcomes for this particular example:

Example 5a

The user does not change the value of the property, so the developer tool uses the current design-time data/time value for the property during code generation. The result is:

var w = new CalendarWidget("div1", { hilightedDate: 07/31/2007 });
Example 5b

The user changes the value of the property (to 2011-12-13T10:20:00+01:00 per assumptions above), so the developer tool uses the format specified by the outputFormat attribute. Since outputFormat is *NOT* specified, the "Date Time String Format" defined in the ECMAScript5 specification is used.

var w = new CalendarWidget("div1", { hilightedDate: 2011-12-13T10:20:00+01:00 });

Example 6

<property name="hdate" datatype="Date" outputDefault="null">

This example is identical to Example 5 except that the outputDefault formatting makes no use of the output template syntax. Because of this, when the default value is applied and the developer tool processes the outputDefault template, the result is a value that exactly matches the original outputDefault attribute value. The result is that anytime the defaultValue is used, a "null" is written out in its place. As with Example 5, there are 2 possible outcomes for this example:

Example 6a

The user does not change the value of the property, so the developer tool uses the default value for the property during code generation. The result is:

var w = new CalendarWidget("div1", { hilightedDate: null });
Example 6b

The user changes the value of the property (to 2011-12-13T10:20:00+01:00 per assumptions above), so the developer tool uses the format specified by the outputFormat attribute. Since outputFormat is *NOT* specified, the "Date Time String Format" defined in the ECMAScript5 specification is used.

var w = new CalendarWidget("div1", { hilightedDate: 2011-12-13T10:20:00+01:00 });

Example 7

<property name="hdate" datatype="Date" 
          defaultValue="2009-12-25T10:00:00+07:00" outputDefault="null">

In this example defaultValue and outputDefault are specified, but outputFormat is not. The handling of this example should be identical to the handling for Example 5 and Example 6 except that the default date/time, if used, would be the one specified instead of the design-time date/time.

Example 7a

The user does not change the value of the property, so the developer tool uses the default value for the property during code generation. The result is:

var w = new CalendarWidget("div1", { hilightedDate: null });
Example 7b

The user changes the value of the property (to 2011-12-13T10:20:00+01:00 per assumptions above), so the developer tool uses the format specified by the outputFormat attribute. Since outputFormat is *NOT* specified, the "Date Time String Format" defined in the ECMAScript5 specification is used..

var w = new CalendarWidget("div1", { hilightedDate: 2011-12-13T10:20:00+01:00 });

Example 8

<property name="hdate" datatype="Date" 
          outputFormat="MM/DD/YYYY" outputDefault="null">

In this example outputFormat and outputDefault are specified but defaultValue is not.

Example 8a

The user does not change the value of the property, so the developer tool uses the default value for the property during code generation. The result is:

var w = new CalendarWidget("div1", { hilightedDate: null });
Example 8b

The user changes the value of the property (to 2011-12-13T10:20:00+01:00 per assumptions above), so the developer tool uses the format specified by the outputFormat attribute.

var w = new CalendarWidget("div1", { hilightedDate: 12/13/2011 });

Example 9

<property name="hdate" datatype="Date" 
          defaultValue="2009-12-25T10:00:00+07:00" outputFormat="MM/DD/YYYY" outputDefault="null">

In this example defaultValue, outputFormat and outputDefault are all provided. There are 2 possible outcomes:

Example 9a

The user does not change the value of the property, so the developer tool uses the default value for the property during code generation. The result is:

var w = new CalendarWidget("div1", { hilightedDate: null });
Example 9b

The user changes the value of the property (to 2011-12-13T10:20:00+01:00 per assumptions above), so the developer tool uses the format specified by the outputFormat attribute.

var w = new CalendarWidget("div1", { hilightedDate: 12/13/2011 });

Example 10

<property name="hdate" datatype="Date" 
          defaultValue="2009-12-25T10:00:00+07:00" outputFormat="MM/DD/YYYY" outputDefault="MM-DD-YYYY">

This example is identical to Example 9, but just to be complete we give an example of an outputDefault value that actually uses the template syntax. There are 2 possible outcomes:

Example 10a

The user does not change the value of the property, so the developer tool uses the default value for the property during code generation. The result is:

var w = new CalendarWidget("div1", { hilightedDate: 12-25-2009 });
Example 10b

The user changes the value of the property (to 2011-12-13T10:20:00+01:00 per assumptions above), so the developer tool uses the format specified by the outputFormat attribute.

var w = new CalendarWidget("div1", { hilightedDate: 12/13/2011 });

Example 11

<property name="hdate" datatype="Date" 
          outputFormat="new Date('MM/DD/YYYY')" outputDefault="null">

In this example outputFormat and outputDefault are provided, but defaultValue is not specified. There are 2 possible outcomes:

Example 11a

The user does not change the value of the property, so the developer tool uses the default value for the property during code generation. The result is:

var w = new CalendarWidget("div1", { hilightedDate: null });
Example 11b

The user changes the value of the property (to 2011-12-13T10:20:00+01:00 per assumptions above), so the developer tool uses the format specified by the outputFormat attribute.

var w = new CalendarWidget("div1", { hilightedDate: new Date('12/13/2011') });


Pattern attributes

This section describes the rules and processing model for the following "pattern attributes":

  • getterPattern
  • setterPattern
  • registerHandlerPattern
  • unregisterHandlerPattern

These pattern attributes only apply to JavaScript APIs and are not applicable to OpenAjax Widgets.

getterPattern and setterPattern attributes

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.

Developer tools can identify the getter and setter function names using pattern recognition, which the developer tool might leverage to provide more useful code completion features. For example:

<property name="Color" getterPattern="get{{property}}()" setterPattern="set{{property}}({{value}})"/>

indicates that the getter function has the signature getColor() and the setter pattern has the signature setColor(colorvalue).

Both getterPattern and setterPattern are inheritable. For more information, see Inheritance and defaults, below.

registerHandlerPattern and unregisterHandlerPattern attributes

The registerHandlerPattern and unregisterHandlerPattern attributes apply to the <event> element and specify the name patterns for the event handler registration and unregistration functions for that event. For example:

<event name="locationChange">
  <handlerFunction registerHandlerPattern="{{event}}Handler({{callback}})">
    <parameter name="lat" datatype="Number"/>
    <parameter name="long" datatype="Number"/>
  </handlerFunction>
</event>

In the above example, the function to register an event handler is named locationChangeHandler and which takes a single parameter, which is the callback function. The callback function will receive two parameters, both of which are Number values.

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

For getterPattern and setterPattern, 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 for this property.

For registerHandlerPattern and unregisterHandlerPattern, there are four substitution strings, delimited by double-braces:

  • {{event}}: The name of the event (corresponds to the 'name' attribute on the <event> element)
  • {{eventUCFirst}}: Same as {{event}}, except that the first letter of the event name has been transformed into upper case (equivalent to the toUpperCase method in ECMAScript 262)
  • {{eventLCFirst}}: Same as {{event}}, except that the first letter of the event name has been transformed into lower case (equivalent to the toLowerCase method in ECMAScript 262)
  • {{callback}}: The callback function (a JavaScript Function object).

getterPattern and setterPattern examples

Example:

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

In the example above:

  • The property getter function has the following signature: <object>.color.get();
  • The property setter function has the following signature: <object>.color.set(value);

Example:

<property name="color"
          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 = <object>.getValue('color');
  • Runtime JavaScript logic can set the property value via <object>.setValue('color','blue');

Example:

<property name="color"
          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 = <object>.getColorValue();
  • Runtime JavaScript logic can set the property value via <object>.setColorValue('blue');

Inheritance and defaults

getterPattern, setterPattern, registerHandlerPattern and unregisterHandlerPattern attributes are inheritable from their ancestor elements.

If either of getterPattern or setterPattern exists on a given <property> element, then that attribute value takes precedence over any inherited values. If one of these attributes does not exist on a given <property> element, then the developer tool MUST find the nearest ancestor element that has the given attribute and use the attribute value from that ancestor. If no ancestors have the given attribute, then there is no value to inherit; the attribute is unspecified.

Similarly, if either of registerHandlerPattern or unregisterHandlerPattern exists on a given <handlerFunction> element, then that attribute value takes precedence over any inherited values.

If the attribute is unspecified after inheritance, then the developer tool MUST assume that there is no corresponding function. For example, if getterPattern is unspecified, there is no corresponding getter function.


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