The following table summarizes the attributes:

Here is an example:

<event name="locationChange">
  <handlerFunction registerCallbackPattern="{{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 that takes a single parameter, which is the callback function. The event handler function will be passed two parameters, both of which are Number values.

<interface>

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?  
)

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.

As shown in the Compact RelaxNG schema snippet above, the <interface> element can contain various child elements. Descriptions of these child elements can be found elsewhere within this specification.

The name attribute specifies the absolute object name using JavaScript dot notation for the class, 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 (i.e., has an appropriate constructor function).

The visibility attribute specifies the intended visibility of this interface to other parts of the JavaScript application. Its value can be any of the following access modifiers: public|private|protected|internal|protected-internal. For descriptions of these access modifiers, refer to the description of the visibility attribute for the <class> element.

The getterPattern and setterPattern attributes specify the name or name pattern for property getter and setter functions. Both attributes are inheritable in that all descendant <property> elements that do not specify the attribute will inherit these attributes. For more about these attributes, see the write-up on "Pattern attributes".

<method>

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?
)

The <method> element describes a JavaScript function that is not used as a constructor.

As shown in the Compact RelaxNG schema snippet above, the <method> element can contain various child elements. Descriptions of these child elements can be found elsewhere within this specification.

The name attribute specifies JavaScript name for this function.

The scope attribute can have values instance or static. A value of instance indicates that this class method is available only after an instance of this class has been created. A value of static indicates that this class method belongs to the class itself (i.e., does not require object instantiation).

The visibility attribute specifies the intended visibility of this method to other parts of the JavaScript application. Its value can be any of the following access modifiers: public|private|protected|internal|protected-internal. For descriptions of these access modifiers, refer to the description of the visibility attribute for the <class> element.

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>

mix_element = element mix {
  mix_content  &  mix_attributes  &  foreign_nodes
}
mix_content = (
  descriptive_elements
)
mix_attributes = (
  datatype  &  fromProperty?  &  toProperty?  &  fromScope?  &  toScope?
)

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>s, <method>s, <event>s, <alias>es, <ancestor>s, <config>s, <constructor>s, <event>s and <mix>es 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.

As shown in the Compact RelaxNG schema snippet above, the <mix> element can contain various child elements. Descriptions of these child elements can be found elsewhere within this specification.

The datatype attribute is a reference to the 'datatype' on the <mixin>, <interface> or <class> element whose features should be mixed in.

The fromScope attribute applies to properties and methods and can have values instance or static. If fromScope="instance", then all instance properties and methods are mixed in. If fromScope="static", then all static properties and methods are mixed in. (See the description of the scope attribute.)

The toScope attribute applies to properties and methods and can have values instance or static. If toScope="instance", then all properties and methods are mixed on an instance basis. If toScope="static", then all properties and methods are mixed on an static basis. (See the description of the scope 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> or <class> element.

The toProperty attribute provides the name for the mixed-in property when placed on this <mixin>, <interface> or <class>. If not specified or if it is the empty string, then the mixed-in property's name has the same name as the fromProperty.

<mixin>

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?    
)

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).

As shown in the Compact RelaxNG schema snippet above, the <mixin> element can contain various child elements. Descriptions of these child elements can be found elsewhere within this specification.

The name attribute specifies the absolute object name using JavaScript dot notation for the mixin, such as "FooToolkit.io.http" (where the Foo toolkit has a main global object called "FooToolkit", a subobject "io", with subobject "http" which is set up as a JavaScript mixin.

The scope attribute can have values instance or static. A value of instance indicates that this class method is available only after an instance of this class has been created. A value of static indicates that this class method belongs to the class itself (i.e., does not require object instantiation).

The visibility attribute specifies the intended visibility of this mixin to other parts of the JavaScript application. Its value can be any of the following access modifiers: public|private|protected|internal|protected-internal. For descriptions of these access modifiers, refer to the description of the visibility attribute for the <class> element.

<namespace>

namespace_element = element namespace {
  namespace_content  &  namespace_attributes  &  foreign_nodes
}
namespace_content = (
  descriptive_elements
)
namespace_attributes = (
  name  &  visibility?
)

The <namespace> element can be used to describes 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. One way to use the <namespace> element is to provide descriptive information (e.g., using the <description> element) about the base object.

As shown in the Compact RelaxNG schema snippet above, the <namespace> element can contain various child elements. Descriptions of these child elements can be found elsewhere within this specification.

The name attribute specifies the absolute object name using JavaScript dot notation for the class, 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 (i.e., has an appropriate constructor function).

The visibility attribute specifies the intended visibility of this namespace to other parts of the JavaScript application. Its value can be any of the following access modifiers: public|private|protected|internal|protected-internal. For descriptions of these access modifiers, refer to the description of the visibility attribute for the <class> element.

<parameter>

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
)

2009-02-10: Need to add discussion about nested property elements

2009-02-24: Make sure the spec is clear that child <parameter> and <returnType> elements only apply when datatype="Function" and that child <property> elements only apply when datatype="Object".

2009-04-09: Make sure the spec is clear that this is a feature mostly for the IDE case in that it provides a poor-man's JSON schema feature. It isn't possible to express everything in JSON schema, such as unions.

The <parameter> element describes a parameter to a JavaScript function.

As shown in the Compact RelaxNG schema snippet above, the <parameter> element can contain various child elements. Descriptions of these child elements can be found elsewhere within this specification.

The name attribute specifies the name of the corresponding parameter within the JavaScript function definition. For example, consider the following JavaScript function:

MyClass.Init = function(parm1, parm2) { ... }

The corresponding OpenAjax Metadata for this function might look like this:

<class name="MyClass">
  <method name="Init">
    <parameter name="parm1" .../>
    <parameter name="parm2" .../>
  </method>
</class>

The datatype attribute specifies the allowed datatype(s) for the parameter. See the Datatypes chapterfor the detailed definition of this 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>

  <description>
  The key aspect of this function is the object of style properties that will be animated, 
  and to what end. Each key within the object represents a style property that will also be animated 
  (e.g. "height", "top", or "opacity").

  Note that properties should be specified using camel case, e.g. "marginLeft" instead of "margin-left."

  The value associated with the key represents to what end the property will be animated. If a number is 
  provided as the value, then the style property will be transitioned from its current state to that new 
  number. Otherwise if the string "hide", "show", or "toggle" is provided, a default animation will be 
  constructed for that property. 
  </description>

  <parameters>

    <parameter name="params" datatype="Options" 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="Callback" defaultValue="">
          <description/>
        </property>
        <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="Options " 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="Callback" 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"/>

  <!-- examples here ->
</method>

2009-02-17 At today's telecon, we agreed there were some issues in the example above. Lori will investigate and see if there is a different and better example. One of the issues is datatype="Callback". Also, Jon needs to investigate what's going on with datatype="Options".

<returnType>

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
)

2009-02-24: Make sure the spec is clear that child <parameter> elements only apply when datatype="Function" and that child <property> elements only apply when datatype="Object".

The <returnType> element specifies the datatype of the value that the method returns and supplemental descriptive information about the return value.

As shown in the Compact RelaxNG schema snippet above, the <returnType> element can contain various child elements. Descriptions of these child elements can be found elsewhere within this specification.

The datatype attribute specifies the datatype for the value that the method returns. The detailed specification for the datatype attribute can be found in the Datatypes chapter of this specification. However, for the <returns> element, the datatype attribute includes one additional feature that targets factory methods, where the datatype attribute can reference one of the method's parameters. In this case, the string value of the datatype attribute must exactly match the string value of the name attribute on one of the <parameter> elements for this method. If such a match exists between the <returns> element's datatype and the <parameter> element's name, then the return value from the method is the value of that parameter, which can be either a String value (the name of the class) or a Function value (the class constructor). To illustrate, suppose you have the following method definition:

<method name="classFactory">
  <parameter name="classToInstantiate" datatype="String"/>
  <returns datatype="classToInstantiate"/>
</method>

The method definition indicates that the return value from the method is an object whose classname is passed as a String to the classFactory method. Now, let's furthermore suppose this method might be invoked at runtime by any of the following:

• myShape = classFactory('acme.graphtools.circleClass')
• myShape = classFactory('acme.graphtools.rectClass')

In this hypothetical case, the method will return an object that is either an instance of acme.graphtools.circleClass or acme.graphtools.rectClass.

Here is the same example, except that a Function value is used to identify the class:

<method name="classFactory">
  <parameter name="classToInstantiate" datatype="Function"/>
  <returns datatype="classToInstantiate"/>
</method>

For this example, the factory method might be invoked as follows (note that the arguments are not quoted, whereas in the previous String example, the class names were in quotes):

• myShape = classFactory(acme.graphtools.circleClass)
• myShape = classFactory(acme.graphtools.rectClass)

User agents must first look to see if the specified datatype matches one of the parameter names, and then determine if the specified datatype matches one of the ECMAScript core datatypes or the name of a JavaScript class.

The paramName and paramValue attributes are most useful for factory methods where the datatype of the return value is dependent on a parameter whose possible values consists of an enumeration. If paramName and paramValue are provided, then they indicate that when the <parameter> element whose name attribute exactly matches the value of the paramName attribute and where the value of the parameter exactly matches the paramValue attribute, then the method returns the datatype specified on this <returns> element. To illustrate, suppose you have the following method definition:

<method name="classFactory">
  <parameter name="classToInstantiate" datatype="String">
    <options>
      <option value="rect"/>
      <option value="circle"/>
    </options>
  </parameter>
  <returns paramName="classToInstantiate" paramValue="rect" datatype="acme.graphtools.rectClass"/>
  <returns paramName="classToInstantiate" paramValue="circle" datatype="acme.graphtools.circleClass"/>
</method>

and furthermore suppose at runtime this method can be invoked by either myShape = classFactory('rect'); or myShape = classFactory('circle');. The above method definition indicates that: (a) when 'rect' is passed as the parameter then the return datatype is 'acme.graphtools.rectClass', and (b) when 'circle' is passed as the parameter then the return datatype is 'acme.graphtools.circleClass'.

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) for the following situations: (a) if only one of paramName and paramValue are 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 possible values for the parameter.

Note that attribute datatype is a required attribute in OpenAjax Metadata, whereas in some inline commenting systems such as JSDoc, the datatype might be optional. When converting from these inline commenting systems into OpenAjax Metadata, if the datatype is not specified, a suggested approach is to set datatype to Object.

<singleton>

20081216: There are some details to work out on this element.

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?    
)

The <singleton> element describes a global static 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.

As shown in the Compact RelaxNG schema snippet above, the <singleton> element can contain various child elements. Descriptions of these child elements can be found elsewhere within this specification.

The name attribute specifies the absolute object name using JavaScript dot notation for the singleton, 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 singleton (i.e., has an appropriate constructor function).

The visibility attribute specifies the intended visibility of this singleton to other parts of the JavaScript application. Its value can be any of the following access modifiers: public|private|protected|internal|protected-internal. For descriptions of these access modifiers, refer to the description of the visibility attribute for the <class> element.

The getterPattern and setterPattern attributes specify the name or name pattern for property getter and setter functions. Both attributes are inheritable in that all descendant <property> elements that do not specify the attribute will inherit these attributes. For more about these attributes, see the write-up on "Pattern attributes".

EDITOR: Make sure that all 'datatype' attributes refer to datatypes chapter and make sure there is appropriate writeup on classname datatypes to talk about the use of JavaScript dot notation to identify classes.