IDE API Metadata Strawman Proposal
From MemberWiki
Contents |
Overview
This strawman proposes that we use the Aptana's XML file as the starting point, with a small number of immediate changes per some of our more obvious requirements.
Example
Here is an example:
<?xml version="1.0" encoding="UTF-8"?> <api xmlns="http://ns.openajax.org/api" version="..." apiType="javascript"> <class type="libraryname.ClassName" superclass="Object"> <constructors> <constructor scope="instance"> <description>Constructor description</description> <parameters> <parameter name="message" usage="required" jsType="string"> <description>Parameter description</description> </parameter> </parameters> <return-types> <return-type type="libraryname.ClassName"/> </return-types> </constructor> </constructors> <properties> <property name="propertyInstance" access="read-write" scope="instance" jsType="string"> <description>Property description</description> </property> <property name="propertyStatic" access="read-write" scope="static" jsType="string"> <description>Property description</description> </property> </properties> <methods> <method name="functionInstance" scope="instance"> <description>Method description</description> <parameters> <parameter name="param" usage="required" jsType="string"> <description>Parameter description</description> </parameter> </parameters> <return-types> <return-type type="String"/> </return-types> </method> <method name="functionStatic" scope="static"> <description>Method description</description> <parameters/> <return-types> <return-type jsType="string"/> </return-types> </method> </methods> </class> </javascript>
The Dojo DatePicker API expressed in this format
Replace Aptana's <property> element with an <api apiType="javascript"> element
This is an attempt to address Microsoft's requirement that we put in extensibility hooks to accommodate multi-language scenarios.
Minor changes to Aptana's <property> element
This strawman proposes that we start with the Aptana <property> element from Aptana's XML format and make the following small set of changes:
- Aptana has a 'type' attribute that holds the JavaScript type. Some systems will want additional typing information, such as whether the value must be a positive integer or a currency amount. Therefore, I am proposing two attributes having to do with data typing, a 'jsType' attribute which holds the JavaScript type and an 'xsdType' which holds the XML Schema Datatype per that specification. Note that XML Schema is extensible and allows for custom datatypes.
- I have added some additional attributes as needed by widgets.
- I have taken a stab at databinding. There is a 'bindable' attribute that can take the values '1way', '2way', and 'no' and a 'bindObject' that is either a JavaScript object or a string that is the name of a JavaScript object.
- I'm not sure about how 'visibility' works in Aptana, but I have proposed it as a hint to IDEs about whether the property should be presented to the user.
Here is an example:
<widget ... > ... <properties> <property name="clockType" jsType="" xsdType="" defaultValue="" required="boolean" access="readonly" scope="" visibility="string" bindable="" bindObject="" > <description>...</description> </property> </properties> ... </widget>
where:
- name is the internal name for the field
- description is the display text
- jsType is the JavaScript type
- xsdType allows for more detailed datatyping via XML Schema Datatypes [1], such as string, boolean, decimal, float, dateTime, anyURI or QName, or custom datatypes using the more advanced features.
- defaultValue is self-explanatory
- required is a boolean that indicates whether a value must be provided to the widget constructor
- access is either 'readonly' or 'read-write'
- scope is either 'static' or 'instance'
- visibility is a hint that indicates whether the given property should appear in an inspector dialog. This is designed as an enumeration for future growth, but 'yes' and 'no' will be the only two values initially.
- bindable: see earlier description
- bindObject: see earlier description