Skip to Content | Skip to Navigation


Inlining API

This document contains information on how to inline API documentation into the reference-guide.

Introduction

The Dojo API Documentation supports the ability to make remote procedure calls in order to retrieve a JSON representation of the API. rstWiki, the tool that generates the reference-guide supports the ability to inline this documentation into the page using special directives.

The format of the directives is as the following:

.. api-doc :: package/module
  :level: 2
  :table:
  :topfunc:
  :methods: foo bar
  :properties: baz qux
  :events: onCorge onGrault
  :no-headers:
  :no-inherited:
  :extensions:
  :privates:
  :summary:
  :description:
  :returns:
  :sig:

Where the .. api-doc :: is followed by the MID to be inlined (e.g. dojo/query or dijit/form/Button). The following other options are available:

Option Description
:level: The header level that the at which the labels will be output at. Defaults to 2.
:table: Information should be presented in a table format, with summary information provided. If this is specified, :level, :description: and :sig: will be ignored.
:topfunc: If specified, and the module returns a function, it will output the information for that root function.
:methods: Output the methods for the specified module. If this is followed by a space deliminated list, then only those methods will be output in the order supplied. If there are none specified, all methods will be output, based on the :privates: argument.
:properties: Output the properties for the specified module. If this is followed by a space deliminated list, then only those properties will be output in the order supplied. If there are none specified, all properties will be output, based on the :privates: argument.
:events: Output the events for the specified module. If this is followed by a space deliminated list, then only those events will be output in the order supplied. If there are none specified, all events will be output, based on the :privates: argument.
:no-headers: If not using tables, do not output a header for each method, property or event.
:no-inherited: If outputting methods, properties or events, do not include those that are inherited.
:no-base: If outputting methods, properties or events, do not include those that are declared within the class itself.
:extensions: If outputting methods, properties or events, include those that
:privates: If outputting methods, properties or events, include those that are marked as private.
:summary: Output the summary for each method, property or event.
:description: Output the description for each method, property or event.
:returns: For methods, include information about the return value of the method.
:sig: For methods, include a table of arguments that form the signature of the method.

The above directive is designed to potentially be used, with a different configuration, in different places in the document, especially since the directive will not output any headers between methods, properties or events.

The following provides some "live" examples:

dojo/on Root Function

A function that provides core event listening functionality. With this function you can provide a target, event type, and listener to be notified of future matching events that are fired.

NameTypeDescription
targetElement|Object

This is the target object or DOM element that to receive events from

typeString|Function

This is the name of the event to listen for or an extension event type.

listenerFunction

This is the function that should be called when the event fires.

dontFixundefined

dojo/on() returns Object or undefined.

dojo/Stateful Methods

MethodReturnsDescription
get(name)any|undefined

Get a property on a Stateful instance.

set(name,value)any|function

Set a property on a Stateful instance

watch(name,callback)any|object

Watches a property for changes

dijit/_WidgetBase Properties

PropertyTypeDescription
_attrPairNamesobject
_blankGifString

Path to a blank 1x1 image. Used by <img> nodes in templates that really get their image via CSS background-image.

_setClassAttrobject
_setDirAttrundefined
_setIdAttrstring
_setLangAttrundefined
_startedBoolean

startup() has completed.

attributeMapObject

Deprecated. Instead of attributeMap, widget should have a _setXXXAttr attribute for each XXX attribute to be mapped to the DOM.

attributeMap sets up a "binding" between attributes (aka properties) of the widget and the widget's DOM. Changes to widget attributes listed in attributeMap will be reflected into the DOM.

For example, calling set('title', 'hello') on a TitlePane will automatically cause the TitlePane's DOM to update with the new title.

attributeMap is a hash where the key is an attribute of the widget, and the value reflects a binding to a:

  • DOM node attribute

    focus: {node: "focusNode", type: "attribute"} Maps this.focus to this.focusNode.focus

  • DOM node innerHTML

    title: { node: "titleNode", type: "innerHTML" } Maps this.title to this.titleNode.innerHTML

  • DOM node innerText

    title: { node: "titleNode", type: "innerText" } Maps this.title to this.titleNode.innerText

  • DOM node CSS class

    myClass: { node: "domNode", type: "class" } Maps this.myClass to this.domNode.className

If the value is an array, then each element in the array matches one of the formats of the above list.

There are also some shorthands for backwards compatibility:

  • string --> { node: string, type: "attribute" }, for example:
"focusNode" ---> { node: "focusNode", type: "attribute" }
  • "" --> { node: "domNode", type: "attribute" }
baseClassString

Root CSS class of the widget (ex: dijitTextBox), used to construct CSS classes to indicate widget state.

classstring
containerNodeDomNode

Designates where children of the source DOM node will be placed. "Children" in this case refers to both DOM nodes and widgets. For example, for myWidget:

<div data-dojo-type=myWidget>
    <b> here's a plain DOM node
    <span data-dojo-type=subWidget>and a widget</span>
    <i> and another plain DOM node </i>
</div>

containerNode would point to:

<b> here's a plain DOM node
<span data-dojo-type=subWidget>and a widget</span>
<i> and another plain DOM node </i>

In templated widgets, "containerNode" is set via a data-dojo-attach-point assignment.

containerNode must be defined for any widget that accepts innerHTML (like ContentPane or BorderContainer or even Button), and conversely is null for widgets that don't, like TextBox.

dirString

Bi-directional support, as defined by the HTML DIR attribute. Either left-to-right "ltr" or right-to-left "rtl". If undefined, widgets renders in page's default direction.

domNodeDomNode

This is our visible representation of the widget! Other DOM Nodes may by assigned to other properties, usually through the template system's data-dojo-attach-point syntax, but the domNode property is the canonical "top level" node in widget UI.

idString

A unique, opaque ID string that can be assigned by users or by the system. If the developer passes an ID which is known not to be unique, the specified ID is ignored and the system-generated ID is used instead.

langString

Rarely used. Overrides the default Dojo locale used to render this widget, as defined by the HTML LANG attribute. Value must be among the list of locales specified during by the Dojo bootstrap, formatted according to RFC 3066 (like en-us).

ownerDocumentDocument

The document this widget belongs to. If not specified to constructor, will default to srcNodeRef.ownerDocument, or if no sourceRef specified, then to dojo/_base/window::doc

srcNodeRefDomNode

pointer to original DOM node

styleString||Object

HTML style attributes as cssText string or name/value hash

textDirString

Bi-directional support, the main variable which is responsible for the direction of the text. The text direction can be different than the GUI direction by using this parameter in creation of a widget.

Allowed values:

  1. "ltr"
  2. "rtl"
  3. "auto" - contextual the direction of a text defined by first strong letter.

By default is as the page direction.

titleString

HTML title attribute.

For form widgets this specifies a tooltip to display when hovering over the widget (just like the native HTML title attribute).

For TitlePane or for when this widget is a child of a TabContainer, AccordionContainer, etc., it's used to specify the tab label, accordion pane title, etc.

tooltipString

When this widget's title attribute is used to for a tab label, accordion pane title, etc., this specifies the tooltip to appear when the mouse is hovered over that text.

dijit/form/Button Events

onBlur

Called when the widget stops being "active" because focus moved to something outside of it, or the user clicked somewhere outside of it, or the widget was hidden.

onChange

Callback when this widget's value is changed.

onClick

Connect to this function to receive notifications of mouse click events.

onClose

Called when this widget is being displayed as a popup (ex: a Calendar popped up from a DateTextBox), and it is hidden. This is called from the dijit.popup code, and should not be called directly.

Also used as a parameter for children of dijit.layout.StackContainer or subclasses. Callback if a user tries to close the child. Child will be closed if this function returns true.

onDblClick

Connect to this function to receive notifications of mouse double click events.

onFocus

Called when the widget becomes "active" because it or a widget inside of it either has focus, or has recently been clicked.

onHide

Called when another widget becomes the selected pane in a dijit.layout.TabContainer, dijit.layout.StackContainer, dijit.layout.AccordionContainer, etc.

Also called to indicate hide of a dijit.Dialog, dijit.TooltipDialog, or dijit.TitlePane.

onKeyDown

Connect to this function to receive notifications of keys being pressed down.

onKeyPress

Connect to this function to receive notifications of printable keys being typed.

onKeyUp

Connect to this function to receive notifications of keys being released.

onMouseDown

Connect to this function to receive notifications of when the mouse button is pressed down.

onMouseEnter

Connect to this function to receive notifications of when the mouse moves onto this widget.

onMouseLeave

Connect to this function to receive notifications of when the mouse moves off of this widget.

onMouseMove

Connect to this function to receive notifications of when the mouse moves over nodes contained within this widget.

onMouseOut

Connect to this function to receive notifications of when the mouse moves off of nodes contained within this widget.

onMouseOver

Connect to this function to receive notifications of when the mouse moves onto nodes contained within this widget.

onMouseUp

Connect to this function to receive notifications of when the mouse button is released.

onShow

Called when this widget becomes the selected pane in a dijit.layout.TabContainer, dijit.layout.StackContainer, dijit.layout.AccordionContainer, etc.

Also called to indicate display of a dijit.Dialog, dijit.TooltipDialog, or dijit.TitlePane.