The Dojo Parser¶
TODOC – A very brief writeup is available here: http://dojocampus.org/content/2008/03/08/the-dojo-parser/
The Dojo Parser is an optional module which is used to convert specially decorated nodes in the DOM and convert them into Dijits. By decorated we mean use of a dojoType attribute. Any “Class” (or object, such as the ones created by dojo.declare) can be instantiated by using a dojoType attribute on some node in the DOM, and create a widget out of it.
This is not limited to Dijit, or dojo.declare.
Loading the Parser¶
To include the Dojo parser on your page, require the module dojo.parser:
dojo.require("dojo.parser");
note: dijit._Templated require()'s dojo.parser, so a lot of examples don't include this step (dijit._Templated is loaded by most every Dijit). It is always safer to explicitly require the module than to assume it has been loaded.
Running the Parser¶
There are two ways to run the dojo.parser: manually, or before onLoad.
To execute the parser manually, simply call the function parse:
dojo.parser.parse();
This will scan the entire DOM for dojoType attributes, and create new instances from the nodes.
todoc: scoping a parser call to node by stringId|domNode
todoc: running parser onload
Setting the parser behavior¶
todoc: parseOnLoad parseOnLoad:false by default, parseOnLoad:true optional, parseOnLoad:true makes addOnLoad call after parsing. howto set parseOnLoad
Instantiating a Node¶
HTML sets all attributes on nodes as strings. However, when the parser instantiates your nodes, it looks at the prototype of the class you are trying to instantiate (via dojoType attribute) and trys to make a "best guess" at what type your value should be. This requires that all attributes you want to be passed in via the parser have a corresponding empty class member in the class you are trying to instantiate.
- Empty values of types are as follows:
- 0 = an integer
- "" = a string
- null = an object
- [] = an array
Private members (those that begin with an underscore (_) ) are not mapped in from the source node.
For example, given the class:
dojo.declare("my.custom.type", null, {
name: "",
value: 0,
objectVal: null,
anotherObject: null,
arrayVal: [],
typedArray: null,
_privateVal: 0
});
And HTML node:
<div dojoType="my.custom.type" name="nm" value="5" objectVal="{a: 1, b:'c'}"
anotherObject="namedObj" arrayVal="a,b,c,1,2" typedArray="['a','b','c',1,2]"
_privateVal="5" anotherValue="more"></div>
The parser would create an object and pass it paramaters of:
{
name: "nm", // Just a simple string
value: 5, // Typed to an integer
objectVal: {a: 1, b:'c'}, // Typed to an object
anotherObject: dojo.getObject("namedObj"), // For strings, try getting the object via dojo.getObject
arrayVal: ["a","b","c","1","2"], // When typing to an array, all entries are strings
typedArray: ["a", "b", "c", 1, 2] // To get a "typed" array, treat it like an object instead
}
Note that _privateVal is not passed in (since it is private), and anotherValue is not passed in either (since it does not exist in the prototype of the class).
The parser automatically will call the startup() function of all nodes when it is finished parsing (if the function exists, ie for dijit widgets)
NEW in 1.3: Beginning in release 1.3 of dojo, you can manually call dojo.parser.instantiate on any node - and pass in an additional mixin to specify options, such as dojoType, etc. The values in the mixin would override any values in your node. For example:
<div id="myDiv" name="ABC" value="1"></div>
You can manually call the parser's instantiate function (which does the "Magical Typing") by doing:
dojo.parser.instantiate([dojo.byId("myDiv")], {dojoType: "my.custom.type});
Calling instantiate in this way will return to you a list of instances that were created. Note that the first parameter to instantiate is an array of nodes...even if it's one-element you need to wrap it in an array
Caveats¶
todoc: re-parsing, duplicate id's
Examples¶
Load some HTML content from a remote URL, and convert the nodes decorated with dojoType's into widgets:
dojo.xhrGet({
url: "widgets.html",
load: function(data){
dojo.byId("container").innerHTML = data;
dojo.parser.parse("container");
}
});
Delay page-level parsing until after some custom code (having set parseOnLoad:false):
dojo.require("dojo.parser");
dojo.addOnLoad(function(){
// do something();
dojo.parser.parse();
});
See Also¶
- Understanding The Parser - Part of "The book of Dojo 0.9"