OpenAjax Metadata 1.0 Specification Properties
From MemberWiki
NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.
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):
- Widget Metadata elements:
- API Metadata elements:
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.
- <property> element: defines a property
- <properties> element: defines a group of properties
- <childProperties> element: defines a group of properties that are attached onto child elements
- <config> element: defines a JavaScript object (or object literal) that can be referred to by a 'datatype' attribute
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:
- descriptive_elements such as <description> and <example>
- compatibility_elements such as <available> and <deprecated>
- <option>, <options>
- <parameter>, <parameters>
- <property>, <properties>
- <returnType>, <returnTypes>
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
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
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:00Z | Jan. 20, 2009, 13:00 in UTC (coordinated universal time) |
2009-01-20T08:00-05 | Jan. 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:
- Zero or more
<property>
sub-elements. - Zero or more
<properties>
sub-elements. (Nested<properties>
elements can be used to specify hierarchical groupings of properties.) - descriptive_elements such as <description> and <example>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
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:
- descriptive_elements such as <description> and <example>
- Zero or more
<property>
child elements. For additional information about plural elements such as<childProperties>
, refer to the Plural and Singular Elements chapter.
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
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:
- descriptive_elements such as <description> and <example>
- Zero or more
<property>
as direct children of the<config>
element - A single
<properties>
child element, which in turn contains zero or more<property>
child elements
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
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
(line10
) MUST use the<config>
element from line09
instead of line02
because of the rule that the developer tool MUST search the containing <class> element before searching the root <api> element. - Property
prop2
(line11
) MUST use the<config>
element from line03
and ignore the<config>
element on line06
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 line04
because there was no<config>
element with the nameconfig3
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 thetoUpperCase
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 thetoLowerCase
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 thetoUpperCase
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 thetoLowerCase
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.