IDE API Metadata Strawman Proposal DojoDatePicker

From MemberWiki

Dojo DatePicker

As extracted from the Dojo DatePicker documentation

<?xml version="1.0" encoding="UTF-8"?>
<api xmlns="http://ns.openajax.org/api" version="..." apiType="javascript">
   <class type="dojo.widget.DatePicker" superclass="dojo.widget.HtmlWidget">
       <constructors>
           <constructor scope="instance">
               <description></description>
               <parameters/>
               <return-types/>
           </constructor>
       </constructors>
       <properties>
           <property name="value" readonly="true" scope="instance" type="Date"/>
           <property name="startDate" access="read-write" scope="instance" type="Date"/>
           <property name="endDate" access="read-write" scope="instance" type="Date"/>
           <property name="weekStartsOn" access="read-write" scope="instance" type="Number"/>
           <property name="today" readonly="true" scope="instance" type="Date">
               <description>Today's date.</description>
           </property>
           <property name="selectedNode" readonly="true" scope="instance" type="HtmlElement"/>
           <property name="clickedNode" readonly="true" scope="instance" type="HtmlElement"/>
       </properties>
       <methods>
           <method name="destroy" scope="instance">
               <description>Destructor method.</description>
               <parameters/>
               <return-types/>
           </method>
           <method name="fillInTemplate" scope="instance">
               <description></description>
               <parameters>
                   <parameter name="args" required="true"/>
                   <parameter name="frag" required="true"/>
               </parameters>
               <return-types/>
           </method>
           <method name="getDate" scope="instance">
               <description>return current date as a Date object</description>
               <parameters/>
               <return-types>
                   <return-type type="Date"/>
               </return-types>
           </method>
           <method name="getValue" scope="instance">
               <description>return current date in RFC 3339 format</description>
               <parameters/>
               <return-types>
                   <return-type type="String"/>
               </return-types>
           </method>
           <method name="isDisabledDate" scope="instance">
               <description>May be overridden to disable certain dates in the calendar e.g. isDisabledDate=dojo.date.isWeekend</description>
               <parameters>
                   <parameter name="dateObj" required="true" type="Date"/>
                   <parameter name="locale" type="String"/>
               </parameters>
               <return-types>
                   <return-type type="Boolean"/>
               </return-types>
           </method>
           <method name="onClick" scope="instance">
               <description>The click event handler</description>
               <parameters>
                   <parameter name="evt" required="true" type="Object"/>
               </parameters>
               <return-types/>
           </method>
           <method name="onIncrementMonth" scope="instance">
               <description>handler for increment month event</description>
               <parameters>
                   <parameter name="evt" required="true" type="Object"/>
               </parameters>
               <return-types/>
           </method>
           <method name="onIncrementWeek" scope="instance">
               <description>handler for increment week event</description>
               <parameters>
                   <parameter name="evt" required="true" type="Object"/>
               </parameters>
               <return-types/>
           </method>
           <method name="onIncrementYear" scope="instance">
               <description>handler for increment year event</description>
               <parameters>
                   <parameter name="evt" required="true" type="Object"/>
               </parameters>
               <return-types/>
           </method>
           <method name="onValueChanged" scope="instance">
               <description>the set date event handler</description>
               <parameters>
                   <parameter name="date" required="true" type="Date"/>
               </parameters>
               <return-types/>
           </method>
           <method name="postMixInProperties" scope="instance">
               <description>see dojo.widget.DomWidget</description>
               <parameters/>
               <return-types/>
           </method>
           <method name="setDate" scope="instance">
               <description>set the current date and update the UI</description>
               <parameters>
                   <parameter name="dateObj" required="true" type="['Date','String']"/>
               </parameters>
               <return-types/>
           </method>
           <method name="setValue" scope="instance">
               <description>set the current date from RFC 3339 formatted string or a date object, synonymous with setDate</description>
               <parameters>
                   <parameter name="rfcDate" required="true" type="['Date','String']"/>
               </parameters>
               <return-types/>
           </method>
       </methods>
   </class>
</javascript>

• Why "return type_s_"? JON (20080102): Raised as IDE Issue 10: returnType or returnTypes
• Why aren't localizable text descriptions in a separate file? JON (20080102): See [[IDE Issue 3] | IDE Issue 3: Widget metadata localization]
• What is "Event" (mentioned as a parameter type in the Dojo docs)? JON (20080102): For Event, is Object sufficient, or do we need a special valueType for DOM events? Raised as IDE Issue 12: Special valueType for DOM Events
• How do we handle methods that can take two types (see setDate which takes a String or a Date)? JON (20080102): Informed by our discussion (/member/wiki/IDE_Minutes_2007-12-20), I have proposed array literal syntax, such as type="['Date','String']".
• Not sure about the properties, which are not clearly documented.
• What is the type for Dom elements? JON (20080102): Is String sufficient, or do we need a special valueType for a fragment of markup and/or for a snippet of HTML "rich text"? Raised as IDE Issue 13: Special valueType for markup fragments and/or rich text