OpenAjax Metadata 1.0 Specification API Metadata
From MemberWiki
NOTE: This wiki page holds part of the OpenAjax Metadata 1.0 Specification.
Contents |
Chapter 6: API Metadata
Introduction
This chapter defines the OpenAjax Metadata XML grammar for the runtime JavaScript APIs (e.g., classes and methods) that are available for a given Ajax library.
The following elements are defined in this chapter:
- <api>
- <alias>
- <ancestor>
- <class>
- <constructor>
- <event>
- <exception>
- <globals>
- <handlerFunction>
- <interface>
- <method>
- <mix>
- <mixin>
- <namespace>
- <parameter>
- <returnType>
- <singleton>
The following elements are defined in subsequent chapters:
- <property>
- <description>
- <title>
- <shortDescription>
- <example>
- <remarks>
- <reference>
- <author>
- <license>
- <available>
- <deprecated>
- <useragent>
- <config>
- <enum>
- <option>
- Plural elements: <aliases>, <ancestors>, <classes>, <constructors>, <events>, <exceptions>, <interfaces>, <methods>, <mixes>, <mixins>, <namespaces>, <parameters>, <returnTypes>, <singletons>
Additional information about API Metadata can be found in:
- Properties chapter
- Datatypes chapter
- Descriptive elements and attributes chapter
- Compatibility elements and attributes chapter
- Localization chapter
- Variable Substitution chapter
Common attributes
The following attributes are available on multiple elements defined in this chapter:
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
scope | Whether this feature is instance-based or static. | instance|static | no | instance |
visibility | Intended visibility of this feature to other parts of the JavaScript application. | public|private|protected|internal|protected-internal | no | public |
Attribute details
'scope' attribute
The scope
attribute specifies whether the feature belongs to the class itself or to instances of the class. A value of instance
indicates that the given feature is available only after an instance of this class has been created. A value of static
indicates that this feature belongs to the class itself and does not require object instantiation.
'visibility' attribute
The visibility
attribute specifies the intended visibility of the feature to other parts of the JavaScript application. Its value can be any of the following access modifiers:
-
public
indicates that the given feature is intended to be available to any code within the application. (This is the default.) -
private
indicates that the given feature is intended to be available only within the <class> or <singleton> itself. Private features are not intended to be available to derived classes. -
protected
indicates that the given feature is intended to be available only within the <class> or <singleton> itself and to derived classes. -
internal
indicates that the given feature is intended to be public across the class's top-level namespace (including all descendant namespaces, classes and singletons), but private to JavaScript logic outside of the top-level namespace. (For the purposes of this attribute, if a class has the name "aaa.bbb.ccc", then "aaa" and "aaa.bbb" are considered namespaces, and "aaa" is the top-level namespace.) -
protected-internal
indicates that access to the given feature is the union of the access granted byprotected
and the access granted byinternal
.
<api>
The <api>
element is the root element of an OpenAjax Metadata file that defines JavaScript APIs.
An Ajax library may define all of its APIs within a single OpenAjax Metadata file or split the API definitions across multiple OpenAjax Metadata files. (For additional information, refer to the File naming conventions section in the Introduction.)
Schema
api_element = element api { api_content & api_attributes & foreign_nodes } api_content = ( descriptive_elements & class_element* & classes_element* & config_element* & configs_element* & enum_element* & enums_element* & globals_element* & interface_element* & interfaces_element* & license_element? & locale_element* & mixin_element* & mixins_element* & namespace_element* & namespaces_element* & singleton_element* & singletons_element* ) api_attributes = ( lang? & language? & spec & version? & pattern_attributes )
Child content
This element might contain any of the following sub-elements:
- descriptive_elements such as <description> and <example>
- <class>, <classes>
- <config>, <configs>
- <enum>, <enums>
- <globals>
- <interface>, <interfaces>
- <license>
- <locale>
- <mixin>, <mixins>
- <namespace>, <namespaces>
- <singleton>, <singletons>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
language | Programming language to which the API metadata applies. | String (see below) | no | javascript |
spec | Version number of the OpenAjax Metadata spec to which this metadata file conforms. | Version string (see below) | yes | none |
version | Version number for the JavaScript APIs that are described by this metadata file. | Version string (see below) | no | none |
lang | Identifies the natural or formal language for the content. Defined in Localization chapter. | |||
pattern_attributes | Attributes 'getterPattern', 'setterPattern', 'registerHandlerPattern' and 'unregisterHandlerPattern'. Defined in Pattern attributes section in Properties chapter. |
Attribute details
'language' attribute
The language
attribute specifies the programming language for which the API metadata applies. The default is "javascript", which indicates the various versions of the language whose standard is named "ECMAScript" (e.g., ECMA-262).
'spec' attribute
The spec
attribute specifies the version number of the OpenAjax Metadata spec to which this metadata file conforms. (See the write-up on Version number attributes in the Compatibility chapter for rules on version number attributes.)
'version' attribute
The version
attribute specifies the version number for the group of JavaScript APIs (i.e., the library) described by this metadata file. (See the write-up on Version number attributes in the Compatibility chapter for rules on version number attributes.)
<alias>
The <alias>
element can be used to specify an alternate name for a class or singleton that a developer tool might use during content assist. Typically, the alternate name is shorter and/or more understandable that the original name.
Schema
alias_element = element alias { alias_content & alias_attributes & foreign_attributes } alias_content = ( empty ) alias_attributes = ( name )
Child content
<alias>
must be an empty element (i.e., no child content).
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
name | Name of the alias. | String | yes | none |
Attribute details
'name' attribute
The name
attribute specifies the name of the alias.
The name MUST be globally unique within the context of a particular JavaScript library.
Additional information
Example:
<class name="jQuery"> <alias name="$" /> </class>
<ancestor>
The <ancestor>
element specifies (via the datatype
attribute) a "superclass" for the current class or interface.
Schema
ancestor_element = element ancestor { ancestor_content & ancestor_attributes & foreign_attributes } ancestor_content = ( empty ) ancestor_attributes = ( datatype )
Child content
<ancestor>
must be an empty element (i.e., no child content).
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
datatype | Name of an ancestor <class> , <interface> , <mixin> or <singleton> . |
String (see below) | yes | none |
Attribute details
'datatype' attribute
The datatype
attribute specifies the name of a <class>
, <interface>
, <mixin>
or <singleton>
whose <property>
, <method>
, <event>
, <alias>
, <ancestor>
, <config>
, <constructor>
, <event>
and <mix>
elements are included within the current class. For additional information, refer to the detailed specification for the 'datatype' attribute in the Datatypes chapter.
<class>
The <class>
element describes a JavaScript class.
Schema
class_element = element class { class_content & class_attributes & foreign_nodes } class_content = ( descriptive_elements & compatibility_elements & alias_element* & aliases_element* & ancestor_element* & ancestors_element* & config_element* & configs_element* & constructor_element* & constructors_element* & event_element* & events_element* & mix_element* & mixes_element* & method_element* & methods_element* & property_element* & properties_element* ) class_attributes = ( name & visibility? & pattern_attributes & registerCallbackPattern? & unregisterCallbackPattern? )
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>
- <alias>, <aliases>
- <ancestor>, <ancestors>
- <config>, <configs>
- <constructor>, <constructors>
- <event>, <events>
- <mix>, <mixes>
- <method>, <methods>
- <property>, <properties>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
name | Absolute object name for the class. | String (see below) | yes | none |
visibility | Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section. | |||
pattern_attributes | Attributes 'getterPattern' and 'setterPattern'. Defined in Pattern attributes section in Properties chapter. | |||
registerCallbackPattern | Specifies the name pattern for the event handler registration function. Defined in Properties chapter. | |||
unregisterCallbackPattern | Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter. |
Attribute details
'name' attribute
The name
attribute specifies the absolute object name for the class using JavaScript dot notation, such as "FooToolkit.io.httpreq" (where the Foo toolkit has a main global object called "FooToolkit" and a subobject "io" with subobject "httpreq", which is set up as a JavaScript class with an appropriate constructor function).
The name MUST be globally unique within the context of a particular JavaScript library.
<constructor>
The <constructor>
element describes a constructor method. A constructor can be described by multiple <constructor>
elements, in which case the different <constructor>
elements can be used to specify different parameter and return value alternatives.
If no <returnType>
is specified, the constructor method is assumed to return an instance of the class.
Schema
constructor_element = element constructor { constructor_content & constructor_attributes & foreign_nodes } constructor_content = ( descriptive_elements & compatibility_elements & exception_element* & exceptions_element* & parameter_element* & parameters_element* & returnType_element* & returnTypes_element* ) constructor_attributes = ( visibility? )
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>
- <exception>, <exceptions>
- <parameter>, <parameters>
- <returnType>, <returnTypes>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
visibility | Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section. |
Example
<class name="jQuery"> <constructor> <shortDescription>This function accepts a string containing a CSS selector which is then used to match a set of elements.</shortDescription> <description> The core functionality of jQuery centers around this function. Everything in jQuery is based upon this, or uses this in some way. The most basic use of this function is to pass in an expression (usually consisting of CSS), which then finds all matching elements. By default, if no context is specified, $() looks for DOM elements within the context of the current HTML document. If you do specify a context, such as a DOM element or jQuery object, the expression will be matched against the contents of that context. </description> <!-- parameters here --> <returnType datatype="jQuery"/> <!-- examples here --> </constructor> <!-- more constructors here --> </class>
<event>
The <event>
element is used to describe various aspects of library-specific events, such as the naming pattern used by the library for functions to register and unregister event handlers.
Schema
event_element = element event { event_content & event_attributes & foreign_nodes } event_content = ( descriptive_elements & compatibility_elements & handlerFunction_element? ) event_attributes = ( name & registerCallbackPattern? & unregisterCallbackPattern? & visibility? )
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>
- <handlerFunction>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
name | Name of the event. | String (see below) | yes | none |
registerCallbackPattern | Specifies the name pattern for the event handler registration function. Defined in Properties chapter. | |||
unregisterCallbackPattern | Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter. | |||
visibility | Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section. |
Attribute details
'name' attribute
The name
attribute specifies the name of the event.
The name MUST be globally unique within the context of current container object.
<exception>
The <exception>
element describes an exception that a JavaScript function might throw.
Schema
exception_element = element exception { exception_content & exception_attributes & foreign_nodes } exception_content = ( descriptive_elements & compatibility_elements & parameter_element* & parameters_element* & property_element* & properties_element* & returnType_element* & returnTypes_element* ) exception_attributes = ( datatype? )
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>
- <parameter>, <parameters>
- <property>, <properties>
- <returnType>, <returnTypes>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
datatype | Class name for the exception object. | String (see below) | no | Error |
Attribute details
'datatype' attribute
The datatype
attribute specifies the class name for the exception object. See the Datatypes chapter for the detailed definition of this attribute.
<globals>
The <globals>
element describes properties and methods that are global to the JavaScript runtime environment (i.e., available directly from the JavaScript window
object) and therefore not contained within a particular namespace or class.
Schema
globals_element = element globals { globals_content & globals_attributes & foreign_nodes } globals_content = ( property_element* & properties_element* & method_element* & methods_element* ) globals_attributes = ( pattern_attributes )
Child content
This element might contain any of the following sub-elements:
Attribute summary
pattern_attributes | Attributes 'getterPattern' and 'setterPattern'. Defined in Pattern attributes section in Properties chapter. |
<handlerFunction>
The <handlerFunction>
element is an optional child element to the <event>
element that can be used to describe the naming pattern for the function that registers an event handler for the event and to describe the parameters to the event handler function.
Schema
handlerFunction_element = element handlerFunction { handlerFunction_content & handlerFunction_attributes & foreign_nodes } handlerFunction_content = ( descriptive_elements & compatibility_elements & exception_element* & exceptions_element* & parameter_element* & parameters_element* & returnType_element* & returnTypes_element* ) handlerFunction_attributes = ( registerCallbackPattern? & unregisterCallbackPattern? )
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>
- <exception>, <exceptions>
- <parameter>, <parameters>
- <returnType>, <returnTypes>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
registerCallbackPattern | Specifies the name pattern for the event handler registration function. Defined in Properties chapter. | |||
unregisterCallbackPattern | Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter. |
Example
In the following example, the function to register an event handler is named locationChangeHandler
. It takes a single parameter, which is the callback function. This callback function will be passed two parameters, both of which are Number
values.
<event name="locationChange"> <handlerFunction registerCallbackPattern="{{event}}Handler({{callback}})"> <parameter name="lat" datatype="Number"/> <parameter name="long" datatype="Number"/> </handlerFunction> </event>
<interface>
The <interface>
element describes a logical group of JavaScript features (e.g., methods and properties) that are used as a superclass by other classes or interfaces. Typically, <interface>
elements are referenced by <ancestor>
elements.
Schema
interface_element = element interface { interface_content & interface_attributes & foreign_nodes } interface_content = ( descriptive_elements & compatibility_elements & ancestor_element* & ancestors_element* & config_element* & configs_element* & constructor_element* & constructors_element* & event_element* & events_element* & mix_element* & mixes_element* & method_element* & methods_element* & property_element* & properties_element* ) interface_attributes = ( name & visibility? & pattern_attributes & registerCallbackPattern? & unregisterCallbackPattern? )
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>
- <ancestor>, <ancestors>
- <config>, <configs>
- <constructor>, <constructors>
- <event>, <events>
- <mix>, <mixes>
- <method>, <methods>
- <property>, <properties>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
name | Absolute object name for the interface. | String | yes | none |
pattern_attributes | Attributes 'getterPattern' and 'setterPattern'. Defined in Pattern attributes section in Properties chapter. | |||
registerCallbackPattern | Specifies the name pattern for the event handler registration function. Defined in Properties chapter. | |||
unregisterCallbackPattern | Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter. | |||
visibility | Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section. |
Attribute details
'name' attribute
The name
attribute specifies the absolute object name for the interface using JavaScript dot notation, such as "FooToolkit.io.httpreq" (where the Foo toolkit has a main global object called "FooToolkit", a subobject "io", with subobject "httpreq" which is set up as a JavaScript interface).
The name MUST be globally unique within the context of a particular JavaScript library.
<method>
The <method>
element describes a JavaScript function that is not used as a constructor.
Schema
method_element = element method { method_content & method_attributes & foreign_nodes } method_content = ( descriptive_elements & compatibility_elements & exception_element* & exceptions_element* & parameter_element* & parameters_element* & returnType_element* & returnTypes_element* ) method_attributes = ( name & scope? & visibility? )
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>
- <exception>, <exceptions>
- <parameter>, <parameters>
- <returnType>, <returnTypes>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
name | JavaScript name for this function. | String | yes | none |
scope | Whether this feature is instance-based or static. Defined in Common attributes section. | |||
visibility | Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section. |
Attribute details
'name' attribute
The name
attribute specifies the JavaScript name for this function.
The name MUST be globally unique within the context of current container object.
Example
<method name="addClass" scope="instance"> <shortDescription>Adds the specified class(es) to each of the set of matched elements.</shortDescription> <parameters> <parameter name="class" datatype="String" usage="required"> <description>One or more classes to add to the elements; these are separated by spaces.</description> </parameter> </parameters> <returnType datatype="jQuery"/> <! -- examples here --> </method>
<mix>
The <mix>
element indicates that methods and properties (and other features) from another object are copied (i.e., mixed in) into this object. The datatype
attribute specifies the name of a <class>
, <interface>
, <mixin>
or <singleton>
whose <property>
, <method>
, <event>
, <alias>
, <ancestor>
, <config>
, <constructor>
, <event>
and <mix>
elements are included within the current class. This element can be used to mix in either a set of methods and properties or (if the fromProperty
attribute has a value) an individual method or property.
Schema
mix_element = element mix { mix_content & mix_attributes & foreign_nodes } mix_content = ( descriptive_elements ) mix_attributes = ( datatype & fromProperty? & toProperty? & fromScope? & toScope? )
Child content
This element might contain any of the following sub-elements:
- descriptive_elements such as <description> and <example>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
datatype | Reference to an element whose features should be mixed in. | String (see below) | yes | none |
fromProperty | Name of single method or property to be mixed in. | String | no | (see below) |
fromScope | Whether to mix in the properties and methods of an object instance or of the class. | instance|static | no | instance |
toProperty | Name for method or property when mixed in. | String | no | value of fromProperty |
toScope | Whether to mix into object instance or class. | instance|static | no | value of fromScope |
Attribute details
'datatype' attribute
The datatype
attribute is a reference to the name of the element whose features should be mixed in.
'fromProperty' attribute
If the fromProperty
attribute has a value and is not the empty string, then only a single method or property will be mixed in. The fromProperty
attribute provides the name of the property that is to be copied from the referenced <mixin>
, <interface>
, <class>
or <singleton>
element.
'fromScope' attribute
The fromScope
attribute applies to properties and methods. A value of "instance" indicates that all instance properties and methods should be mixed in. A value of "static" indicates that all static properties and methods should be mixed in.
(See the description of the scope
attribute.)
'toProperty' attribute
The toProperty
attribute provides the name for the mixed-in property when placed on the given
<mixin>
, <interface>
, <class>
or <singleton>
.
If not specified or if it is the empty string, then the mixed-in property's name has the same name as the fromProperty
. This attribute is ignored if no fromProperty
attribute is present.
'toScope' attribute
The toScope
attribute applies to properties and methods. A value of "instance" indicates that all properties and methods should be mixed in on an instance basis. A value of "static" indicates that all properties and methods should mixed in on a static basis. (See the description of the scope
attribute.)
<mixin>
The <mixin>
element defines a collection of methods, properties, etc. that are available to be mixed into other classes (i.e., referred to by a <mix> element). Mixins are parallel to classes and singletons (whose methods and properties can also be mixed into other classes); unlike the methods and properties inside <class>
and <singleton>
elements, those inside <mixin>
elements are *only* available for mixing and do not have any meaning on their own.
Schema
mixin_element = element mixin { mixin_content & mixin_attributes & foreign_nodes } mixin_content = ( descriptive_elements & config_element* & configs_element* & constructor_element* & constructors_element* & event_element* & events_element* & mix_element* & mixes_element* & method_element* & methods_element* & property_element* & properties_element* ) mixin_attributes = ( name & scope? & visibility? & pattern_attributes & registerCallbackPattern? & unregisterCallbackPattern? )
Child content
This element might contain any of the following sub-elements:
- <config>, <configs>
- <constructor>, <constructors>
- <event>, <events>
- <mix>, <mixes>
- <method>, <methods>
- <property>, <properties>
- descriptive_elements such as <description> and <example>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
name | Absolute object name for the mixin. | String (see below) | yes | none |
scope | Whether this feature is instance-based or static. Defined in Common attributes section. | |||
visibility | Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section. | |||
pattern_attributes | Attributes 'getterPattern' and 'setterPattern'. Defined in Pattern attributes section in Properties chapter. | |||
registerCallbackPattern | Specifies the name pattern for the event handler registration function. Defined in Properties chapter. | |||
unregisterCallbackPattern | Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter. |
Attribute details
'name' attribute
The name
attribute specifies the absolute object name for the mixin using JavaScript dot notation, such as "FooToolkit.io.httpreq" (where the Foo toolkit has a main global object called "FooToolkit", a subobject "io", with subobject "httpreq" which is set up as a JavaScript class with an appropriate constructor function).
The name MUST be globally unique within the context of a particular JavaScript library.
<namespace>
The <namespace>
element can be used to describe a JavaScript object that is a base object for other JavaScript classes but which itself is not a class (i.e., there is no constructor which creates instances of this object). For example, suppose there is a class named "MyLibrary.io.xhr" where the "xhr" object has a constructor, but "MyLibrary" and "io" do not. In this case, "MyLibrary" and "MyLibrary.io" are candidates for the <namespace>
element.
Schema
namespace_element = element namespace { namespace_content & namespace_attributes & foreign_nodes } namespace_content = ( descriptive_elements ) namespace_attributes = ( name & visibility? )
Child content
This element might contain any of the following sub-elements:
- descriptive_elements such as <description> and <example>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
name | Absolute object name for the namespace. | String (see below) | yes | none |
visibility | Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section. |
Attribute details
'name' attribute
The name
attribute specifies the absolute object name for the namespace using JavaScript dot notation, such as "FooToolkit.io.httpreq" (where the Foo toolkit has a main global object called "FooToolkit", a subobject "io", with subobject "httpreq").
The name MUST be globally unique within the context of a particular JavaScript library.
<parameter>
The <parameter>
element describes a parameter to a JavaScript function.
Schema
parameter_element = element parameter { parameter_content & parameter_attributes & foreign_nodes } parameter_content = ( descriptive_elements & compatibility_elements & option_element* & options_element* & parameter_element* & parameters_element* & property_element* & properties_element* & returnType_element* & returnTypes_element* ) parameter_attributes = ( datatype? & name & usage? & datatype_supplemental_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>
- <config>, <configs>
- <returnType>, <returnTypes>
This element MAY contain <property>
or <properties>
sub-elements only when the datatype attribute is set to or allows the value type "Object". In this case, the <property>
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 "Function". In this case, the <parameter>
and <returnType>
elements provide descriptive detail about the parameters and return types for the Function.
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
name | Name of the parameter. | String (see below) | yes | none |
datatype | Allowed datatype(s) for the parameter. | String (see below) | no | String |
usage | Whether the parameter is required or optional and whether a variable number of values may be provided. | required|optional|zero-or-more|one-or-more | no | required |
datatype_supplemental_attributes | Various attributes that provide additional information about the datatype, such as min and max values. Defined in Datatypes chapter. |
Attribute details
'name' attribute
The name
attribute specifies the name of the parameter. The name MUST be globally unique within the context of current container object.
'datatype' attribute
The datatype
attribute specifies the allowed datatype(s) for the parameter. See the Datatypes chapter for the detailed definition of this attribute.
'usage' attribute
The usage
attribute specifies whether the parameter is required or optional and whether a variable number of values may be provided (i.e., zero-or-more or one-or-more). Permissible values are:
-
required
(the default value for this attribute) -
optional
-
zero-or-more
-
one-or-more
Example
<method name="animate" scope="instance"> <shortDescription>A function for making custom animations.</shortDescription> <parameters> <parameter name="params" datatype="Object" usage="required"> <description>A set of style attributes that you wish to animate, and to what end.</description> <properties> <property name="duration" datatype="String|Number" defaultValue="normal"> <description>A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).</description> </property> <property name="easing" datatype="String" defaultValue=""swing""> <description>The name of the easing effect that you want to use (plugin required). There are two built-in values, "linear" and "swing".</description> </property> <property name="complete" datatype="Function" defaultValue=""> <description>A function to be executed whenever the animation completes, executes once for each element animated against.</description> </property> <property name="step" datatype="Function" defaultValue="" /> <property name="queue" datatype="Boolean" defaultValue="true"> <description>Setting this to false will make the animation skip the queue and begin running immediately. (Added in jQuery 1.2)</description> </property> </properties> </parameter> <parameter name="options" datatype="Object" usage="required"> <description>A set of options with which to configure the animation.</description> <properties> <property name="duration" datatype="String|Number" defaultValue="normal"> <description>A string representing one of the three predefined speeds ("slow", "normal", or "fast") or the number of milliseconds to run the animation (e.g. 1000).</description> </property> <property name="easing" datatype="String" defaultValue="swing"> <description>The name of the easing effect that you want to use (plugin required). There are two built-in values, "linear" and "swing".</description> </property> <property name="complete" datatype="Function" defaultValue=""> <description>A function to be executed whenever the animation completes, executes once for each element animated against.</description> </property> <property name="step" datatype="Function" defaultValue="" /> <property name="queue" datatype="Boolean" defaultValue="true"> <description>Setting this to false will make the animation skip the queue and begin running immediately. (Added in jQuery 1.2)</description> </property> </properties> </parameter> </parameters> <returnType datatype="jQuery"/> </method>
<returnType>
The <returnType>
element specifies the datatype of and descriptive information about the value that a method returns.
Schema
returnType_element = element returnType { returnType_content & returnType_attributes & foreign_nodes } returnType_content = ( descriptive_elements & parameter_element* & parameters_element* & property_element* & properties_element* & returnType_element* & returnTypes_element* ) returnType_attributes = ( datatype & paramName? & paramValue? & datatype_supplemental_attributes )
Child content
This element might contain any of the following sub-elements:
- descriptive_elements (various elements, such as <description> and <example>)
- <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 "Object". In this case, the <property>
elements provide descriptive detail about the various properties on the Object.
This element MAY contain <parameter>
, <parameters>
, <returnTypes>
or <returnTypes>
sub-elements only when the datatype attribute is set to or allows the value type "Function". In this case, the <parameter>
and <returnType>
elements provide descriptive detail about the parameters and return types for the Function.
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
datatype | Datatype for the value that the method returns. | String (see below) | yes | none |
paramName | Name of the parameter on which the datatype depends (for factory methods; see below). | String | yes | none |
paramValue | Value of the parameter on which the datatype depends (for factory methods; see below). | String | yes | none |
datatype_supplemental_attributes | Various attributes that provide additional information about the datatype, such as min and max values. Defined in Datatypes chapter. |
Attribute details
'datatype' attribute
The 'datatype' attribute specifies the datatype of the value that the method returns. The detailed specification for the 'datatype' attribute can be found in the Datatypes chapter.
Note, however, for the <returnType>
element, the datatype
attribute includes one additional feature that targets factory methods, where the datatype
attribute can reference one of the method's parameters. See Factory methods below.
'paramName' and 'paramValue' attributes
The paramName
and paramValue
attributes target factory methods where the datatype of the return value is dependent on a parameter whose possible values consists of an enumeration. See Factory methods below.
Factory methods
The <returnType>
element includes special rules to describe factory methods where the return value from the factory method depends on one of the parameters passed into the function. The potential cases are outlined below.
Case 1: Simple factory method
For this case:
- The string value of the
datatype
attribute MUST exactly match the string value of thename
attribute on one of the<parameter>
elements for this method. - The
<returnType>
element does not include attributesparamName
andparamValue
.
If the string value of the <returnType>
element's datatype
exactly matches the name
attribute on one of the <parameter>
elements (and the <returnType>
element does not include paramName
and paramValue
attributes), then the return value from the method is an instance object for the class identified by the value of the referenced <parameter>
.
To illustrate the simple factory method case where the referenced parameter identifies the class using a String, suppose you have the following method definition:
<method name="classFactory1"> <parameter name="classToInstantiate" datatype="String"/> <returnType datatype="classToInstantiate"/> </method>
and suppose that this method might be invoked at runtime by any of the following:
[1] myShape = classFactory1('acme.graphtools.circleClass'); [2] myShape = classFactory1('acme.graphtools.rectClass');
In [1] above, the classFactory1
method returns an instance object for the acme.graphtools.circleClass
class, whereas [2] returns an instance object for the acme.graphtools.rectClass
class.
The next example illustrates the situation where the referenced parameter identifies the class constructor function instead of a String (i.e., datatype="Function"
):
<method name="Sys.Component.create"> <parameter name="componentType" datatype="Function"/> <parameter name="properties" datatype="Object" /> <parameter name="events" datatype="Object" /> <parameter name="references" datatype="Object" /> <parameter name="element" datatype="HTMLElement" /> <returnType datatype="componentType"/> </method>
Suppose that this method might be invoked at runtime by the following:
Sys.Component.create(Sys.UI.DataView, null, null, null, document.getElementById("someDiv"));
The above code would return an instance of the Sys.UI.DataView
class.
Case 2: Factory methods using paramName
and paramValue
The paramName
and paramValue
attributes target the factory method scenario where the datatype of the return value is dependent on a parameter whose possible values consist of an enumeration. If paramName
and paramValue
are provided, then the method returns an instance object for the class identified by the datatype
attribute specified on the <returnType>
element whose paramName
exactly matches the name
attribute of one of the <parameters>
elements and whose paramValue
attribute exactly matches the value of that parameter. For this scenario, typically the <method> element will have multiple <returnType>
sub-elements.
To illustrate, suppose you have the following method definition:
<method name="create"> <parameter name="classToInstantiate" datatype="String"> <options> <option value="beta.database"/> <option value="beta.desktop"/> <option value="beta.geolocation"/> <option value="beta.httprequest"/> <option value="beta.localserver" /> <option value="beta.timer" /> <option value="beta.workerpool"/> </options> </parameter> <returnType paramName="classToInstantiate" paramValue="beta.database" datatype="Database"/> <returnType paramName="classToInstantiate" paramValue="beta.desktop" datatype="Desktop"/> <returnType paramName="classToInstantiate" paramValue="beta.geolocation" datatype="Geolocation"/> <returnType paramName="classToInstantiate" paramValue="beta.httprequest" datatype="HttpRequest "/> <returnType paramName="classToInstantiate" paramValue="beta.localserver" datatype="LocalServer"/> <returnType paramName="classToInstantiate" paramValue="beta.timer" datatype="Timer"/> <returnType paramName="classToInstantiate" paramValue="beta.workerpool" datatype="WorkerPool"/> </method>
and furthermore suppose at runtime this method can be invoked by any of the following:
[1] var db = google.gears.factory.create('beta.database'); [2] var desktop = google.gears.factory.create('beta.desktop'); [3] var geo = google.gears.factory.create('beta.geolocation'); [4] var request = google.gears.factory.create('beta.httprequest'); [5] var localServer = google.gears.factory.create('beta.localserver'); [6] var timer = google.gears.factory.create('beta.timer'); [7] var wp = google.gears.factory.create('beta.workerpool');
If create()
is invoked using [1] (i.e., when 'beta.database' is passed as the parameter), then the class factory returns an instance object from class Database, whereas using [7] (i.e., when 'beta.workerpool' is passed as the parameter), then the class factory returns an instance object from class WorkerPool.
Note that paramName
and paramValue
do not require the use of an enumeration (i.e., <options>
and <option>
elements). These attributes can also be used on parameters whose datatype
is String that do not specify a discrete list of available options.
The metadata file is incorrectly formulated (i.e., in error) in the following situations: (a) if only one of paramName
or paramValue
is specified; (b) when paramName
does not match one of the method's parameters; and (c) when a discrete enumeration is specified and paramValue
does not match one of the enumerated values for the parameter.
Developer tools MUST first look to see if the specified datatype
matches one of the parameter names, and then determine if the specified datatype
matches other possible values (e.g., one of the ECMAScript core datatypes or the name of a JavaScript class).
<singleton>
The <singleton>
element describes a JavaScript object that functions like a <class>
in that it might include its own APIs, such as method and properties, but unlike <class>
, does not include the ability to construct new instances of itself.
Schema
singleton_element = element singleton { singleton_content & singleton_attributes & foreign_nodes } singleton_content = ( descriptive_elements & compatibility_elements & alias_element* & aliases_element* & ancestor_element* & ancestors_element* & config_element* & configs_element* & event_element* & events_element* & mix_element* & mixes_element* & method_element* & methods_element* & property_element* & properties_element* ) singleton_attributes = ( name & visibility? & pattern_attributes & registerCallbackPattern? & unregisterCallbackPattern? )
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>
- <alias>, <aliases>
- <ancestor>, <ancestors>
- <config>, <configs>
- <event>, <events>
- <mix>, <mixes>
- <method>, <methods>
- <property>, <properties>
Attribute summary
Attribute | Description | Type | Required | Default |
---|---|---|---|---|
name | Absolute object name for the singleton. | String | yes | none |
pattern_attributes | Attributes 'getterPattern' and 'setterPattern'. Defined in Pattern attributes section in Properties chapter. | |||
registerCallbackPattern | Specifies the name pattern for the event handler registration function. Defined in Properties chapter. | |||
unregisterCallbackPattern | Specifies the name pattern for the event handler unregistration function. Defined in Properties chapter. | |||
visibility | Intended visibility of this feature to other parts of the JavaScript application. Defined in Common attributes section. |
Attribute details
'name' attribute
The name
attribute specifies the absolute object name for the singleton. The name MUST be globally unique within the context of a particular JavaScript library.