dojo/parser (version 1.10)

Summary

The Dom/Widget parsing package

See the dojo/parser reference documentation for more information.

Property Summary

Method Summary

  • _clearCache() Clear cached data.
  • _functionFromScript(script,attrData) Convert a <script type="dojo/method" args="a, b, c"> ... </script> into a function
  • _instantiate(nodes,mixin,options,returnPromise) Takes array of objects representing nodes, and turns them into class instances and potentially calls a startup method to allow them to connect with any children.
  • _require(script,options) Helper for _scanAMD().
  • _scanAmd(root,options) Scans the DOM for any declarative requires and returns their values.
  • construct(ctor,node,mixin,options,scripts,inherited) Calls new ctor(params, node), where params is the hash of parameters specified on the node, excluding data-dojo-type and data-dojo-mixins.
  • instantiate(nodes,mixin,options) Takes array of nodes, and turns them into class instances and potentially calls a startup method to allow them to connect with any children.
  • parse(rootNode,options) Scan the DOM for class instances, and instantiate them.
  • scan(root,options) Scan a DOM tree and return an array of objects representing the DOMNodes that need to be turned into widgets.

Properties

_attrName
Defined by: dojox/dtl/_Templated
_query
Defined by: dojox/dtl/_Templated

Methods

_clearCache()
Defined by dojo/parser

Clear cached data. Used mainly for benchmarking.

_functionFromScript(script,attrData)
Defined by dojo/parser

Convert a <script type="dojo/method" args="a, b, c"> ... </script> into a function

Parameter Type Description
script DOMNode

The <script> DOMNode
attrData String

For HTML5 compliance, searches for attrData + "args" (typically "data-dojo-args") instead of "args"
Returns:instance
_instantiate(nodes,mixin,options,returnPromise)
Defined by dojo/parser

Takes array of objects representing nodes, and turns them into class instances and potentially calls a startup method to allow them to connect with any children.

Parameter Type Description
nodes Array

Array of objects like 

{
    ctor: Function (may be null)
    types: ["dijit/form/Button", "acme/MyMixin"] (used if ctor not specified)
    node: DOMNode,
    scripts: [ ... ],   // array of <script type="dojo/..."> children of node
    inherited: { ... }  // settings inherited from ancestors like dir, theme, etc.
}
mixin Object

An object that will be mixed in with each node in the array. Values in the mixin will override values in the node, if they exist.
options Object

An options object used to hold kwArgs for instantiation. See parse.options argument for details.
returnPromise Boolean

Return a Promise rather than the instance; supports asynchronous widget creation.
Returns:any | undefined

Array of instances, or if returnPromise is true, a promise for array of instances that resolves when instances have finished initializing.

_require(script,options)
Defined by dojo/parser

Helper for _scanAMD(). Takes a <script type=dojo/require>bar: "acme/bar", ...</script> node, calls require() to load the specified modules and (asynchronously) assign them to the specified global variables, and returns a Promise for when that operation completes.

In the example above, it is effectively doing a require(["acme/bar", ...], function(a){ bar = a; }).

Parameter Type Description
script DOMNode
options Object
Optional
Returns:undefined
_scanAmd(root,options)
Defined by dojo/parser

Scans the DOM for any declarative requires and returns their values.

Looks for <script type=dojo/require>bar: "acme/bar", ...</script> node, calls require() to load the specified modules and (asynchronously) assign them to the specified global variables, and returns a Promise for when those operations complete.

Parameter Type Description
root DomNode

The node to base the scan from.
options Object
Optional

a kwArgs options object, see parse() for details
Returns:undefined
construct(ctor,node,mixin,options,scripts,inherited)
Defined by dojo/parser

Calls new ctor(params, node), where params is the hash of parameters specified on the node, excluding data-dojo-type and data-dojo-mixins. Does not call startup().

Parameter Type Description
ctor Function

Widget constructor.
node DOMNode

This node will be replaced/attached to by the widget. It also specifies the arguments to pass to ctor.
mixin Object
Optional

Attributes in this object will be passed as parameters to ctor, overriding attributes specified on the node.
options Object
Optional

An options object used to hold kwArgs for instantiation. See parse.options argument for details.
scripts DomNode[]
Optional

Array of <script type="dojo/*"> DOMNodes. If not specified, will search for <script> tags inside node.
inherited Object
Optional

Settings from dir=rtl or lang=... on a node above this node. Overrides options.inherited.
Returns:any | undefined

Instance or Promise for the instance, if markupFactory() itself returned a promise

instantiate(nodes,mixin,options)
Defined by dojo/parser

Takes array of nodes, and turns them into class instances and potentially calls a startup method to allow them to connect with any children.

Parameter Type Description
nodes Array

Array of DOM nodes
mixin Object
Optional

An object that will be mixed in with each node in the array. Values in the mixin will override values in the node, if they exist.
options Object
Optional

An object used to hold kwArgs for instantiation. See parse.options argument for details.
Returns:any | undefined

Array of instances.

parse(rootNode,options)
Defined by dojo/parser

Scan the DOM for class instances, and instantiate them.

Search specified node (or root node) recursively for class instances, and instantiate them. Searches for either data-dojo-type="Class" or dojoType="Class" where "Class" is a a fully qualified class name, like dijit/form/Button

Using data-dojo-type: Attributes using can be mixed into the parameters used to instantiate the Class by using a data-dojo-props attribute on the node being converted. data-dojo-props should be a string attribute to be converted from JSON.

Using dojoType: Attributes are read from the original domNode and converted to appropriate types by looking up the Class prototype values. This is the default behavior from Dojo 1.0 to Dojo 1.5. dojoType support is deprecated, and will go away in Dojo 2.0.

Parameter Type Description
rootNode DomNode
Optional

A default starting root node from which to start the parsing. Can be omitted, defaulting to the entire document. If omitted, the options object can be passed in this place. If the options object has a rootNode member, that is used.
options Object
Optional

A hash of options.

  • noStart: Boolean?: when set will prevent the parser from calling .startup() when locating the nodes.
  • rootNode: DomNode?: identical to the function's rootNode argument, though allowed to be passed in via this `options object.
  • template: Boolean: If true, ignores ContentPane's stopParser flag and parses contents inside of a ContentPane inside of a template. This allows dojoAttachPoint on widgets/nodes nested inside the ContentPane to work.
  • inherited: Object: Hash possibly containing dir and lang settings to be applied to parsed widgets, unless there's another setting on a sub-node that overrides
  • scope: String: Root for attribute names to search for. If scopeName is dojo, will search for data-dojo-type (or dojoType). For backwards compatibility reasons defaults to dojo._scopeName (which is "dojo" except when multi-version support is used, when it will be something like dojo16, dojo20, etc.)
  • propsThis: Object: If specified, "this" referenced from data-dojo-props will refer to propsThis. Intended for use from the widgets-in-template feature of dijit._WidgetsInTemplateMixin
  • contextRequire: Function: If specified, this require is utilised for looking resolving modules instead of the dojo/parser context require(). Intended for use from the widgets-in-template feature of dijit._WidgetsInTemplateMixin.
Returns:Mixed | Array

Returns a blended object that is an array of the instantiated objects, but also can include a promise that is resolved with the instantiated objects. This is done for backwards compatibility. If the parser auto-requires modules, it will always behave in a promise fashion and parser.parse().then(function(instances){...}) should be used.

Examples

Example 1

Parse all widgets on a page: 

parser.parse();

Example 2

Parse all classes within the node with id="foo" 

parser.parse(dojo.byId('foo'));

Example 3

Parse all classes in a page, but do not call .startup() on any child 

parser.parse({ noStart: true })

Example 4

Parse all classes in a node, but do not call .startup() 

parser.parse(someNode, { noStart:true });
// or
parser.parse({ noStart:true, rootNode: someNode });
scan(root,options)
Defined by dojo/parser

Scan a DOM tree and return an array of objects representing the DOMNodes that need to be turned into widgets.

Search specified node (or document root node) recursively for class instances and return an array of objects that represent potential widgets to be instantiated. Searches for either data-dojo-type="MID" or dojoType="MID" where "MID" is a module ID like "dijit/form/Button" or a fully qualified Class name like "dijit/form/Button". If the MID is not currently available, scan will attempt to require() in the module.

See parser.parse() for details of markup.

Parameter Type Description
root DomNode
Optional

A default starting root node from which to start the parsing. Can be omitted, defaulting to the entire document. If omitted, the options object can be passed in this place. If the options object has a rootNode member, that is used.
options Object

a kwArgs options object, see parse() for details

Returns:Promise | undefined

A promise that is resolved with the nodes that have been parsed.

Error in the documentation? Can’t find what you are looking for? Let us know!