main

dojo/main

Summary

This module is the foundational module of the dojo boot sequence; it defines the dojo object.

Properties

back

Defined by: dojo/back

baseUrl

Defined by: dojo/_base/configSpidermonkey

behavior

Defined by: dojo/behavior

cldr

Defined by: dojo/cldr/monetary

colors

Defined by: dojo/colors

config

Defined by: dojo/_base/kernel

connectPublisher

Defined by: dojo/robotx

contentHandlers

Defined by: dojo/_base/xhr

currency

Defined by: dojo/currency

data

Defined by: dojo/data/util/filter

date

Defined by: dojo/date/stamp

dijit

Defined by: dojo/_base/kernel

dnd

Defined by: dojo/dnd/common

doc

Defined by: dojo/_base/window

dojox

Defined by: dojo/_base/kernel

fx

Defined by: dojo/fx

gears

Defined by: dojo/gears

global

Defined by: dojo/_base/window

html

Defined by: dojo/html

i18n

Defined by: dojo/i18n

io

Defined by: dojo/io/iframe

isAir

Defined by: dojo/_base/sniff

isAndroid

Defined by: dojo/_base/sniff

isAsync

Defined by: dojo/_base/kernel

isBrowser

Defined by: dojo/_base/configFirefoxExtension

isChrome

Defined by: dojo/_base/sniff

isCopyKey

Defined by: dojox/grid/_Grid

isFF

Defined by: dojo/_base/configFirefoxExtension

isIE

Defined by: dojo/_base/sniff

isIos

Defined by: dojo/_base/sniff

isKhtml

Defined by: dojo/_base/sniff

isMac

Defined by: dojo/_base/sniff

isMoz

Defined by: dojo/_base/configFirefoxExtension

isMozilla

Defined by: dojo/_base/configFirefoxExtension

isOpera

Defined by: dojo/_base/sniff

isQuirks

Defined by: dojo/_base/configFirefoxExtension

isSafari

Defined by: dojo/_base/sniff

isSpidermonkey

Defined by: dojo/_base/configSpidermonkey

isWebKit

Defined by: dojo/_base/sniff

isWii

Defined by: dojo/_base/sniff

keys

Defined by: dojo/keys

locale

Defined by: dojo/_base/configFirefoxExtension

mouseButtons

Defined by: dojo/mouse

number

Defined by: dojo/number

parser

Defined by: dojox/mobile/parser

publish

Defined by: dojo/robotx

query

Defined by: dojo/query

regexp

Defined by: dojo/regexp

rpc

Defined by: dojo/rpc/RpcService

scopeMap

Defined by: dojo/_base/kernel

store

Defined by: dojo/store/Cache

string

Defined by: dojo/string

subscribe

Defined by: dojo/robotx

tests

Defined by: dojo/tests

toJsonIndentStr

Defined by: dojo/_base/json

touch

Defined by: dojo/touch

version

Defined by: dojo/_base/kernel

window

Defined by: dojo/window

Methods

AdapterRegistry(returnWrappers)

Defined by dojo/AdapterRegistry

A registry to make contextual calling/searching easier.

Objects of this class keep list of arrays in the form [name, check, wrap, directReturn] that are used to determine what the contextual result of a set of checked arguments is. All check/wrap functions in this registry should be of the same arity.

// create a new registry
require(["dojo/AdapterRegistry"],
function(AdapterRegistry){
    var reg = new AdapterRegistry();
    reg.register("handleString",
        function(str){
            return typeof val == "string"
        },
        function(str){
            // do something with the string here
        }
    );
    reg.register("handleArr",
        dojo.isArray,
        function(arr){
            // do something with the array here
        }
    );

    // now we can pass reg.match() *either* an array or a string and
    // the value we pass will get handled by the right function
    reg.match("someValue"); // will call the first function
    reg.match(["someValue"]); // will call the second
});

addClass(node,classStr)

Defined by dojo/dom-class

Adds the specified classes to the end of the class list on the passed node. Will not re-apply duplicate classes.

require(["dojo/dom-class"], function(domClass){
    domClass.add("someNode", "anewClass");
});

require(["dojo/dom-class"], function(domClass){
    domClass.add("someNode", "firstClass secondClass");
});

require(["dojo/dom-class"], function(domClass){
    domClass.add("someNode", ["firstClass", "secondClass"]);
});

require(["dojo/query"], function(query){
    query("ul > li").addClass("firstLevel");
});

addOnLoad(priority,context,callback)

Defined by dojo/ready

Add a function to execute on DOM content loaded and all requested modules have arrived and been evaluated. In most cases, the domReady plug-in should suffice and this method should not be needed.

When called in a non-browser environment, just checks that all requested modules have arrived and been evaluated.

require(["dojo/ready"], function(ready){
    ready(function(){ alert("Dom ready!"); });
});

require(["dojo/ready"], function(ready){
    ready(2, function(){ alert("low priority ready!"); })
});

require(["dojo/ready"], function(ready){
    ready(foo, function(){
        // in here, this == foo
    });
});

require(["dojo/ready"], function(ready){
    var foo = { dojoReady: function(){ console.warn(this, "dojo dom and modules ready."); } };
    ready(foo, "dojoReady");
});

addOnUnload(obj,functionName)

Defined by dojo/_base/unload

Registers a function to be triggered when the page unloads. Deprecated, use on(window, "beforeunload", lang.hitch(obj, functionName)) instead.

The first time that addOnUnload is called Dojo will register a page listener to trigger your unload handler with.

In a browser environment, the functions will be triggered during the window.onbeforeunload event. Be careful of doing too much work in an unload handler. onbeforeunload can be triggered if a link to download a file is clicked, or if the link is a javascript: link. In these cases, the onbeforeunload event fires, but the document is not actually destroyed. So be careful about doing destructive operations in a dojo.addOnUnload callback.

Further note that calling dojo.addOnUnload will prevent browsers from using a "fast back" cache to make page loading via back button instantaneous.

var afunc = function() {console.log("global function");};
require(["dojo/_base/unload"], function(unload) {
    var foo = {bar: function(){ console.log("bar unloading...");}, 
               data: "mydata"};
    unload.addOnUnload(afunc);
    unload.addOnUnload(foo, "bar");
    unload.addOnUnload(foo, function(){console.log("", this.data);});
});

addOnWindowUnload(obj,functionName)

Defined by dojo/_base/configFirefoxExtension

registers a function to be triggered when window.onunload fires. Be careful trying to modify the DOM or access JavaScript properties during this phase of page unloading: they may not always be available. Consider dojo.addOnUnload() if you need to modify the DOM or do heavy JavaScript work.

dojo.addOnWindowUnload(functionPointer)
dojo.addOnWindowUnload(object, "functionName")
dojo.addOnWindowUnload(object, function(){ /* ... */});

anim(node,properties,duration,easing,onEnd,delay)

Defined by dojo/_base/fx

A simpler interface to animateProperty(), also returns an instance of Animation but begins the animation immediately, unlike nearly every other Dojo animation API.

Simpler (but somewhat less powerful) version of animateProperty. It uses defaults for many basic properties and allows for positional parameters to be used in place of the packed "property bag" which is used for other Dojo animation methods.

The Animation object returned will be already playing, so calling play() on it again is (usually) a no-op.

Returns: undefined

basefx.anim("id", { opacity: 0 });

basefx.anim("id", { opacity: 0 }, 1000);

animateProperty(args)

Defined by dojo/_base/fx

Returns an animation that will transition the properties of node defined in args depending how they are defined in args.properties

Foundation of most dojo/_base/fx animations. It takes an object of "properties" corresponding to style properties, and animates them in parallel over a set duration.

Returns: instance

basefx.animateProperty({
    node: "nodeId",
    properties: { width: 400 },
}).play();

basefx.animateProperty({ node: node, duration:2000,
    properties: {
        width: { start: '200', end: '400', units:"px" },
        height: { start:'200', end: '400', units:"px" },
        paddingTop: { start:'5', end:'50', units:"px" }
    }
}).play();

basefx.animateProperty({
    node: "nodeId",
    // dojo figures out the start value
    properties: { width: { end: 400 } },
    easing: function(n){
        return (n==0) ? 0 : Math.pow(2, 10 * (n - 1));
    },
    onEnd: function(node){
        // called when the animation finishes. The animation
        // target is passed to this function
    }
}).play(500); // delay playing half a second

var anim = basefx.animateProperty({
    node:"someId",
    properties:{
        width:400, height:500
    }
});
aspect.after(anim, "onEnd", function(){
    console.log("animation ended");
}, true);
// play the animation now:
anim.play();

basefx.animateProperty({
    node:"mine",
    properties:{
        height:function(node){
            // shrink this node by 50%
            return domGeom.position(node).h / 2
        },
        width:{
            start:function(node){ return 100; },
            end:function(node){ return 200; }
        }
    }
}).play();

Animation(args)

Defined by dojo/_base/fx

A generic animation class that fires callbacks into its handlers object at various states.

A generic animation class that fires callbacks into its handlers object at various states. Nearly all dojo animation functions return an instance of this method, usually without calling the .play() method beforehand. Therefore, you will likely need to call .play() on instances of Animation when one is returned.

attr(node,name,value)

Defined by dojo/_base/html

Gets or sets an attribute on an HTML element.

Handles normalized getting and setting of attributes on DOM Nodes. If 2 arguments are passed, and a the second argument is a string, acts as a getter.

If a third argument is passed, or if the second argument is a map of attributes, acts as a setter.

When passing functions as values, note that they will not be directly assigned to slots on the node, but rather the default behavior will be removed and the new behavior will be added using dojo.connect(), meaning that event handler properties will be normalized and that some caveats with regards to non-standard behaviors for onsubmit apply. Namely that you should cancel form submission using dojo.stopEvent() on the passed event object instead of returning a boolean value from the handler itself.

Returns: any | undefined

when used as a getter, the value of the requested attribute or null if that attribute does not have a specified or default value;

when used as a setter, the DOM node

// get the current value of the "foo" attribute on a node
dojo.attr(dojo.byId("nodeId"), "foo");
// or we can just pass the id:
dojo.attr("nodeId", "foo");

// use attr() to set the tab index
dojo.attr("nodeId", "tabIndex", 3);

dojo.attr("formId", {
    "foo": "bar",
    "tabIndex": -1,
    "method": "POST",
    "onsubmit": function(e){
        // stop submitting the form. Note that the IE behavior
        // of returning true or false will have no effect here
        // since our handler is connect()ed to the built-in
        // onsubmit behavior and so we need to use
        // dojo.stopEvent() to ensure that the submission
        // doesn't proceed.
        dojo.stopEvent(e);

        // submit the form with Ajax
        dojo.xhrPost({ form: "formId" });
    }
});

dojo.attr("someNode",{
    id:"bar",
    style:{
        width:"200px", height:"100px", color:"#000"
    }
});

var obj = { color:"#fff", backgroundColor:"#000" };
dojo.attr("someNode", "style", obj);

// though shorter to use `dojo.style()` in this case:
dojo.style("someNode", obj);

blendColors(start,end,weight,obj)

Defined by dojo/_base/Color

Blend colors end and start with weight from 0 to 1, 0.5 being a 50/50 blend, can reuse a previously allocated Color object for the result

Returns: undefined

body(doc)

Defined by dojo/_base/window

Return the body element of the specified document or of dojo/_base/window::doc.

Returns: undefined

win.body().appendChild(dojo.doc.createElement('div'));

byId(id,doc)

Defined by dojo/dom

Returns DOM node with matching id attribute or falsy value (ex: null or undefined) if not found. If id is a DomNode, this function is a no-op.

Returns: instance

require(["dojo/dom"], function(dom){
    var n = dom.byId("foo");
});

require(["dojo/dom"], function(dom){
    var n = dom.byId("bar");
    if(n){ doStuff() ... }
});

require(["dojo/dom"], function(dom){
    var foo = function(nodeOrId){
        nodeOrId = dom.byId(nodeOrId);
        // ... more stuff
    }
});

cache(module,url,value)

Defined by dojo/text

A getter and setter for storing the string content associated with the module and url arguments.

If module is a string that contains slashes, then it is interpretted as a fully resolved path (typically a result returned by require.toUrl), and url should not be provided. This is the preferred signature. If module is a string that does not contain slashes, then url must also be provided and module and url are used to call dojo.moduleUrl() to generate a module URL. This signature is deprecated. If value is specified, the cache value for the moduleUrl will be set to that value. Otherwise, dojo.cache will fetch the moduleUrl and store it in its internal cache and return that cached value for the URL. To clear a cache value pass null for value. Since XMLHttpRequest (XHR) is used to fetch the the URL contents, only modules on the same domain of the page can use this capability. The build system can inline the cache values though, to allow for xdomain hosting.

Returns: undefined | null

//If template.html contains "<h1>Hello</h1>" that will be
//the value for the text variable.
//Note: This is pre-AMD, deprecated syntax
var text = dojo["cache"]("my.module", "template.html");

//If template.html contains "<html><body><h1>Hello</h1></body></html>", the
//text variable will contain just "<h1>Hello</h1>".
//Note: This is pre-AMD, deprecated syntax
var text = dojo["cache"]("my.module", "template.html", {sanitize: true});

//If template.html contains "<html><body><h1>Hello</h1></body></html>", the
//text variable will contain just "<h1>Hello</h1>".
//Note: This is pre-AMD, deprecated syntax
var text = dojo["cache"](new dojo._Url("my/module/template.html"), {sanitize: true});

clearCache()

Defined by dojo/_base/array

Color(color)

Defined by dojo/_base/Color

Takes a named string, hex string, array of rgb or rgba values, an object with r, g, b, and a properties, or another Color object and creates a new Color instance to work from.

require(["dojo/_base/color"], function(Color){
    var c = new Color();
    c.setColor([0,0,0]); // black
    var hex = c.toHex(); // #000000
});

  require(["dojo/_base/color", "dojo/dom-style"], function(Color, domStyle){
      var color = domStyle("someNode", "backgroundColor");
      var n = new Color(color);
      // adjust the color some
      n.r *= .5;
      console.log(n.toString()); // rgb(128, 255, 255);
  });

colorFromArray(a,obj)

Defined by dojo/_base/Color

Builds a Color from a 3 or 4 element array, mapping each element in sequence to the rgb(a) values of the color.

Returns: any | undefined

A Color object. If obj is passed, it will be the return value.

require(["dojo/_base/color"], function(Color){
    var myColor = new Color().fromArray([237,237,237,0.5]); // grey, 50% alpha
});

colorFromHex(color,obj)

Defined by dojo/_base/Color

Converts a hex string with a '#' prefix to a color object. Supports 12-bit #rgb shorthand. Optionally accepts a Color object to update with the parsed value.

Returns: any

A Color object. If obj is passed, it will be the return value.

require(["dojo/_base/color"], function(Color){
    var thing = new Color().fromHex("#ededed"); // grey, longhand
    var thing2 = new Color().fromHex("#000"); // black, shorthand
});

colorFromRgb(color,obj)

Defined by dojo/colors

get rgb(a) array from css-style color declarations

this function can handle all 4 CSS3 Color Module formats: rgb, rgba, hsl, hsla, including rgb(a) with percentage values.

Returns: null

colorFromString(str,obj)

Defined by dojo/_base/Color

Parses str for a color value. Accepts hex, rgb, and rgba style color values.

Acceptable input values for str may include arrays of any form accepted by dojo.colorFromArray, hex strings such as "#aaaaaa", or rgb or rgba strings such as "rgb(133, 200, 16)" or "rgba(10, 10, 10, 50)"

Returns: any

A Color object. If obj is passed, it will be the return value.

connect(obj,event,context,method,dontFix)

Defined by dojo/_base/connect

dojo.connect is a deprecated event handling and delegation method in Dojo. It allows one function to "listen in" on the execution of any other, triggering the second whenever the first is called. Many listeners may be attached to a function, and source functions may be either regular function calls or DOM events.

Connects listeners to actions, so that after event fires, a listener is called with the same arguments passed to the original function.

Since dojo.connect allows the source of events to be either a "regular" JavaScript function or a DOM event, it provides a uniform interface for listening to all the types of events that an application is likely to deal with though a single, unified interface. DOM programmers may want to think of it as "addEventListener for everything and anything".

When setting up a connection, the event parameter must be a string that is the name of the method/event to be listened for. If obj is null, kernel.global is assumed, meaning that connections to global methods are supported but also that you may inadvertently connect to a global by passing an incorrect object name or invalid reference.

dojo.connect generally is forgiving. If you pass the name of a function or method that does not yet exist on obj, connect will not fail, but will instead set up a stub method. Similarly, null arguments may simply be omitted such that fewer than 4 arguments may be required to set up a connection See the examples for details.

The return value is a handle that is needed to remove this connection with dojo.disconnect.

Returns: undefined

dojo.connect(obj, "onchange", ui, "update");
dojo.connect(obj, "onchange", ui, ui.update); // same

var link = dojo.connect(obj, "onchange", ui, "update");
...
dojo.disconnect(link);

dojo.connect(null, "onglobalevent", watcher, "handler");

dojo.connect(ob, "onCustomEvent", null, "customEventHandler");
dojo.connect(ob, "onCustomEvent", "customEventHandler"); // same

dojo.connect(ob, "onCustomEvent", null, customEventHandler);
dojo.connect(ob, "onCustomEvent", customEventHandler); // same

dojo.connect(null, "globalEvent", null, globalHandler);
dojo.connect("globalEvent", globalHandler); // same

contentBox(node,box)

Defined by dojo/_base/html

Getter/setter for the content-box of node.

Returns an object in the expected format of box (regardless if box is passed). The object might look like: { l: 50, t: 200, w: 300: h: 150 } for a node offset from its parent 50px to the left, 200px from the top with a content width of 300px and a content-height of 150px. Note that the content box may have a much larger border or margin box, depending on the box model currently in use and CSS values set/inherited for node. While the getter will return top and left values, the setter only accepts setting the width and height.

Returns: undefined

cookie(name,value,props)

Defined by dojo/cookie

Get or set a cookie.

If one argument is passed, returns the value of the cookie For two or more arguments, acts as a setter.

Returns: undefined

require(["dojo/cookie", "dojo/json"], function(cookie, json){
    cookie("configObj", json.stringify(config, {expires: 5 }));
});

require(["dojo/cookie", "dojo/json"], function(cookie, json){
    config = json.parse(cookie("configObj"));
});

require(["dojo/cookie"], function(cookie){
    cookie("configObj", null, {expires: -1});
});

coords(node,includeScroll)

Defined by dojo/_base/html

Deprecated: Use position() for border-box x/y/w/h or marginBox() for margin-box w/h/l/t.

Returns an object that measures margin-box (w)idth/(h)eight and absolute position x/y of the border-box. Also returned is computed (l)eft and (t)op values in pixels from the node's offsetParent as returned from marginBox(). Return value will be in the form:

{ l: 50, t: 200, w: 300: h: 150, x: 100, y: 300 }

Does not act as a setter. If includeScroll is passed, the x and

y params are affected as one would expect in dojo.position().

Returns: undefined

create(tag,attrs,refNode,pos)

Defined by dojo/dom-construct

Create an element, allowing for optional attribute decoration and placement.

A DOM Element creation function. A shorthand method for creating a node or a fragment, and allowing for a convenient optional attribute setting step, as well as an optional DOM placement reference.

Attributes are set by passing the optional object through dojo.setAttr. See dojo.setAttr for noted caveats and nuances, and API if applicable.

Placement is done via dojo.place, assuming the new node to be the action node, passing along the optional reference node and position.

Returns: undefined

require(["dojo/dom-construct"], function(domConstruct){
    var n = domConstruct.create("div");
});

require(["dojo/dom-construct"], function(domConstruct){
    var n = domConstruct.create("div", { innerHTML:"<p>hi</p>" });
});

require(["dojo/dom-construct"], function(domConstruct){
    var n = domConstruct.create("div", null, dojo.body());
});

require(["dojo/dom-construct", "dojo/_base/array"],
function(domConstruct, arrayUtil){
    var ul = domConstruct.create("ul", null, "someId", "first");
    var items = ["one", "two", "three", "four"];
    arrayUtil.forEach(items, function(data){
        domConstruct.create("li", { innerHTML: data }, ul);
    });
});

require(["dojo/dom-construct"], function(domConstruct){
    domConstruct.create("a", { href:"foo.html", title:"Goto FOO!" }, dojo.body());
});

declare(className,superclass,props)

Defined by dojo/_base/declare

Create a feature-rich constructor from compact notation.

Create a constructor using a compact notation for inheritance and prototype extension.

Mixin ancestors provide a type of multiple inheritance. Prototypes of mixin ancestors are copied to the new class: changes to mixin prototypes will not affect classes to which they have been mixed in.

Ancestors can be compound classes created by this version of declare(). In complex cases all base classes are going to be linearized according to C3 MRO algorithm (see http://www.python.org/download/releases/2.3/mro/ for more details).

"className" is cached in "declaredClass" property of the new class, if it was supplied. The immediate super class will be cached in "superclass" property of the new class.

Methods in "props" will be copied and modified: "nom" property (the declared name of the method) will be added to all copied functions to help identify them for the internal machinery. Be very careful, while reusing methods: if you use the same function under different names, it can produce errors in some cases.

It is possible to use constructors created "manually" (without declare()) as bases. They will be called as usual during the creation of an instance, their methods will be chained, and even called by "this.inherited()".

Special property "-chains-" governs how to chain methods. It is a dictionary, which uses method names as keys, and hint strings as values. If a hint string is "after", this method will be called after methods of its base classes. If a hint string is "before", this method will be called before methods of its base classes.

If "constructor" is not mentioned in "-chains-" property, it will be chained using the legacy mode: using "after" chaining, calling preamble() method before each constructor, if available, and calling postscript() after all constructors were executed. If the hint is "after", it is chained as a regular method, but postscript() will be called after the chain of constructors. "constructor" cannot be chained "before", but it allows a special hint string: "manual", which means that constructors are not going to be chained in any way, and programmer will call them manually using this.inherited(). In the latter case postscript() will be called after the construction.

All chaining hints are "inherited" from base classes and potentially can be overridden. Be very careful when overriding hints! Make sure that all chained methods can work in a proposed manner of chaining.

Once a method was chained, it is impossible to unchain it. The only exception is "constructor". You don't need to define a method in order to supply a chaining hint.

If a method is chained, it cannot use this.inherited() because all other methods in the hierarchy will be called automatically.

Usually constructors and initializers of any kind are chained using "after" and destructors of any kind are chained as "before". Note that chaining assumes that chained methods do not return any value: any returned value will be discarded.

Returns: dojo/_base/declare.__DeclareCreatedObject | undefined

New constructor function.

declare("my.classes.bar", my.classes.foo, {
    // properties to be added to the class prototype
    someValue: 2,
    // initialization function
    constructor: function(){
        this.myComplicatedObject = new ReallyComplicatedObject();
    },
    // other functions
    someMethod: function(){
        doStuff();
    }
});

var MyBase = declare(null, {
    // constructor, properties, and methods go here
    // ...
});
var MyClass1 = declare(MyBase, {
    // constructor, properties, and methods go here
    // ...
});
var MyClass2 = declare(MyBase, {
    // constructor, properties, and methods go here
    // ...
});
var MyDiamond = declare([MyClass1, MyClass2], {
    // constructor, properties, and methods go here
    // ...
});

var F = function(){ console.log("raw constructor"); };
F.prototype.method = function(){
    console.log("raw method");
};
var A = declare(F, {
    constructor: function(){
        console.log("A.constructor");
    },
    method: function(){
        console.log("before calling F.method...");
        this.inherited(arguments);
        console.log("...back in A");
    }
});
new A().method();
// will print:
// raw constructor
// A.constructor
// before calling F.method...
// raw method
// ...back in A

var A = declare(null, {
    "-chains-": {
        destroy: "before"
    }
});
var B = declare(A, {
    constructor: function(){
        console.log("B.constructor");
    },
    destroy: function(){
        console.log("B.destroy");
    }
});
var C = declare(B, {
    constructor: function(){
        console.log("C.constructor");
    },
    destroy: function(){
        console.log("C.destroy");
    }
});
new C().destroy();
// prints:
// B.constructor
// C.constructor
// C.destroy
// B.destroy

var A = declare(null, {
    "-chains-": {
        constructor: "manual"
    }
});
var B = declare(A, {
    constructor: function(){
        // ...
        // call the base constructor with new parameters
        this.inherited(arguments, [1, 2, 3]);
        // ...
    }
});

var A = declare(null, {
    "-chains-": {
        m1: "before"
    },
    m1: function(){
        console.log("A.m1");
    },
    m2: function(){
        console.log("A.m2");
    }
});
var B = declare(A, {
    "-chains-": {
        m2: "after"
    },
    m1: function(){
        console.log("B.m1");
    },
    m2: function(){
        console.log("B.m2");
    }
});
var x = new B();
x.m1();
// prints:
// B.m1
// A.m1
x.m2();
// prints:
// A.m2
// B.m2

Deferred(canceller)

Defined by dojo/_base/Deferred

Deprecated. This module defines the legacy dojo/_base/Deferred API. New code should use dojo/Deferred instead.

The Deferred API is based on the concept of promises that provide a generic interface into the eventual completion of an asynchronous action. The motivation for promises fundamentally is about creating a separation of concerns that allows one to achieve the same type of call patterns and logical data flow in asynchronous code as can be achieved in synchronous code. Promises allows one to be able to call a function purely with arguments needed for execution, without conflating the call with concerns of whether it is sync or async. One shouldn't need to alter a call's arguments if the implementation switches from sync to async (or vice versa). By having async functions return promises, the concerns of making the call are separated from the concerns of asynchronous interaction (which are handled by the promise).

The Deferred is a type of promise that provides methods for fulfilling the promise with a successful result or an error. The most important method for working with Dojo's promises is the then() method, which follows the CommonJS proposed promise API. An example of using a Dojo promise:

var resultingPromise = someAsyncOperation.then(function(result){
    ... handle result ...
},
function(error){
    ... handle error ...
});

The .then() call returns a new promise that represents the result of the execution of the callback. The callbacks will never affect the original promises value.

The Deferred instances also provide the following functions for backwards compatibility:

• addCallback(handler)
• addErrback(handler)
• callback(result)
• errback(result)

Callbacks are allowed to return promises themselves, so you can build complicated sequences of events with ease.

The creator of the Deferred may specify a canceller. The canceller is a function that will be called if Deferred.cancel is called before the Deferred fires. You can use this to implement clean aborting of an XMLHttpRequest, etc. Note that cancel will fire the deferred with a CancelledError (unless your canceller returns another kind of error), so the errbacks should be prepared to handle that error for cancellable Deferreds.

var deferred = new Deferred();
setTimeout(function(){ deferred.callback({success: true}); }, 1000);
return deferred;

// callback style:
function renderLotsOfData(data, callback){
    var success = false
    try{
        for(var x in data){
            renderDataitem(data[x]);
        }
        success = true;
    }catch(e){ }
    if(callback){
        callback(success);
    }
}


// using callback style
renderLotsOfData(someDataObj, function(success){
    // handles success or failure
    if(!success){
        promptUserToRecover();
    }
});
// NOTE: no way to add another callback here!!

// Deferred style:
function renderLotsOfData(data){
    var d = new Deferred();
    try{
        for(var x in data){
            renderDataitem(data[x]);
        }
        d.callback(true);
    }catch(e){
        d.errback(new Error("rendering failed"));
    }
    return d;
}


// using Deferred style
renderLotsOfData(someDataObj).then(null, function(){
    promptUserToRecover();
});
// NOTE: addErrback and addCallback both return the Deferred
// again, so we could chain adding callbacks or save the
// deferred for later should we need to be notified again.

// Deferred style and async func
function renderLotsOfData(data){
    var d = new Deferred();
    setTimeout(function(){
        try{
            for(var x in data){
                renderDataitem(data[x]);
            }
            d.callback(true);
        }catch(e){
            d.errback(new Error("rendering failed"));
        }
    }, 100);
    return d;
}


// using Deferred style
renderLotsOfData(someDataObj).then(null, function(){
    promptUserToRecover();
});

DeferredList(list,fireOnOneCallback,fireOnOneErrback,consumeErrors,canceller)

Defined by dojo/DeferredList

Deprecated, use dojo/promise/all instead. Provides event handling for a group of Deferred objects.

DeferredList takes an array of existing deferreds and returns a new deferred of its own this new deferred will typically have its callback fired when all of the deferreds in the given list have fired their own deferreds. The parameters fireOnOneCallback and fireOnOneErrback, will fire before all the deferreds as appropriate

deprecated(behaviour,extra,removal)

Defined by dojo/_base/kernel

Log a debug message to indicate that a behavior has been deprecated.

dojo.deprecated("myApp.getTemp()", "use myApp.getLocaleTemp() instead", "1.0");

destroy(node)

Defined by dojo/_base/html

disconnect(handle)

Defined by dojo/_base/connect

Remove a link created by dojo.connect.

Removes the connection between event and the method referenced by handle.

docScroll(doc)

Defined by dojo/dom-geometry

Returns an object with {node, x, y} with corresponding offsets.

Returns: Object | undefined

empty(node)

Defined by dojo/_base/html

eval(scriptText)

Defined by dojo/_base/kernel

A legacy method created for use exclusively by internal Dojo methods. Do not use this method directly unless you understand its possibly-different implications on the platforms your are targeting.

Makes an attempt to evaluate scriptText in the global scope. The function works correctly for browsers that support indirect eval.

As usual, IE does not. On IE, the only way to implement global eval is to use execScript. Unfortunately, execScript does not return a value and breaks some current usages of dojo.eval. This implementation uses the technique of executing eval in the scope of a function that is a single scope frame below the global scope; thereby coming close to the global scope. Note carefully that

dojo.eval("var pi = 3.14;");

will define global pi in non-IE environments, but define pi only in a temporary local scope for IE. If you want to define a global variable using dojo.eval, write something like

dojo.eval("window.pi = 3.14;")

Returns: any

The result of the evaluation. Often undefined

every(arr,callback,thisObject)

Defined by dojo/_base/array

Determines whether or not every item in arr satisfies the condition implemented by callback.

This function corresponds to the JavaScript 1.6 Array.every() method, with one difference: when run over sparse arrays, this implementation passes the "holes" in the sparse array to the callback function with a value of undefined. JavaScript 1.6's every skips the holes in the sparse array. For more details, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/every

Returns: Boolean

// returns false
array.every([1, 2, 3, 4], function(item){ return item>1; });

// returns true
array.every([1, 2, 3, 4], function(item){ return item>0; });

exit(exitcode)

Defined by dojo/_base/configSpidermonkey

experimental(moduleName,extra)

Defined by dojo/_base/kernel

Marks code as experimental.

This can be used to mark a function, file, or module as experimental. Experimental code is not ready to be used, and the APIs are subject to change without notice. Experimental code may be completed deleted without going through the normal deprecation process.

dojo.experimental("dojo.data.Result");

dojo.experimental("dojo.weather.toKelvin()", "PENDING approval from NOAA");

fadeIn(args)

Defined by dojo/_base/fx

Returns an animation that will fade node defined in 'args' from its current opacity to fully opaque.

Returns: undefined

fadeOut(args)

Defined by dojo/_base/fx

Returns an animation that will fade node defined in 'args' from its current opacity to fully transparent.

Returns: undefined

fieldToObject(inputNode)

Defined by dojo/dom-form

Serialize a form field to a JavaScript object.

Returns the value encoded in a form field as as a string or an array of strings. Disabled form elements and unchecked radio and checkboxes are skipped. Multi-select elements are returned as an array of string values.

Returns: Object | undefined

filter(arr,callback,thisObject)

Defined by dojo/_base/array

Returns a new Array with those items from arr that match the condition implemented by callback.

This function corresponds to the JavaScript 1.6 Array.filter() method, with one difference: when run over sparse arrays, this implementation passes the "holes" in the sparse array to the callback function with a value of undefined. JavaScript 1.6's filter skips the holes in the sparse array. For more details, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/filter

Returns: Array

// returns [2, 3, 4]
array.filter([1, 2, 3, 4], function(item){ return item>1; });

fixEvent(evt,sender)

Defined by dojo/_base/event

normalizes properties on the event object including event bubbling methods, keystroke normalization, and x/y positions

Returns: Event

native event object

fixIeBiDiScrollLeft(scrollLeft,doc)

Defined by dojo/dom-geometry

In RTL direction, scrollLeft should be a negative value, but IE returns a positive one. All codes using documentElement.scrollLeft must call this function to fix this error, otherwise the position will offset to right when there is a horizontal scrollbar.

Returns: Number | number

forEach(arr,callback,thisObject)

Defined by dojo/_base/array

for every item in arr, callback is invoked. Return values are ignored. If you want to break out of the loop, consider using array.every() or array.some(). forEach does not allow breaking out of the loop over the items in arr.

This function corresponds to the JavaScript 1.6 Array.forEach() method, with one difference: when run over sparse arrays, this implementation passes the "holes" in the sparse array to the callback function with a value of undefined. JavaScript 1.6's forEach skips the holes in the sparse array. For more details, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/forEach

// log out all members of the array:
array.forEach(
      [ "thinger", "blah", "howdy", 10 ],
      function(item){
          console.log(item);
      }
);

// log out the members and their indexes
array.forEach(
      [ "thinger", "blah", "howdy", 10 ],
      function(item, idx, arr){
          console.log(item, "at index:", idx);
      }
);

// use a scoped object member as the callback

var obj = {
      prefix: "logged via obj.callback:",
      callback: function(item){
          console.log(this.prefix, item);
      }
};

// specifying the scope function executes the callback in that scope
array.forEach(
      [ "thinger", "blah", "howdy", 10 ],
      obj.callback,
      obj
);

// alternately, we can accomplish the same thing with lang.hitch()
array.forEach(
      [ "thinger", "blah", "howdy", 10 ],
      lang.hitch(obj, "callback")
);

formToJson(formNode,prettyPrint)

Defined by dojo/dom-form

Create a serialized JSON string from a form node or string ID identifying the form to serialize

Returns: String | undefined

formToObject(formNode)

Defined by dojo/dom-form

Serialize a form node to a JavaScript object.

Returns the values encoded in an HTML form as string properties in an object which it then returns. Disabled form elements, buttons, and other non-value form elements are skipped. Multi-select elements are returned as an array of string values.

Returns: object

<form id="test_form">
    <input type="text" name="blah" value="blah">
    <input type="text" name="no_value" value="blah" disabled>
    <input type="button" name="no_value2" value="blah">
    <select type="select" multiple name="multi" size="5">
        <option value="blah">blah</option>
        <option value="thud" selected>thud</option>
        <option value="thonk" selected>thonk</option>
    </select>
</form>

{
    blah: "blah",
    multi: [
        "thud",
        "thonk"
    ]
};

formToQuery(formNode)

Defined by dojo/dom-form

Returns a URL-encoded string representing the form passed as either a node or string ID identifying the form to serialize

Returns: String | undefined

fromJson(js)

Defined by dojo/_base/json

Parses a JavaScript expression and returns a JavaScript value.

Throws for invalid JavaScript expressions. It does not use a strict JSON parser. It always delegates to eval(). The content passed to this method must therefore come from a trusted source. It is recommend that you use dojo/json's parse function for an implementation uses the (faster) native JSON parse when available.

Returns: undefined

getAttr(node,name)

Defined by dojo/dom-attr

Gets an attribute on an HTML element.

Handles normalized getting of attributes on DOM Nodes.

Returns: any | undefined | null

the value of the requested attribute or null if that attribute does not have a specified or default value;

// get the current value of the "foo" attribute on a node
require(["dojo/dom-attr", "dojo/dom"], function(domAttr, dom){
    domAttr.get(dom.byId("nodeId"), "foo");
    // or we can just pass the id:
    domAttr.get("nodeId", "foo");
}); 

getBorderExtents(node,computedStyle)

Defined by dojo/dom-geometry

returns an object with properties useful for noting the border dimensions.

• l/t/r/b = the sum of left/top/right/bottom border (respectively)
• w = the sum of the left and right border
• h = the sum of the top and bottom border

The w/h are used for calculating boxes. Normally application code will not need to invoke this directly, and will use the ...box... functions instead.

Returns: object

getComputedStyle(node)

Defined by dojo/dom-style

Returns a "computed style" object.

Gets a "computed style" object which can be used to gather information about the current state of the rendered node.

Note that this may behave differently on different browsers. Values may have different formats and value encodings across browsers.

Note also that this method is expensive. Wherever possible, reuse the returned object.

Use the dojo/dom-style.get() method for more consistent (pixelized) return values.

require(["dojo/dom-style", "dojo/dom"], function(domStyle, dom){
    domStyle.getComputedStyle(dom.byId('foo')).borderWidth;
});

require(["dojo/dom-style", "dojo/dom"], function(domStyle, dom){
    var cs = domStyle.getComputedStyle(dom.byId("someNode"));
    var w = cs.width, h = cs.height;
});

getContentBox(node,computedStyle)

Defined by dojo/dom-geometry

Returns an object that encodes the width, height, left and top positions of the node's content box, irrespective of the current box model.

Returns: object

getIeDocumentElementOffset(doc)

Defined by dojo/dom-geometry

returns the offset in x and y from the document body to the visual edge of the page for IE

The following values in IE contain an offset:

event.clientX
event.clientY
node.getBoundingClientRect().left
node.getBoundingClientRect().top

But other position related values do not contain this offset,

such as node.offsetLeft, node.offsetTop, node.style.left and node.style.top. The offset is always (2, 2) in LTR direction. When the body is in RTL direction, the offset counts the width of left scroll bar's width. This function computes the actual offset.

Returns: object

getL10nName(moduleName,bundleName,locale)

Defined by dojo/i18n

Returns: string

getMarginBox(node,computedStyle)

Defined by dojo/dom-geometry

returns an object that encodes the width, height, left and top positions of the node's margin box.

Returns: object

getMarginExtents(node,computedStyle)

Defined by dojo/dom-geometry

returns object with properties useful for box fitting with regards to box margins (i.e., the outer-box).

• l/t = marginLeft, marginTop, respectively
• w = total width, margin inclusive
• h = total height, margin inclusive

The w/h are used for calculating boxes. Normally application code will not need to invoke this directly, and will use the ...box... functions instead.

Returns: object

getMarginSize(node,computedStyle)

Defined by dojo/dom-geometry

returns an object that encodes the width and height of the node's margin box

Returns: object

getNodeProp(node,name)

Defined by dojo/dom-attr

Returns an effective value of a property or an attribute.

Returns: any

the value of the attribute

getPadBorderExtents(node,computedStyle)

Defined by dojo/dom-geometry

Returns object with properties useful for box fitting with regards to padding.

• l/t/r/b = the sum of left/top/right/bottom padding and left/top/right/bottom border (respectively)
• w = the sum of the left and right padding and border
• h = the sum of the top and bottom padding and border

The w/h are used for calculating boxes. Normally application code will not need to invoke this directly, and will use the ...box... functions instead.

Returns: object

getPadExtents(node,computedStyle)

Defined by dojo/dom-geometry

Returns object with special values specifically useful for node fitting.

Returns an object with w, h, l, t properties:

l/t/r/b = left/top/right/bottom padding (respectively)
w = the total of the left and right padding
h = the total of the top and bottom padding

If 'node' has position, l/t forms the origin for child nodes.

The w/h are used for calculating boxes. Normally application code will not need to invoke this directly, and will use the ...box... functions instead.

Returns: object

getProp(node,name)

Defined by dojo/dom-prop

Gets a property on an HTML element.

Handles normalized getting of properties on DOM nodes.

Returns: any | undefined

the value of the requested property or its default value

// get the current value of the "foo" property on a node
require(["dojo/dom-prop", "dojo/dom"], function(domProp, dom){
    domProp.get(dom.byId("nodeId"), "foo");
    // or we can just pass the id:
    domProp.get("nodeId", "foo");
});

getStyle(node,name)

Defined by dojo/dom-style

Accesses styles on a node.

Getting the style value uses the computed style for the node, so the value will be a calculated value, not just the immediate node.style value. Also when getting values, use specific style names, like "borderBottomWidth" instead of "border" since compound values like "border" are not necessarily reflected as expected. If you want to get node dimensions, use dojo/dom-geometry.getMarginBox(), dojo/dom-geometry.getContentBox() or dojo/dom-geometry.getPosition().

Returns: undefined

require(["dojo/dom-style", "dojo/dom"], function(domStyle, dom){
    domStyle.get("thinger");
});

require(["dojo/dom-style", "dojo/dom"], function(domStyle, dom){
    domStyle.get("thinger", "opacity"); // 1 by default
});

hasAttr(node,name)

Defined by dojo/dom-attr

Returns true if the requested attribute is specified on the given element, and false otherwise.

Returns: Boolean | contentWindow.document isn't accessible within IE7/8

true if the requested attribute is specified on the given element, and false otherwise

hasClass(node,classStr)

Defined by dojo/dom-class

Returns whether or not the specified classes are a portion of the class list currently applied to the node.

Returns: boolean

if(dojo.hasClass("someNode","aSillyClassName")){ ... }

hash(hash,replace)

Defined by dojo/hash

Gets or sets the hash string in the browser URL.

Handles getting and setting of location.hash.

• If no arguments are passed, acts as a getter.
• If a string is passed, acts as a setter.

Returns: any | undefined

when used as a getter, returns the current hash string. when used as a setter, returns the new hash string.

topic.subscribe("/dojo/hashchange", context, callback);

function callback (hashValue){
    // do something based on the hash value.
}

indexOf(arr,value,fromIndex,findLast)

Defined by dojo/_base/array

locates the first index of the provided value in the passed array. If the value is not found, -1 is returned.

This method corresponds to the JavaScript 1.6 Array.indexOf method, with two differences:

1. when run over sparse arrays, the Dojo function invokes the callback for every index whereas JavaScript 1.6's indexOf skips the holes in the sparse array.
2. uses equality (==) rather than strict equality (===)

For details on this method, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/indexOf

Returns: Number

isBodyLtr(doc)

Defined by dojo/dom-geometry

Returns true if the current language is left-to-right, and false otherwise.

Returns: Boolean | boolean

isDescendant(node,ancestor)

Defined by dojo/dom

Returns true if node is a descendant of ancestor

Returns: boolean

require(["dojo/dom"], function(dom){
    if(dom.isDescendant("bar", "foo")){ ... }
});

lastIndexOf(arr,value,fromIndex)

Defined by dojo/_base/array

locates the last index of the provided value in the passed array. If the value is not found, -1 is returned.

This method corresponds to the JavaScript 1.6 Array.lastIndexOf method, with two differences:

1. when run over sparse arrays, the Dojo function invokes the callback for every index whereas JavaScript 1.6's lasIndexOf skips the holes in the sparse array.
2. uses equality (==) rather than strict equality (===)

For details on this method, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/lastIndexOf

Returns: Number

loadInit(f)

Defined by dojo/_base/loader

map(arr,callback,thisObject,Ctr)

Defined by dojo/_base/array

applies callback to each element of arr and returns an Array with the results

This function corresponds to the JavaScript 1.6 Array.map() method, with one difference: when run over sparse arrays, this implementation passes the "holes" in the sparse array to the callback function with a value of undefined. JavaScript 1.6's map skips the holes in the sparse array. For more details, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/map

Returns: Array | instance

// returns [2, 3, 4, 5]
array.map([1, 2, 3, 4], function(item){ return item+1 });

marginBox(node,box)

Defined by dojo/_base/html

Getter/setter for the margin-box of node.

Getter/setter for the margin-box of node. Returns an object in the expected format of box (regardless if box is passed). The object might look like: { l: 50, t: 200, w: 300: h: 150 } for a node offset from its parent 50px to the left, 200px from the top with a margin width of 300px and a margin-height of 150px.

Returns: undefined

var box = dojo.marginBox("someNodeId");
console.dir(box);

var box = dojo.marginBox("someNodeId");
dojo.marginBox("someOtherNode", box);

moduleUrl(module,url)

Defined by dojo/_base/kernel

Returns a URL relative to a module.

Returns: string

var pngPath = dojo.moduleUrl("acme","images/small.png");
console.dir(pngPath); // list the object properties
// create an image and set it's source to pngPath's value:
var img = document.createElement("img");
img.src = pngPath;
// add our image to the document
dojo.body().appendChild(img);

// somewhere in a configuration block
dojo.registerModulePath("acme.widget", "../../acme/widget");
dojo.registerModulePath("acme.util", "../../util");

// ...

// code in a module using acme resources
var tmpltPath = dojo.moduleUrl("acme.widget","templates/template.html");
var dataPath = dojo.moduleUrl("acme.util","resources/data.json");

NodeList(array)

Defined by dojo/query

Array-like object which adds syntactic sugar for chaining, common iteration operations, animation, and node manipulation. NodeLists are most often returned as the result of dojo/query() calls.

NodeList instances provide many utilities that reflect core Dojo APIs for Array iteration and manipulation, DOM manipulation, and event handling. Instead of needing to dig up functions in the dojo package, NodeLists generally make the full power of Dojo available for DOM manipulation tasks in a simple, chainable way.

Returns: Array

require(["dojo/query", "dojo/dom"
], function(query, dom){
    query.NodeList(dom.byId("foo"));
});

require(["dojo/on", "dojo/dom"
], function(on, dom){
    var l = query(".thinger");
    l.forEach(function(node, index, nodeList){
        console.log(index, node.innerHTML);
    });
});

require(["dojo/query", "dojo/dom-construct", "dojo/dom"
], function(query, domConstruct, dom){
    var l = query(".thinger");
    // since NodeLists are real arrays, they have a length
    // property that is both readable and writable and
    // push/pop/shift/unshift methods
    console.log(l.length);
    l.push(domConstruct.create("span"));

    // dojo's normalized array methods work too:
    console.log( l.indexOf(dom.byId("foo")) );
    // ...including the special "function as string" shorthand
    console.log( l.every("item.nodeType == 1") );

    // NodeLists can be [..] indexed, or you can use the at()
    // function to get specific items wrapped in a new NodeList:
    var node = l[3]; // the 4th element
    var newList = l.at(1, 3); // the 2nd and 4th elements
});

require(["dojo/query", "dojo/NodeList-dom"
], function(query){
    query(".thinger")
        .onclick(function(e){ /* ... */ })
        .at(1, 3, 8) // get a subset
            .style("padding", "5px")
            .forEach(console.log);
});

objectToQuery(map)

Defined by dojo/io-query

takes a name/value mapping object and returns a string representing a URL-encoded version of that object.

Returns: undefined

{
    blah: "blah",
    multi: [
        "thud",
        "thonk"
    ]
};

"blah=blah&multi=thud&multi=thonk"

place(node,refNode,position)

Defined by dojo/dom-construct

Attempt to insert node into the DOM, choosing from various positioning options. Returns the first argument resolved to a DOM node.

Returns: DOMNode | undefined

Returned values is the first argument resolved to a DOM node.

.place() is also a method of dojo/NodeList, allowing dojo/query node lookups.

require(["dojo/dom-construct"], function(domConstruct){
    domConstruct.place("someNode", "anotherNode");
});

require(["dojo/dom-construct"], function(domConstruct){
    domConstruct.place("someNode", "anotherNode", "before");
});

require(["dojo/dom-construct", "dojo/_base/window"
], function(domConstruct, win){
    domConstruct.place("<div></div>", win.body());
});

require(["dojo/dom-construct"], function(domConstruct){
    domConstruct.place("<li></li>", "someUl", "first");
});

platformRequire(modMap)

Defined by dojo/_base/loader

require one or more modules based on which host environment Dojo is currently operating in

This method takes a "map" of arrays which one can use to optionally load dojo modules. The map is indexed by the possible dojo.name values, with two additional values: "default" and "common". The items in the "default" array will be loaded if none of the other items have been chosen based on dojo.name, set by your host environment. The items in the "common" array will always be loaded, regardless of which list is chosen.

dojo.platformRequire({
    browser: [
        "foo.sample", // simple module
        "foo.test",
        ["foo.bar.baz", true] // skip object check in _loadModule (dojo.require)
    ],
    default: [ "foo.sample._base" ],
    common: [ "important.module.common" ]
});

popContext()

Defined by dojo/_base/configFirefoxExtension

If the context stack contains elements, ensure that subsequent code executes in the previous context to the current context. The current context set ([global, document]) is returned.

position(node,includeScroll)

Defined by dojo/dom-geometry

Gets the position and size of the passed element relative to the viewport (if includeScroll==false), or relative to the document root (if includeScroll==true).

Returns an object of the form: { x: 100, y: 300, w: 20, h: 15 }. If includeScroll==true, the x and y values will include any document offsets that may affect the position relative to the viewport. Uses the border-box model (inclusive of border and padding but not margin). Does not act as a setter.

Returns: Object | object

prop(node,name,value)

Defined by dojo/_base/html

Gets or sets a property on an HTML element.

Handles normalized getting and setting of properties on DOM Nodes. If 2 arguments are passed, and a the second argument is a string, acts as a getter.

If a third argument is passed, or if the second argument is a map of attributes, acts as a setter.

When passing functions as values, note that they will not be directly assigned to slots on the node, but rather the default behavior will be removed and the new behavior will be added using dojo.connect(), meaning that event handler properties will be normalized and that some caveats with regards to non-standard behaviors for onsubmit apply. Namely that you should cancel form submission using dojo.stopEvent() on the passed event object instead of returning a boolean value from the handler itself.

Returns: any

when used as a getter, the value of the requested property or null if that attribute does not have a specified or default value;

when used as a setter, the DOM node

// get the current value of the "foo" property on a node
dojo.prop(dojo.byId("nodeId"), "foo");
// or we can just pass the id:
dojo.prop("nodeId", "foo");

// use prop() to set the tab index
dojo.prop("nodeId", "tabIndex", 3);

dojo.prop("formId", {
    "foo": "bar",
    "tabIndex": -1,
    "method": "POST",
    "onsubmit": function(e){
        // stop submitting the form. Note that the IE behavior
        // of returning true or false will have no effect here
        // since our handler is connect()ed to the built-in
        // onsubmit behavior and so we need to use
        // dojo.stopEvent() to ensure that the submission
        // doesn't proceed.
        dojo.stopEvent(e);

        // submit the form with Ajax
        dojo.xhrPost({ form: "formId" });
    }
});

dojo.prop("someNode",{
    id:"bar",
    style:{
        width:"200px", height:"100px", color:"#000"
    }
});

var obj = { color:"#fff", backgroundColor:"#000" };
dojo.prop("someNode", "style", obj);

// though shorter to use `dojo.style()` in this case:
dojo.style("someNode", obj);

provide(mid)

Defined by dojo/_base/loader

pushContext(g,d)

Defined by dojo/_base/configFirefoxExtension

causes subsequent calls to Dojo methods to assume the passed object and, optionally, document as the default scopes to use. A 2-element array of the previous global and document are returned.

dojo.pushContext treats contexts as a stack. The auto-detected contexts which are initially provided using dojo.setContext() require authors to keep state in order to "return" to a previous context, whereas the dojo.pushContext and dojo.popContext methods provide a more natural way to augment blocks of code to ensure that they execute in a different window or frame without issue. If called without any arguments, the default context (the context when Dojo is first loaded) is instead pushed into the stack. If only a single string is passed, a node in the intitial context's document is looked up and its contextWindow and contextDocument properties are used as the context to push. This means that iframes can be given an ID and code can be executed in the scope of the iframe's document in subsequent calls easily.

queryToObject(str)

Defined by dojo/io-query

Create an object representing a de-serialized query section of a URL. Query keys with multiple values are returned in an array.

Returns: object

"foo=bar&foo=baz&thinger=%20spaces%20=blah&zonk=blarg&"

{
    foo: [ "bar", "baz" ],
    thinger: " spaces =blah",
    zonk: "blarg"
}

rawXhrPost(args)

Defined by dojo/_base/xhr

Sends an HTTP POST request to the server. In addition to the properties listed for the dojo.__XhrArgs type, the following property is allowed:

Returns: undefined

rawXhrPut(args)

Defined by dojo/_base/xhr

Sends an HTTP PUT request to the server. In addition to the properties listed for the dojo.__XhrArgs type, the following property is allowed:

Returns: undefined

ready(priority,context,callback)

Defined by dojo/ready

Add a function to execute on DOM content loaded and all requested modules have arrived and been evaluated. In most cases, the domReady plug-in should suffice and this method should not be needed.

When called in a non-browser environment, just checks that all requested modules have arrived and been evaluated.

require(["dojo/ready"], function(ready){
    ready(function(){ alert("Dom ready!"); });
});

require(["dojo/ready"], function(ready){
    ready(2, function(){ alert("low priority ready!"); })
});

require(["dojo/ready"], function(ready){
    ready(foo, function(){
        // in here, this == foo
    });
});

require(["dojo/ready"], function(ready){
    var foo = { dojoReady: function(){ console.warn(this, "dojo dom and modules ready."); } };
    ready(foo, "dojoReady");
});

registerModulePath(moduleName,prefix)

Defined by dojo/_base/loader

Maps a module name to a path

An unregistered module is given the default path of ../[module], relative to Dojo root. For example, module acme is mapped to ../acme. If you want to use a different module name, use dojo.registerModulePath.

/myapp/js/dojo/dojo/dojo.js

/myapp/js/foo/bar.js
/myapp/js/foo/baz.js
/myapp/js/foo/thud/xyzzy.js

dojo.registerModulePath("foo", "../../foo");

<script type="text/javascript"
    src="/myapp/js/dojo/dojo/dojo.js"></script>
<script type="text/javascript">
    dojo.registerModulePath("foo", "../../foo");
    dojo.require("foo.bar");
    dojo.require("foo.baz");
    dojo.require("foo.thud.xyzzy");
</script>

removeAttr(node,name)

Defined by dojo/dom-attr

Removes an attribute from an HTML element.

removeClass(node,classStr)

Defined by dojo/dom-class

Removes the specified classes from node. No contains() check is required.

require(["dojo/dom-class"], function(domClass){
    domClass.remove("someNode", "firstClass");
});

require(["dojo/dom-class"], function(domClass){
    domClass.remove("someNode", "firstClass secondClass");
});

require(["dojo/dom-class"], function(domClass){
    domClass.remove("someNode", ["firstClass", "secondClass"]);
});

require(["dojo/dom-class"], function(domClass){
    domClass.remove("someNode");
});

require(["dojo/query"], function(query){
    query("ul > li").removeClass("foo");
});

replaceClass(node,addClassStr,removeClassStr)

Defined by dojo/dom-class

Replaces one or more classes on a node if not present. Operates more quickly than calling dojo.removeClass and dojo.addClass

require(["dojo/dom-class"], function(domClass){
    domClass.replace("someNode", "add1 add2", "remove1 remove2");
});

require(["dojo/dom-class"], function(domClass){
    domClass.replace("someNode", "addMe");
});

require(["dojo/query"], function(query){
    query(".findMe").replaceClass("addMe", "removeMe");
});

require(moduleName,omitModuleCheck)

Defined by dojo/_base/loader

loads a Javascript module from the appropriate URI

Modules are loaded via dojo.require by using one of two loaders: the normal loader and the xdomain loader. The xdomain loader is used when dojo was built with a custom build that specified loader=xdomain and the module lives on a modulePath that is a whole URL, with protocol and a domain. The versions of Dojo that are on the Google and AOL CDNs use the xdomain loader.

If the module is loaded via the xdomain loader, it is an asynchronous load, since the module is added via a dynamically created script tag. This means that dojo.require() can return before the module has loaded. However, this should only happen in the case where you do dojo.require calls in the top-level HTML page, or if you purposely avoid the loader checking for dojo.require dependencies in your module by using a syntax like dojo["require"] to load the module.

Sometimes it is useful to not have the loader detect the dojo.require calls in the module so that you can dynamically load the modules as a result of an action on the page, instead of right at module load time.

Also, for script blocks in an HTML page, the loader does not pre-process them, so it does not know to download the modules before the dojo.require calls occur.

So, in those two cases, when you want on-the-fly module loading or for script blocks in the HTML page, special care must be taken if the dojo.required code is loaded asynchronously. To make sure you can execute code that depends on the dojo.required modules, be sure to add the code that depends on the modules in a dojo.addOnLoad() callback. dojo.addOnLoad waits for all outstanding modules to finish loading before executing.

This type of syntax works with both xdomain and normal loaders, so it is good practice to always use this idiom for on-the-fly code loading and in HTML script blocks. If at some point you change loaders and where the code is loaded from, it will all still work.

More on how dojo.require dojo.require("A.B") first checks to see if symbol A.B is defined. If it is, it is simply returned (nothing to do).

If it is not defined, it will look for A/B.js in the script root directory.

dojo.require throws an exception if it cannot find a file to load, or if the symbol A.B is not defined after loading.

It returns the object A.B, but note the caveats above about on-the-fly loading and HTML script blocks when the xdomain loader is loading a module.

dojo.require() does nothing about importing symbols into the current namespace. It is presumed that the caller will take care of that.

Returns: any

the required namespace object

dojo.require("foo");
dojo.require("bar");
dojo.addOnLoad(function(){
    //you can now safely do something with foo and bar
});

with (dojo.require("A.B")) {
    ...
}

var B = dojo.require("A.B");
...

requireAfterIf(condition,moduleName,omitModuleCheck)

Defined by dojo/_base/loader

If the condition is true then call dojo.require() for the specified resource

dojo.requireIf(dojo.isBrowser, "my.special.Module");

requireIf(condition,moduleName,omitModuleCheck)

Defined by dojo/_base/loader

If the condition is true then call dojo.require() for the specified resource

dojo.requireIf(dojo.isBrowser, "my.special.Module");

requireLocalization(moduleName,bundleName,locale)

Defined by dojo/_base/loader

safeMixin(target,source)

Defined by dojo/_base/declare

Mix in properties skipping a constructor and decorating functions like it is done by declare().

This function is used to mix in properties like lang.mixin does, but it skips a constructor property and decorates functions like declare() does.

It is meant to be used with classes and objects produced with declare. Functions mixed in with dojo.safeMixin can use this.inherited() like normal methods.

This function is used to implement extend() method of a constructor produced with declare().

Returns: Object

Target object to accept new properties.

var A = declare(null, {
    m1: function(){
        console.log("A.m1");
    },
    m2: function(){
        console.log("A.m2");
    }
});
var B = declare(A, {
    m1: function(){
        this.inherited(arguments);
        console.log("B.m1");
    }
});
B.extend({
    m2: function(){
        this.inherited(arguments);
        console.log("B.m2");
    }
});
var x = new B();
dojo.safeMixin(x, {
    m1: function(){
        this.inherited(arguments);
        console.log("X.m1");
    },
    m2: function(){
        this.inherited(arguments);
        console.log("X.m2");
    }
});
x.m2();
// prints:
// A.m1
// B.m1
// X.m1

setAttr(node,name,value)

Defined by dojo/dom-attr

Sets an attribute on an HTML element.

Handles normalized setting of attributes on DOM Nodes.

When passing functions as values, note that they will not be directly assigned to slots on the node, but rather the default behavior will be removed and the new behavior will be added using dojo.connect(), meaning that event handler properties will be normalized and that some caveats with regards to non-standard behaviors for onsubmit apply. Namely that you should cancel form submission using dojo.stopEvent() on the passed event object instead of returning a boolean value from the handler itself.

Returns: any | undefined

the DOM node

// use attr() to set the tab index
require(["dojo/dom-attr"], function(domAttr){
    domAttr.set("nodeId", "tabIndex", 3);
});

require(["dojo/dom-attr"],
function(domAttr){
    domAttr.set("formId", {
        "foo": "bar",
        "tabIndex": -1,
        "method": "POST"
    }
});

setContentSize(node,box,computedStyle)

Defined by dojo/dom-geometry

Sets the size of the node's contents, irrespective of margins, padding, or borders.

setContext(globalObject,globalDocument)

Defined by dojo/_base/window

changes the behavior of many core Dojo functions that deal with namespace and DOM lookup, changing them to work in a new global context (e.g., an iframe). The varibles dojo.global and dojo.doc are modified as a result of calling this function and the result of dojo.body() likewise differs.

setMarginBox(node,box,computedStyle)

Defined by dojo/dom-geometry

sets the size of the node's margin box and placement (left/top), irrespective of box model. Think of it as a passthrough to setBox that handles box-model vagaries for you.

setProp(node,name,value)

Defined by dojo/dom-prop

Sets a property on an HTML element.

Handles normalized setting of properties on DOM nodes.

When passing functions as values, note that they will not be directly assigned to slots on the node, but rather the default behavior will be removed and the new behavior will be added using dojo.connect(), meaning that event handler properties will be normalized and that some caveats with regards to non-standard behaviors for onsubmit apply. Namely that you should cancel form submission using dojo.stopEvent() on the passed event object instead of returning a boolean value from the handler itself.

Returns: any | undefined

the DOM node

// use prop() to set the tab index
require(["dojo/dom-prop"], function(domProp){
    domProp.set("nodeId", "tabIndex", 3);
});

require(["dojo/dom-prop"], function(domProp){
    domProp.set("formId", {
        "foo": "bar",
        "tabIndex": -1,
        "method": "POST",
    });
});

setSelectable(node,selectable)

Defined by dojo/dom

setStyle(node,name,value)

Defined by dojo/dom-style

Sets styles on a node.

Returns: String | undefined

If passed, sets value on the node for style, handling cross-browser concerns. When setting a pixel value, be sure to include "px" in the value. For instance, top: "200px". Otherwise, in some cases, some browsers will not apply the style.

require(["dojo/dom-style"], function(domStyle){
    domStyle.set("thinger", "opacity", 0.5); // == 0.5
});

require(["dojo/dom-style"], function(domStyle){
    domStyle.set("thinger", {
        "opacity": 0.5,
        "border": "3px solid black",
        "height": "300px"
    });
});

require(["dojo/dom-style", "dojo/dom"], function(domStyle, dom){
    domStyle.set("thinger",{
        fontSize:"14pt",
        letterSpacing:"1.2em"
    });
});

require(["dojo/dom-style", "dojo/query", "dojo/NodeList-dom"],
function(domStyle, query){
    query(".someClassName").style("visibility","hidden");
    // or
    query("#baz > div").style({
        opacity:0.75,
        fontSize:"13pt"
    });
});

some(arr,callback,thisObject)

Defined by dojo/_base/array

Determines whether or not any item in arr satisfies the condition implemented by callback.

This function corresponds to the JavaScript 1.6 Array.some() method, with one difference: when run over sparse arrays, this implementation passes the "holes" in the sparse array to the callback function with a value of undefined. JavaScript 1.6's some skips the holes in the sparse array. For more details, see: https://developer.mozilla.org/en/Core_JavaScript_1.5_Reference/Objects/Array/some

Returns: Boolean

// is true
array.some([1, 2, 3, 4], function(item){ return item>1; });

// is false
array.some([1, 2, 3, 4], function(item){ return item<1; });

Stateful()

Defined by dojo/Stateful

stopEvent(evt)

Defined by dojo/_base/event

prevents propagation and clobbers the default action of the passed event

style(node,name,value)

Defined by dojo/_base/html

Accesses styles on a node. If 2 arguments are passed, acts as a getter. If 3 arguments are passed, acts as a setter.

Getting the style value uses the computed style for the node, so the value will be a calculated value, not just the immediate node.style value. Also when getting values, use specific style names, like "borderBottomWidth" instead of "border" since compound values like "border" are not necessarily reflected as expected. If you want to get node dimensions, use dojo.marginBox(), dojo.contentBox() or dojo.position().

Returns: any | undefined

when used as a getter, return the computed style of the node if passing in an ID or node, or return the normalized, computed value for the property when passing in a node and a style property

dojo.style("thinger");

dojo.style("thinger", "opacity"); // 1 by default

dojo.style("thinger", "opacity", 0.5); // == 0.5

dojo.style("thinger", {
    "opacity": 0.5,
    "border": "3px solid black",
    "height": "300px"
});

dojo.style("thinger",{
    fontSize:"14pt",
    letterSpacing:"1.2em"
});

dojo.query(".someClassName").style("visibility","hidden");
// or
dojo.query("#baz > div").style({
    opacity:0.75,
    fontSize:"13pt"
});

toDom(frag,doc)

Defined by dojo/dom-construct

instantiates an HTML fragment returning the corresponding DOM.

Returns: any | undefined

Document fragment, unless it's a single node in which case it returns the node itself

require(["dojo/dom-construct"], function(domConstruct){
    var tr = domConstruct.toDom("<tr><td>First!</td></tr>");
});

toggleClass(node,classStr,condition)

Defined by dojo/dom-class

Adds a class to node if not present, or removes if present. Pass a boolean condition if you want to explicitly add or remove. Returns the condition that was specified directly or indirectly.

Returns: Boolean

If passed, true means to add the class, false means to remove. Otherwise dojo.hasClass(node, classStr) is used to detect the class presence.

require(["dojo/dom-class"], function(domClass){
    domClass.toggle("someNode", "hovered");
});

require(["dojo/dom-class"], function(domClass){
    domClass.toggle("someNode", "hovered", true);
});

require(["dojo/query"], function(query){
    query(".toggleMe").toggleClass("toggleMe");
});

toJson(it,prettyPrint)

Defined by dojo/_base/json

Returns a JSON serialization of an object.

Returns a JSON serialization of an object. Note that this doesn't check for infinite recursion, so don't do that! It is recommend that you use dojo/json's stringify function for an lighter and faster implementation that matches the native JSON API and uses the native JSON serializer when available.

Returns: any | undefined

A JSON string serialization of the passed-in object.

var jsonStr = dojo.toJson({ howdy: "stranger!", isStrange: true });
doh.is('{"howdy":"stranger!","isStrange":true}', jsonStr);

dojo.declare("Furby", null, {
    furbies: "are strange",
    furbyCount: 10,
    __json__: function(){
    },
});

toPixelValue(node,value)

Defined by dojo/dom-style

converts style value to pixels on IE or return a numeric value.

Returns: Number

unsubscribe(handle)

Defined by dojo/_base/connect

Remove a topic listener.

var alerter = dojo.subscribe("alerts", null, function(caption, message){ alert(caption + "\n" + message); };
...
dojo.unsubscribe(alerter);

when(valueOrPromise,callback,errback,progback)

Defined by dojo/when

Transparently applies callbacks to values and/or promises.

Accepts promises but also transparently handles non-promises. If no callbacks are provided returns a promise, regardless of the initial value. Foreign promises are converted.

If callbacks are provided and the initial value is not a promise, the callback is executed immediately with no error handling. Returns a promise if the initial value is a promise, or the result of the callback otherwise.

Returns: dojo/promise/Promise | summary: | name:

Promise, or if a callback is provided, the result of the callback.

windowUnloaded()

Defined by dojo/_base/configFirefoxExtension

signal fired by impending window destruction. You may use dojo.addOnWIndowUnload() or dojo.connect() to this method to perform page/application cleanup methods. See dojo.addOnWindowUnload for more info.

withDoc(documentObject,callback,thisObject,cbArguments)

Defined by dojo/_base/window

Invoke callback with documentObject as dojo/_base/window::doc.

Invoke callback with documentObject as dojo/_base/window::doc. If provided, callback will be executed in the context of object thisObject When callback() returns or throws an error, the dojo/_base/window::doc will be restored to its previous state.

Returns: undefined

withGlobal(globalObject,callback,thisObject,cbArguments)

Defined by dojo/_base/window

Invoke callback with globalObject as dojo.global and globalObject.document as dojo.doc.

Invoke callback with globalObject as dojo.global and globalObject.document as dojo.doc. If provided, globalObject will be executed in the context of object thisObject When callback() returns or throws an error, the dojo.global and dojo.doc will be restored to its previous state.

Returns: undefined

xhr(method,args)

Defined by dojox/rpc/Client

Returns: undefined

xhrDelete(args)

Defined by dojo/_base/xhr

Sends an HTTP DELETE request to the server.

Returns: undefined

xhrGet(args)

Defined by dojo/_base/xhr

Sends an HTTP GET request to the server.

Returns: undefined

xhrPost(args)

Defined by dojo/_base/xhr

Sends an HTTP POST request to the server. In addition to the properties listed for the dojo.__XhrArgs type, the following property is allowed:

Returns: undefined

xhrPut(args)

Defined by dojo/_base/xhr

Sends an HTTP PUT request to the server. In addition to the properties listed for the dojo.__XhrArgs type, the following property is allowed:

Returns: undefined