dojo/_base/kernel

Summary

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

See the dojo/_base/kernel reference documentation for more information.

Properties

back

Defined by: dojo/back

Browser history management resources

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

This module defines the user configuration during bootstrap.

connectPublisher

Defined by: dojo/robotx

contentHandlers

Defined by: dojo/_base/xhr

A map of available XHR transport handle types. Name matches the handleAs attribute passed to XHR calls.

currency

Defined by: dojo/currency

localized formatting and parsing routines for currencies

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

Alias for the current document. 'doc' can be modified for temporary context shifting. See also withDoc().

dojox

Defined by: dojo/_base/kernel

fx

Defined by: dojo/fx

Effects library on top of Base animations

gears

Defined by: dojo/gears

TODOC

global

Defined by: dojo/_base/window

Alias for the current window. 'global' can be modified for temporary context shifting. See also withGlobal().

html

Defined by: dojo/html

TODOC

i18n

Defined by: dojo/i18n

This module implements the dojo/i18n! plugin and the v1.6- i18n API

io

Defined by: dojo/io/iframe

isAir

Defined by: dojo/_base/sniff

True if client is Adobe Air

isAndroid

Defined by: dojo/_base/sniff

Version as a Number if client is android browser. undefined otherwise.

isAsync

Defined by: dojo/_base/kernel

isBrowser

Defined by: dojo/_base/configFirefoxExtension

isChrome

Defined by: dojo/_base/sniff

Version as a Number if client is Chrome browser. undefined otherwise.

isCopyKey

Defined by: dojox/grid/_Grid

isFF

Defined by: dojo/_base/configFirefoxExtension

isIE

Defined by: dojo/_base/sniff

Version as a Number if client is MSIE(PC). undefined otherwise. Corresponds to major detected IE version (6, 7, 8, etc.)

isIos

Defined by: dojo/_base/sniff

Version as a Number if client is iPhone, iPod, or iPad. undefined otherwise.

isKhtml

Defined by: dojo/_base/sniff

Version as a Number if client is a KHTML browser. undefined otherwise. Corresponds to major detected version.

isMac

Defined by: dojo/_base/sniff

True if the client runs on Mac

isMoz

Defined by: dojo/_base/configFirefoxExtension

isMozilla

Defined by: dojo/_base/configFirefoxExtension

isOpera

Defined by: dojo/_base/sniff

Version as a Number if client is Opera. undefined otherwise. Corresponds to major detected version.

isQuirks

Defined by: dojo/_base/configFirefoxExtension

isSafari

Defined by: dojo/_base/sniff

Version as a Number if client is Safari or iPhone. undefined otherwise.

isSpidermonkey

Defined by: dojo/_base/configSpidermonkey

isWebKit

Defined by: dojo/_base/sniff

Version as a Number if client is a WebKit-derived browser (Konqueror, Safari, Chrome, etc.). undefined otherwise.

isWii

Defined by: dojo/_base/sniff

True if client is Wii

keys

Defined by: dojo/keys

Definitions for common key values. Client code should test keyCode against these named constants, as the actual codes can vary by browser.

locale

Defined by: dojo/_base/configFirefoxExtension

mouseButtons

Defined by: dojo/mouse

number

Defined by: dojo/number

localized formatting and parsing routines for Number

parser

Defined by: dojox/mobile/parser

publish

Defined by: dojo/robotx

query

Defined by: dojo/query

regexp

Defined by: dojo/regexp

Regular expressions and Builder resources

rpc

Defined by: dojo/rpc/RpcService

scopeMap

Defined by: dojo/_base/kernel

store

Defined by: dojo/store/Cache

string

Defined by: dojo/string

String utilities for Dojo

subscribe

Defined by: dojo/robotx

tests

Defined by: dojo/tests

D.O.H. Test files for Dojo unit testing.

toJsonIndentStr

Defined by: dojo/_base/json

touch

Defined by: dojo/touch

This module provides unified touch event handlers by exporting press, move, release and cancel which can also run well on desktop. Based on http://dvcs.w3.org/hg/webevents/raw-file/tip/touchevents.html Also, if the dojoClick property is set to truthy on a DOM node, dojo/touch generates click events immediately for this node and its descendants (except for descendants that have a dojoClick property set to falsy), to avoid the delay before native browser click events, and regardless of whether evt.preventDefault() was called in a touch.press event listener.

version

Defined by: dojo/_base/kernel

Version number of the Dojo Toolkit

window

Defined by: dojo/window

TODOC

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.

Parameter Type Description
returnWrappers Boolean
Optional

Examples

Example 1

// 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.

Parameter Type Description
node String | DOMNode

String ID or DomNode reference to add a class string too

classStr String | Array

A String class name to add, or several space-separated class names, or an array of class names.

Examples

Example 1

Add a class to some node:

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

Example 2

Add two classes at once:

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

Example 3

Add two classes at once (using array):

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

Example 4

Available in dojo/NodeList for multiple additions

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.

Parameter Type Description
priority Integer
Optional

The order in which to exec this callback relative to other callbacks, defaults to 1000

context undefined

The context in which to run execute callback, or a callback if not using context

callback Function
Optional

The function to execute.

Examples

Example 1

Simple DOM and Modules ready syntax

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

Example 2

Using a priority

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

Example 3

Using context

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

Example 4

Using dojo/hitch style args:

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.

Parameter Type Description
obj Object? | Function
Optional
functionName String | Function
Optional

Examples

Example 1

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.

Parameter Type Description
obj Object
Optional
functionName String | Function
Optional

Examples

Example 1

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.

Parameter Type Description
node DOMNode | String

a DOM node or the id of a node to animate CSS properties on

properties Object
duration Integer
Optional

The number of milliseconds over which the animation should run. Defaults to the global animation default duration (350ms).

easing Function
Optional

An easing function over which to calculate acceleration and deceleration of the animation through its duration. A default easing algorithm is provided, but you may plug in any you wish. A large selection of easing algorithms are available in dojo/fx/easing.

onEnd Function
Optional

A function to be called when the animation finishes running.

delay Integer
Optional

The number of milliseconds to delay beginning the animation by. The default is 0.

Returns: undefined

Examples

Example 1

Fade out a node

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

Example 2

Fade out a node over a full second

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.

Parameter Type Description
args Object

An object with the following properties:

  • properties (Object, optional):

    A hash map of style properties to Objects describing the transition, such as the properties of _Line with an additional 'units' property

  • node (DOMNode|String):

    The node referenced in the animation

  • duration (Integer, optional):

    Duration of the animation in milliseconds.

  • easing (Function, optional):

    An easing function.

Returns: instance

Examples

Example 1

A simple animation that changes the width of the specified node.

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

Dojo figures out the start value for the width and converts the

integer specified for the width to the more expressive but verbose form { width: { end: '400', units: 'px' } } which you can also specify directly. Defaults to 'px' if omitted.

Example 2

Animate width, height, and padding over 2 seconds... the pedantic way:

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();

Note 'paddingTop' is used over 'padding-top'. Multi-name CSS properties

are written using "mixed case", as the hyphen is illegal as an object key.

Example 3

Plug in a different easing function and register a callback for when the animation ends. Easing functions accept values between zero and one and return a value on that basis. In this case, an exponential-in curve.

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

Example 4

Like all Animations, animateProperty returns a handle to the Animation instance, which fires the events common to Dojo FX. Use aspect.after to access these events outside of the Animation definition:

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();

Example 5

Each property can be a function whose return value is substituted along. Additionally, each measurement (eg: start, end) can be a function. The node reference is passed directly to callbacks.

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.

Parameter Type Description
args Object

The 'magic argument', mixing all the properties into this animation instance.

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.

Parameter Type Description
node DOMNode | String

id or reference to the element to get or set the attribute on

name String | Object

the name of the attribute to get or set.

value String
Optional

The value to set for the attribute

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

Examples

Example 1

// 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");

Example 2

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

Example 3

Set multiple values at once, including event handlers:

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" });
    }
});

Example 4

Style is s special case: Only set with an object hash of styles

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

Example 5

Again, only set style as an object hash of styles:

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

Parameter Type Description
start dojo/_base/Color
end dojo/_base/Color
weight Number
obj dojo/_base/Color
Optional

Returns: undefined

body(doc)

Defined by dojo/_base/window

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

Parameter Type Description
doc Document
Optional

Returns: undefined

Examples

Example 1

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.

Parameter Type Description
id String | DOMNode

A string to match an HTML id attribute or a reference to a DOM Node

doc Document
Optional

Document to work in. Defaults to the current value of dojo/_base/window.doc. Can be used to retrieve node references from other documents.

Returns: instance

Examples

Example 1

Look up a node by ID:

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

Example 2

Check if a node exists, and use it.

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

Example 3

Allow string or DomNode references to be passed to a custom function:

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.

Parameter Type Description
module String | Object

dojo/cldr/supplemental

url String

The rest of the path to append to the path derived from the module argument. If module is an object, then this second argument should be the "value" argument instead.

value String | Object
Optional

If a String, the value to use in the cache for the module/url combination. If an Object, it can have two properties: value and sanitize. The value property should be the value to use in the cache, and sanitize can be set to true or false, to indicate if XML declarations should be removed from the value and if the HTML inside a body tag in the value should be extracted as the real value. The value argument or the value property on the value argument are usually only used by the build system as it inlines cache content.

Returns: undefined | null

Examples

Example 1

To ask dojo.cache to fetch content and store it in the cache (the dojo["cache"] style of call is used to avoid an issue with the build system erroneously trying to intern this example. To get the build system to intern your dojo.cache calls, use the "dojo.cache" style of call):

//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");

Example 2

To ask dojo.cache to fetch content and store it in the cache, and sanitize the input (the dojo["cache"] style of call is used to avoid an issue with the build system erroneously trying to intern this example. To get the build system to intern your dojo.cache calls, use the "dojo.cache" style of call):

//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});

Example 3

Same example as previous, but demonstrates how an object can be passed in as the first argument, then the value argument can then be the second argument.

//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.

Parameter Type Description
color Array | String | Object

Examples

Example 1

Work with a Color instance:

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

Example 2

Work with a node's color:

  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.

Parameter Type Description
a Array
obj dojo/_base/Color
Optional

Returns: any | undefined

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

Examples

Example 1

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.

Parameter Type Description
color String
obj dojo/_base/Color
Optional

Returns: any

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

Examples

Example 1

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.

Parameter Type Description
color String
obj dojo/_base/Color
Optional

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)"

Parameter Type Description
str String
obj dojo/_base/Color
Optional

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.

Parameter Type Description
obj Object
Optional

The source object for the event function. Defaults to kernel.global if null. If obj is a DOM node, the connection is delegated to the DOM event manager (unless dontFix is true).

event String

String name of the event function in obj. I.e. identifies a property obj[event].

context Object | null

The object that method will receive as "this".

If context is null and method is a function, then method inherits the context of event.

If method is a string then context must be the source object object for method (context[method]). If context is null, kernel.global is used.

method String | Function

A function reference, or name of a function in context. The function identified by method fires after event does. method receives the same arguments as the event. See context argument comments for information on method's scope.

dontFix Boolean
Optional

If obj is a DOM node, set dontFix to true to prevent delegation of this connection to the DOM event manager.

Returns: undefined

Examples

Example 1

When obj.onchange(), do ui.update():

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

Example 2

Using return value for disconnect:

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

Example 3

When onglobalevent executes, watcher.handler is invoked:

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

Example 4

When ob.onCustomEvent executes, customEventHandler is invoked:

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

Example 5

When ob.onCustomEvent executes, customEventHandler is invoked with the same scope (this):

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

Example 6

When globalEvent executes, globalHandler is invoked with the same scope (this):

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.

Parameter Type Description
node DomNode | String

id or reference to DOM Node to get/set box for

box Object
Optional

If passed, denotes that dojo.contentBox() should update/set the content box for node. Box is an object in the above format, but only w (width) and h (height) are supported. All properties are optional if passed.

Returns: undefined

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.

Parameter Type Description
name String

Name of the cookie

value String
Optional

Value for the cookie

props Object
Optional

Properties for the cookie

Returns: undefined

Examples

Example 1

set a cookie with the JSON-serialized contents of an object which will expire 5 days from now:

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

Example 2

de-serialize a cookie back into a JavaScript object:

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

Example 3

delete a cookie:

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().

Parameter Type Description
node DomNode | String
includeScroll Boolean
Optional

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.

Parameter Type Description
tag DOMNode | String

A string of the element to create (eg: "div", "a", "p", "li", "script", "br"), or an existing DOM node to process.

attrs Object

An object-hash of attributes to set on the newly created node. Can be null, if you don't want to set any attributes/styles. See: dojo.setAttr for a description of available attributes.

refNode DOMNode | String
Optional

Optional reference node. Used by dojo.place to place the newly created node somewhere in the dom relative to refNode. Can be a DomNode reference or String ID of a node.

pos String
Optional

Optional positional reference. Defaults to "last" by way of dojo.place, though can be set to "first","after","before","last", "replace" or "only" to further control the placement of the new node relative to the refNode. 'refNode' is required if a 'pos' is specified.

Returns: undefined

Examples

Example 1

Create a DIV:

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

Example 2

Create a DIV with content:

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

Example 3

Place a new DIV in the BODY, with no attributes set

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

Example 4

Create an UL, and populate it with LI's. Place the list as the first-child of a node with id="someId":

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);
    });
});

Example 5

Create an anchor, with an href. Place in BODY:

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.

Parameter Type Description
className String
Optional

The optional name of the constructor (loosely, a "class") stored in the "declaredClass" property in the created prototype. It will be used as a global name for a created constructor.

superclass Function | Function[]

May be null, a Function, or an Array of Functions. This argument specifies a list of bases (the left-most one is the most deepest base).

props Object

An object whose properties are copied to the created prototype. Add an instance-initialization function by making it a property named "constructor".

Returns: dojo/_base/declare.__DeclareCreatedObject | undefined

New constructor function.

Examples

Example 1

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();
    }
});

Example 2

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
    // ...
});

Example 3

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

Example 4

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

Example 5

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]);
        // ...
    }
});

Example 6

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.

Parameter Type Description
canceller Function
Optional

Examples

Example 1

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

Example 2

Deferred objects are often used when making code asynchronous. It may be easiest to write functions in a synchronous manner and then split code using a deferred to trigger a response to a long-lived operation. For example, instead of register a callback function to denote when a rendering operation completes, the function can simply return a 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!!

Example 3

Using a Deferred doesn't simplify the sending code any, but it provides a standard interface for callers and senders alike, providing both with a simple way to service multiple callbacks for an operation and freeing both sides from worrying about details such as "did this get called already?". With Deferreds, new callbacks can be added at any time.

// 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.

Example 4

In this example, renderLotsOfData is synchronous and so both versions are pretty artificial. Putting the data display on a timeout helps show why Deferreds rock:

// 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();
});

Note that the caller doesn't have to change his code at all to handle the asynchronous case.

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

Parameter Type Description
list Array

The list of deferreds to be synchronizied with this DeferredList

fireOnOneCallback Boolean
Optional

Will cause the DeferredLists callback to be fired as soon as any of the deferreds in its list have been fired instead of waiting until the entire list has finished

fireOnOneErrback Boolean
Optional
consumeErrors Boolean
Optional
canceller Function
Optional

A deferred canceller function, see dojo.Deferred

deprecated(behaviour,extra,removal)

Defined by dojo/_base/kernel

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

Parameter Type Description
behaviour String

The API or behavior being deprecated. Usually in the form of "myApp.someFunction()".

extra String
Optional

Text to append to the message. Often provides advice on a new function or facility to achieve the same goal during the deprecation period.

removal String
Optional

Text to indicate when in the future the behavior will be removed. Usually a version number.

Examples

Example 1

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

destroy(node)

Defined by dojo/_base/html

Parameter Type Description
node undefined

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.

Parameter Type Description
handle Handle

the return value of the dojo.connect call that created the connection.

docScroll(doc)

Defined by dojo/dom-geometry

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

Parameter Type Description
doc Document
Optional

Optional document to query. If unspecified, use win.doc.

Returns: Object | undefined

empty(node)

Defined by dojo/_base/html

Parameter Type Description
node undefined

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;")

Parameter Type Description
scriptText undefined

The text to evaluation.

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

Parameter Type Description
arr Array | String

the array to iterate on. If a string, operates on individual characters.

callback Function | String

a function is invoked with three arguments: item, index, and array and returns true if the condition is met.

thisObject Object
Optional

may be used to scope the call to callback

Returns: Boolean

Examples

Example 1

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

Example 2

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

exit(exitcode)

Defined by dojo/_base/configSpidermonkey

Parameter Type Description
exitcode undefined

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.

Parameter Type Description
moduleName String

The name of a module, or the name of a module file or a specific function

extra String
Optional

some additional message for the user

Examples

Example 1

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

Example 2

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.

Parameter Type Description
args Object

An object with the following properties:

  • node (DOMNode|String):

    The node referenced in the animation

  • duration (Integer, optional):

    Duration of the animation in milliseconds.

  • easing (Function, optional):

    An easing function.

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.

Parameter Type Description
args Object

An object with the following properties:

  • node (DOMNode|String):

    The node referenced in the animation

  • duration (Integer, optional):

    Duration of the animation in milliseconds.

  • easing (Function, optional):

    An easing function.

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.

Parameter Type Description
inputNode DOMNode | String

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

Parameter Type Description
arr Array

the array to iterate over.

callback Function | String

a function that is invoked with three arguments (item, index, array). The return of this function is expected to be a boolean which determines whether the passed-in item will be included in the returned array.

thisObject Object
Optional

may be used to scope the call to callback

Returns: Array

Examples

Example 1

// 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

Parameter Type Description
evt Event

native event object

sender DOMNode

node to treat as "currentTarget"

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.

Parameter Type Description
scrollLeft Number
doc Document
Optional

Optional document to query. If unspecified, use win.doc.

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

Parameter Type Description
arr Array | String
callback Function | String
thisObject Object
Optional

Examples

Example 1

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

Example 2

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

Example 3

// 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

Parameter Type Description
formNode DOMNode | String
prettyPrint Boolean
Optional

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.

Parameter Type Description
formNode DOMNode | String

Returns: object

Examples

Example 1

This form:

<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>

yields this object structure as the result of a call to formToObject():

{
    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

Parameter Type Description
formNode DOMNode | String

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.

Parameter Type Description
js String

a string literal of a JavaScript expression, for instance: '{ "foo": [ "bar", 1, { "baz": "thud" } ] }'

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.

Parameter Type Description
node DOMNode | String

id or reference to the element to get the attribute on

name String

the name of the attribute to get.

Returns: any | undefined | null

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

Examples

Example 1

// 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.

Parameter Type Description
node DOMNode
computedStyle Object
Optional

This parameter accepts computed styles object. If this parameter is omitted, the functions will call dojo/dom-style.getComputedStyle to get one. It is a better way, calling dojo/dom-style.getComputedStyle once, and then pass the reference to this computedStyle parameter. Wherever possible, reuse the returned object of dojo/dom-style.getComputedStyle().

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.

Parameter Type Description
node DOMNode

A reference to a DOM node. Does NOT support taking an ID string for speed reasons.

Examples

Example 1

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

Example 2

Reusing the returned object, avoiding multiple lookups:

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.

Parameter Type Description
node DOMNode
computedStyle Object
Optional

This parameter accepts computed styles object. If this parameter is omitted, the functions will call dojo/dom-style.getComputedStyle to get one. It is a better way, calling dojo/dom-style.getComputedStyle once, and then pass the reference to this computedStyle parameter. Wherever possible, reuse the returned object of dojo/dom-style.getComputedStyle().

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.

Parameter Type Description
doc Document
Optional

Optional document to query. If unspecified, use win.doc.

Returns: object

getL10nName(moduleName,bundleName,locale)

Defined by dojo/i18n

Parameter Type Description
moduleName undefined
bundleName undefined
locale undefined

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.

Parameter Type Description
node DOMNode
computedStyle Object
Optional

This parameter accepts computed styles object. If this parameter is omitted, the functions will call dojo/dom-style.getComputedStyle to get one. It is a better way, calling dojo/dom-style.getComputedStyle once, and then pass the reference to this computedStyle parameter. Wherever possible, reuse the returned object of dojo/dom-style.getComputedStyle().

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.

Parameter Type Description
node DOMNode
computedStyle Object
Optional

This parameter accepts computed styles object. If this parameter is omitted, the functions will call dojo/dom-style.getComputedStyle to get one. It is a better way, calling dojo/dom-style.getComputedStyle once, and then pass the reference to this computedStyle parameter. Wherever possible, reuse the returned object of dojo/dom-style.getComputedStyle().

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

Parameter Type Description
node DOMNode | String
computedStyle Object
Optional

This parameter accepts computed styles object. If this parameter is omitted, the functions will call dojo/dom-style.getComputedStyle to get one. It is a better way, calling dojo/dom-style.getComputedStyle once, and then pass the reference to this computedStyle parameter. Wherever possible, reuse the returned object of dojo/dom-style.getComputedStyle().

Returns: object

getNodeProp(node,name)

Defined by dojo/dom-attr

Returns an effective value of a property or an attribute.

Parameter Type Description
node DOMNode | String

id or reference to the element to remove the attribute from

name String

the name of the 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.

Parameter Type Description
node DOMNode
computedStyle Object
Optional

This parameter accepts computed styles object. If this parameter is omitted, the functions will call dojo/dom-style.getComputedStyle to get one. It is a better way, calling dojo/dom-style.getComputedStyle once, and then pass the reference to this computedStyle parameter. Wherever possible, reuse the returned object of dojo/dom-style.getComputedStyle().

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.

Parameter Type Description
node DOMNode
computedStyle Object
Optional

This parameter accepts computed styles object. If this parameter is omitted, the functions will call dojo/dom-style.getComputedStyle to get one. It is a better way, calling dojo/dom-style.getComputedStyle once, and then pass the reference to this computedStyle parameter. Wherever possible, reuse the returned object of dojo/dom-style.getComputedStyle().

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.

Parameter Type Description
node DOMNode | String

id or reference to the element to get the property on

name String

the name of the property to get.

Returns: any | undefined

the value of the requested property or its default value

Examples

Example 1

// 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().

Parameter Type Description
node DOMNode | String

id or reference to node to get style for

name String
Optional

the style property to get

Returns: undefined

Examples

Example 1

Passing only an ID or node returns the computed style object of the node:

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

Example 2

Passing a node and a style property returns the current normalized, computed value for that property:

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.

Parameter Type Description
node DOMNode | String

id or reference to the element to check

name String

the name of the attribute

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.

Parameter Type Description
node String | DOMNode

String ID or DomNode reference to check the class for.

classStr String

A string class name to look for.

Returns: boolean

Examples

Example 1

Do something if a node with id="someNode" has class="aSillyClassName" present

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.
Parameter Type Description
hash String
Optional

the hash is set - #string.

replace Boolean
Optional

If true, updates the hash value in the current history state instead of creating a new history state.

Returns: any | undefined

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

Examples

Example 1

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

Parameter Type Description
arr Array
value Object
fromIndex Integer
Optional
findLast Boolean
Optional

Makes indexOf() work like lastIndexOf(). Used internally; not meant for external usage.

Returns: Number

isBodyLtr(doc)

Defined by dojo/dom-geometry

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

Parameter Type Description
doc Document
Optional

Optional document to query. If unspecified, use win.doc.

Returns: Boolean | boolean

isDescendant(node,ancestor)

Defined by dojo/dom

Returns true if node is a descendant of ancestor

Parameter Type Description
node DOMNode | String

string id or node reference to test

ancestor DOMNode | String

string id or node reference of potential parent to test against

Returns: boolean

Examples

Example 1

Test is node id="bar" is a descendant of node id="foo"

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

Parameter Type Description
arr undefined
value undefined
fromIndex Integer
Optional

Returns: Number

loadInit(f)

Defined by dojo/_base/loader

Parameter Type Description
f undefined

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

Parameter Type Description
arr Array | String

the array to iterate on. If a string, operates on individual characters.

callback Function | String

a function is invoked with three arguments, (item, index, array), and returns a value

thisObject Object
Optional

may be used to scope the call to callback

Ctr undefined

Returns: Array | instance

Examples

Example 1

// 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.

Parameter Type Description
node DomNode | String

id or reference to DOM Node to get/set box for

box Object
Optional

If passed, denotes that dojo.marginBox() should update/set the margin box for node. Box is an object in the above format. All properties are optional if passed.

Returns: undefined

Examples

Example 1

Retrieve the margin box of a passed node

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

Example 2

Set a node's margin box to the size of another node

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

moduleUrl(module,url)

Defined by dojo/_base/kernel

Returns a URL relative to a module.

Parameter Type Description
module String

dojo/dom-class

url String
Optional

Returns: string

Examples

Example 1

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);

Example 2

you may de-reference as far as you like down the package hierarchy. This is sometimes handy to avoid lengthy relative urls or for building portable sub-packages. In this example, the acme.widget and acme.util directories may be located under different roots (see dojo.registerModulePath) but the the modules which reference them can be unaware of their relative locations on the filesystem:

// 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.

Parameter Type Description
array undefined

Returns: Array

Examples

Example 1

create a node list from a node

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

Example 2

get a NodeList from a CSS query and iterate on it

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

Example 3

use native and Dojo-provided array methods to manipulate a NodeList without needing to use dojo.* functions explicitly:

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
});

Example 4

chainability is a key advantage of NodeLists:

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.

Parameter Type Description
map Object

Returns: undefined

Examples

Example 1

this object:

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

yields the following query string:

"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.

Parameter Type Description
node DOMNode | DocumentFragment | String

id or node reference, or HTML fragment starting with "<" to place relative to refNode

refNode DOMNode | String

id or node reference to use as basis for placement

position String | Number
Optional

string noting the position of node relative to refNode or a number indicating the location in the childNodes collection of refNode. Accepted string values are:

  • before
  • after
  • replace
  • only
  • first
  • last

"first" and "last" indicate positions as children of refNode, "replace" replaces refNode, "only" replaces all children. position defaults to "last" if not specified

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.

Examples

Example 1

Place a node by string id as the last child of another node by string id:

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

Example 2

Place a node by string id before another node by string id

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

Example 3

Create a Node, and place it in the body element (last child):

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

Example 4

Put a new LI as the first child of a list by id:

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.

Parameter Type Description
modMap Object

Examples

Example 1

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.

Parameter Type Description
node DOMNode | String
includeScroll Boolean
Optional

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.

Parameter Type Description
node DomNode | String

id or reference to the element to get or set the property on

name String | Object

the name of the property to get or set.

value String
Optional

The value to set for the property

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

Examples

Example 1

// 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");

Example 2

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

Example 3

Set multiple values at once, including event handlers:

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" });
    }
});

Example 4

Style is s special case: Only set with an object hash of styles

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

Example 5

Again, only set style as an object hash of styles:

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

Parameter Type Description
mid undefined

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.

Parameter Type Description
g Object | String
Optional

The global context. If a string, the id of the frame to search for a context and document.

d MDocumentElement
Optional

The document element to execute subsequent code with.

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.

Parameter Type Description
str String

Returns: object

Examples

Example 1

This string:

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

results in this object structure:

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

Note that spaces and other urlencoded entities are correctly handled.

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:

Parameter Type Description
args Object

An object with the following properties:

  • handleAs (String, optional):

    Acceptable values are: text (default), json, json-comment-optional, json-comment-filtered, javascript, xml. See dojo/_base/xhr.contentHandlers

  • sync (Boolean, optional):

    false is default. Indicates whether the request should be a synchronous (blocking) request.

  • headers (Object, optional):

    Additional HTTP headers to send in the request.

  • failOk (Boolean, optional):

    false is default. Indicates whether a request should be allowed to fail (and therefore no console error message in the event of a failure)

  • contentType (String|Boolean):

    "application/x-www-form-urlencoded" is default. Set to false to prevent a Content-Type header from being sent, or to a string to send a different Content-Type.

  • load:

    This function will be called on a successful HTTP response code.

  • error:

    This function will be called when the request fails due to a network or server error, the url is invalid, etc. It will also be called if the load or handle callback throws an exception, unless djConfig.debugAtAllCosts is true. This allows deployed applications to continue to run even when a logic error happens in the callback, while making it easier to troubleshoot while in debug mode.

  • handle:

    This function will be called at the end of every request, whether or not an error occurs.

  • url (String):

    URL to server endpoint.

  • content (Object, optional):

    Contains properties with string values. These properties will be serialized as name1=value2 and passed in the request.

  • timeout (Integer, optional):

    Milliseconds to wait for the response. If this time passes, the then error callbacks are called.

  • form (DOMNode, optional):

    DOM node for a form. Used to extract the form values and send to the server.

  • preventCache (Boolean, optional):

    Default is false. If true, then a "dojo.preventCache" parameter is sent in the request with a value that changes with each request (timestamp). Useful only with GET-type requests.

  • rawBody (String, optional):

    Sets the raw body for an HTTP request. If this is used, then the content property is ignored. This is mostly useful for HTTP methods that have a body to their requests, like PUT or POST. This property can be used instead of postData and putData for dojo/_base/xhr.rawXhrPost and dojo/_base/xhr.rawXhrPut respectively.

  • ioPublish (Boolean, optional):

    Set this explicitly to false to prevent publishing of topics related to IO operations. Otherwise, if djConfig.ioPublish is set to true, topics will be published via dojo/topic.publish() for different phases of an IO operation. See dojo/main.__IoPublish for a list of topics that are published.

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:

Parameter Type Description
args Object

An object with the following properties:

  • handleAs (String, optional):

    Acceptable values are: text (default), json, json-comment-optional, json-comment-filtered, javascript, xml. See dojo/_base/xhr.contentHandlers

  • sync (Boolean, optional):

    false is default. Indicates whether the request should be a synchronous (blocking) request.

  • headers (Object, optional):

    Additional HTTP headers to send in the request.

  • failOk (Boolean, optional):

    false is default. Indicates whether a request should be allowed to fail (and therefore no console error message in the event of a failure)

  • contentType (String|Boolean):

    "application/x-www-form-urlencoded" is default. Set to false to prevent a Content-Type header from being sent, or to a string to send a different Content-Type.

  • load:

    This function will be called on a successful HTTP response code.

  • error:

    This function will be called when the request fails due to a network or server error, the url is invalid, etc. It will also be called if the load or handle callback throws an exception, unless djConfig.debugAtAllCosts is true. This allows deployed applications to continue to run even when a logic error happens in the callback, while making it easier to troubleshoot while in debug mode.

  • handle:

    This function will be called at the end of every request, whether or not an error occurs.

  • url (String):

    URL to server endpoint.

  • content (Object, optional):

    Contains properties with string values. These properties will be serialized as name1=value2 and passed in the request.

  • timeout (Integer, optional):

    Milliseconds to wait for the response. If this time passes, the then error callbacks are called.

  • form (DOMNode, optional):

    DOM node for a form. Used to extract the form values and send to the server.

  • preventCache (Boolean, optional):

    Default is false. If true, then a "dojo.preventCache" parameter is sent in the request with a value that changes with each request (timestamp). Useful only with GET-type requests.

  • rawBody (String, optional):

    Sets the raw body for an HTTP request. If this is used, then the content property is ignored. This is mostly useful for HTTP methods that have a body to their requests, like PUT or POST. This property can be used instead of postData and putData for dojo/_base/xhr.rawXhrPost and dojo/_base/xhr.rawXhrPut respectively.

  • ioPublish (Boolean, optional):

    Set this explicitly to false to prevent publishing of topics related to IO operations. Otherwise, if djConfig.ioPublish is set to true, topics will be published via dojo/topic.publish() for different phases of an IO operation. See dojo/main.__IoPublish for a list of topics that are published.

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.

Parameter Type Description
priority Integer
Optional

The order in which to exec this callback relative to other callbacks, defaults to 1000

context undefined

The context in which to run execute callback, or a callback if not using context

callback Function
Optional

The function to execute.

Examples

Example 1

Simple DOM and Modules ready syntax

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

Example 2

Using a priority

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

Example 3

Using context

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

Example 4

Using dojo/hitch style args:

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.

Parameter Type Description
moduleName String
prefix String

Examples

Example 1

If your dojo.js is located at this location in the web root:

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

and your modules are located at:

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

Your application can tell Dojo to locate the "foo" namespace by calling:

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

At which point you can then use dojo.require() to load the

modules (assuming they provide() the same things which are required). The full code might be:

<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.

Parameter Type Description
node DOMNode | String

id or reference to the element to remove the attribute from

name String

the name of the attribute to remove

removeClass(node,classStr)

Defined by dojo/dom-class

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

Parameter Type Description
node String | DOMNode

String ID or DomNode reference to remove the class from.

classStr String | Array
Optional

An optional String class name to remove, or several space-separated class names, or an array of class names. If omitted, all class names will be deleted.

Examples

Example 1

Remove a class from some node:

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

Example 2

Remove two classes from some node:

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

Example 3

Remove two classes from some node (using array):

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

Example 4

Remove all classes from some node:

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

Example 5

Available in dojo/NodeList for multiple removal

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

Parameter Type Description
node String | DOMNode

String ID or DomNode reference to remove the class from.

addClassStr String | Array

A String class name to add, or several space-separated class names, or an array of class names.

removeClassStr String | Array
Optional

A String class name to remove, or several space-separated class names, or an array of class names.

Examples

Example 1

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

Example 2

Replace all classes with addMe

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

Example 3

Available in dojo/NodeList for multiple toggles

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.

Parameter Type Description
moduleName String

module name to load, using periods for separators, e.g. "dojo.date.locale". Module paths are de-referenced by dojo's internal mapping of locations to names and are disambiguated by longest prefix. See dojo.registerModulePath() for details on registering new modules.

omitModuleCheck Boolean
Optional

if true, omitModuleCheck skips the step of ensuring that the loaded file actually defines the symbol it is referenced by. For example if it called as dojo.require("a.b.c") and the file located at a/b/c.js does not define an object a.b.c, and exception will be throws whereas no exception is raised when called as dojo.require("a.b.c", true)

Returns: any

the required namespace object

Examples

Example 1

To use dojo.require in conjunction with dojo.ready:

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

Example 2

For example, to import all symbols into a local block, you might write:

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

And to import just the leaf symbol to a local variable:

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

Parameter Type Description
condition Boolean
moduleName String
omitModuleCheck Boolean
Optional

Examples

Example 1

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

Parameter Type Description
condition Boolean
moduleName String
omitModuleCheck Boolean
Optional

Examples

Example 1

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

requireLocalization(moduleName,bundleName,locale)

Defined by dojo/_base/loader

Parameter Type Description
moduleName String
bundleName String
locale String
Optional

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().

Parameter Type Description
target Object

Target object to accept new properties.

source Object

Source object for new properties.

Returns: Object

Target object to accept new properties.

Examples

Example 1

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.

Parameter Type Description
node DOMNode | String

id or reference to the element to set the attribute on

name String | Object

the name of the attribute to set, or a hash of key-value pairs to set.

value String
Optional

the value to set for the attribute, if the name is a string.

Returns: any | undefined

the DOM node

Examples

Example 1

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

Example 2

Set multiple values at once, including event handlers:

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.

Parameter Type Description
node DOMNode
box Object

hash with optional "w", and "h" properties for "width", and "height" respectively. All specified properties should have numeric values in whole pixels.

computedStyle Object
Optional

This parameter accepts computed styles object. If this parameter is omitted, the functions will call dojo/dom-style.getComputedStyle to get one. It is a better way, calling dojo/dom-style.getComputedStyle once, and then pass the reference to this computedStyle parameter. Wherever possible, reuse the returned object of dojo/dom-style.getComputedStyle().

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.

Parameter Type Description
globalObject Object
globalDocument DocumentElement

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.

Parameter Type Description
node DOMNode
box Object

hash with optional "l", "t", "w", and "h" properties for "left", "right", "width", and "height" respectively. All specified properties should have numeric values in whole pixels.

computedStyle Object
Optional

This parameter accepts computed styles object. If this parameter is omitted, the functions will call dojo/dom-style.getComputedStyle to get one. It is a better way, calling dojo/dom-style.getComputedStyle once, and then pass the reference to this computedStyle parameter. Wherever possible, reuse the returned object of dojo/dom-style.getComputedStyle().

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.

Parameter Type Description
node DOMNode | String

id or reference to the element to set the property on

name String | Object

the name of the property to set, or a hash object to set multiple properties at once.

value String
Optional

The value to set for the property

Returns: any | undefined

the DOM node

Examples

Example 1

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

Example 2

Set multiple values at once, including event handlers:

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

setSelectable(node,selectable)

Defined by dojo/dom

Parameter Type Description
node undefined
selectable undefined

setStyle(node,name,value)

Defined by dojo/dom-style

Sets styles on a node.

Parameter Type Description
node DOMNode | String

id or reference to node to set style for

name String | Object

the style property to set in DOM-accessor format ("borderWidth", not "border-width") or an object with key/value pairs suitable for setting each property.

value String
Optional

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.

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.

Examples

Example 1

Passing a node, a style property, and a value changes the current display of the node and returns the new computed value

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

Example 2

Passing a node, an object-style style property sets each of the values in turn and returns the computed style object of the node:

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

Example 3

When the CSS style property is hyphenated, the JavaScript property is camelCased. font-size becomes fontSize, and so on.

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

Example 4

dojo/NodeList implements .style() using the same syntax, omitting the "node" parameter, calling dojo/dom-style.get() on every element of the list. See: dojo/query and dojo/NodeList

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

Parameter Type Description
arr Array | String

the array to iterate over. If a string, operates on individual characters.

callback Function | String

a function is invoked with three arguments: item, index, and array and returns true if the condition is met.

thisObject Object
Optional

may be used to scope the call to callback

Returns: Boolean

Examples

Example 1

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

Example 2

// 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

Parameter Type Description
evt Event

The event object. If omitted, window.event is used on IE.

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().

Parameter Type Description
node DOMNode | String

id or reference to node to get/set style for

name String | Object
Optional

the style property to set in DOM-accessor format ("borderWidth", not "border-width") or an object with key/value pairs suitable for setting each property.

value String
Optional

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.

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

Examples

Example 1

Passing only an ID or node returns the computed style object of the node:

dojo.style("thinger");

Example 2

Passing a node and a style property returns the current normalized, computed value for that property:

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

Example 3

Passing a node, a style property, and a value changes the current display of the node and returns the new computed value

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

Example 4

Passing a node, an object-style style property sets each of the values in turn and returns the computed style object of the node:

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

Example 5

When the CSS style property is hyphenated, the JavaScript property is camelCased. font-size becomes fontSize, and so on.

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

Example 6

dojo/NodeList implements .style() using the same syntax, omitting the "node" parameter, calling dojo.style() on every element of the list. See: dojo/query and dojo/NodeList

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.

Parameter Type Description
frag String

the HTML fragment

doc DocumentNode
Optional

optional document to use when creating DOM nodes, defaults to dojo/_base/window.doc if not specified.

Returns: any | undefined

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

Examples

Example 1

Create a table row:

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.

Parameter Type Description
node String | DOMNode

String ID or DomNode reference to toggle a class string

classStr String | Array

A String class name to toggle, or several space-separated class names, or an array of class names.

condition Boolean
Optional

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

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.

Examples

Example 1

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

Example 2

Forcefully add a class

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

Example 3

Available in dojo/NodeList for multiple toggles

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.

Parameter Type Description
it Object

an object to be serialized. Objects may define their own serialization via a special "json" or "json" function property. If a specialized serializer has been defined, it will be used as a fallback. Note that in 1.6, toJson would serialize undefined, but this no longer supported since it is not supported by native JSON serializer.

prettyPrint Boolean
Optional

if true, we indent objects and arrays to make the output prettier. The variable dojo.toJsonIndentStr is used as the indent string -- to use something other than the default (tab), change that variable before calling dojo.toJson(). Note that if native JSON support is available, it will be used for serialization, and native implementations vary on the exact spacing used in pretty printing.

Returns: any | undefined

A JSON string serialization of the passed-in object.

Examples

Example 1

simple serialization of a trivial object

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

Example 2

a custom serializer for an objects of a particular class:

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.

Parameter Type Description
node DOMNode
value String

Returns: Number

unsubscribe(handle)

Defined by dojo/_base/connect

Remove a topic listener.

Parameter Type Description
handle Handle

The handle returned from a call to subscribe.

Examples

Example 1

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.

Parameter Type Description
valueOrPromise undefined

Either a regular value or an object with a then() method that follows the Promises/A specification.

callback Function
Optional

Callback to be invoked when the promise is resolved, or a non-promise is received.

errback Function
Optional

Callback to be invoked when the promise is rejected.

progback Function
Optional

Callback to be invoked when the promise emits a progress update.

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.

Parameter Type Description
documentObject DocumentElement
callback Function
thisObject Object
Optional
cbArguments Array
Optional

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.

Parameter Type Description
globalObject Object
callback Function
thisObject Object
Optional
cbArguments Array
Optional

Returns: undefined

xhr(method,args)

Defined by dojox/rpc/Client

Parameter Type Description
method undefined
args undefined

Returns: undefined

xhrDelete(args)

Defined by dojo/_base/xhr

Sends an HTTP DELETE request to the server.

Parameter Type Description
args Object

An object with the following properties:

  • handleAs (String, optional):

    Acceptable values are: text (default), json, json-comment-optional, json-comment-filtered, javascript, xml. See dojo/_base/xhr.contentHandlers

  • sync (Boolean, optional):

    false is default. Indicates whether the request should be a synchronous (blocking) request.

  • headers (Object, optional):

    Additional HTTP headers to send in the request.

  • failOk (Boolean, optional):

    false is default. Indicates whether a request should be allowed to fail (and therefore no console error message in the event of a failure)

  • contentType (String|Boolean):

    "application/x-www-form-urlencoded" is default. Set to false to prevent a Content-Type header from being sent, or to a string to send a different Content-Type.

  • load:

    This function will be called on a successful HTTP response code.

  • error:

    This function will be called when the request fails due to a network or server error, the url is invalid, etc. It will also be called if the load or handle callback throws an exception, unless djConfig.debugAtAllCosts is true. This allows deployed applications to continue to run even when a logic error happens in the callback, while making it easier to troubleshoot while in debug mode.

  • handle:

    This function will be called at the end of every request, whether or not an error occurs.

  • url (String):

    URL to server endpoint.

  • content (Object, optional):

    Contains properties with string values. These properties will be serialized as name1=value2 and passed in the request.

  • timeout (Integer, optional):

    Milliseconds to wait for the response. If this time passes, the then error callbacks are called.

  • form (DOMNode, optional):

    DOM node for a form. Used to extract the form values and send to the server.

  • preventCache (Boolean, optional):

    Default is false. If true, then a "dojo.preventCache" parameter is sent in the request with a value that changes with each request (timestamp). Useful only with GET-type requests.

  • rawBody (String, optional):

    Sets the raw body for an HTTP request. If this is used, then the content property is ignored. This is mostly useful for HTTP methods that have a body to their requests, like PUT or POST. This property can be used instead of postData and putData for dojo/_base/xhr.rawXhrPost and dojo/_base/xhr.rawXhrPut respectively.

  • ioPublish (Boolean, optional):

    Set this explicitly to false to prevent publishing of topics related to IO operations. Otherwise, if djConfig.ioPublish is set to true, topics will be published via dojo/topic.publish() for different phases of an IO operation. See dojo/main.__IoPublish for a list of topics that are published.

Returns: undefined

xhrGet(args)

Defined by dojo/_base/xhr

Sends an HTTP GET request to the server.

Parameter Type Description
args Object

An object with the following properties:

  • handleAs (String, optional):

    Acceptable values are: text (default), json, json-comment-optional, json-comment-filtered, javascript, xml. See dojo/_base/xhr.contentHandlers

  • sync (Boolean, optional):

    false is default. Indicates whether the request should be a synchronous (blocking) request.

  • headers (Object, optional):

    Additional HTTP headers to send in the request.

  • failOk (Boolean, optional):

    false is default. Indicates whether a request should be allowed to fail (and therefore no console error message in the event of a failure)

  • contentType (String|Boolean):

    "application/x-www-form-urlencoded" is default. Set to false to prevent a Content-Type header from being sent, or to a string to send a different Content-Type.

  • load:

    This function will be called on a successful HTTP response code.

  • error:

    This function will be called when the request fails due to a network or server error, the url is invalid, etc. It will also be called if the load or handle callback throws an exception, unless djConfig.debugAtAllCosts is true. This allows deployed applications to continue to run even when a logic error happens in the callback, while making it easier to troubleshoot while in debug mode.

  • handle:

    This function will be called at the end of every request, whether or not an error occurs.

  • url (String):

    URL to server endpoint.

  • content (Object, optional):

    Contains properties with string values. These properties will be serialized as name1=value2 and passed in the request.

  • timeout (Integer, optional):

    Milliseconds to wait for the response. If this time passes, the then error callbacks are called.

  • form (DOMNode, optional):

    DOM node for a form. Used to extract the form values and send to the server.

  • preventCache (Boolean, optional):

    Default is false. If true, then a "dojo.preventCache" parameter is sent in the request with a value that changes with each request (timestamp). Useful only with GET-type requests.

  • rawBody (String, optional):

    Sets the raw body for an HTTP request. If this is used, then the content property is ignored. This is mostly useful for HTTP methods that have a body to their requests, like PUT or POST. This property can be used instead of postData and putData for dojo/_base/xhr.rawXhrPost and dojo/_base/xhr.rawXhrPut respectively.

  • ioPublish (Boolean, optional):

    Set this explicitly to false to prevent publishing of topics related to IO operations. Otherwise, if djConfig.ioPublish is set to true, topics will be published via dojo/topic.publish() for different phases of an IO operation. See dojo/main.__IoPublish for a list of topics that are published.

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:

Parameter Type Description
args Object

An object with the following properties:

  • handleAs (String, optional):

    Acceptable values are: text (default), json, json-comment-optional, json-comment-filtered, javascript, xml. See dojo/_base/xhr.contentHandlers

  • sync (Boolean, optional):

    false is default. Indicates whether the request should be a synchronous (blocking) request.

  • headers (Object, optional):

    Additional HTTP headers to send in the request.

  • failOk (Boolean, optional):

    false is default. Indicates whether a request should be allowed to fail (and therefore no console error message in the event of a failure)

  • contentType (String|Boolean):

    "application/x-www-form-urlencoded" is default. Set to false to prevent a Content-Type header from being sent, or to a string to send a different Content-Type.

  • load:

    This function will be called on a successful HTTP response code.

  • error:

    This function will be called when the request fails due to a network or server error, the url is invalid, etc. It will also be called if the load or handle callback throws an exception, unless djConfig.debugAtAllCosts is true. This allows deployed applications to continue to run even when a logic error happens in the callback, while making it easier to troubleshoot while in debug mode.

  • handle:

    This function will be called at the end of every request, whether or not an error occurs.

  • url (String):

    URL to server endpoint.

  • content (Object, optional):

    Contains properties with string values. These properties will be serialized as name1=value2 and passed in the request.

  • timeout (Integer, optional):

    Milliseconds to wait for the response. If this time passes, the then error callbacks are called.

  • form (DOMNode, optional):

    DOM node for a form. Used to extract the form values and send to the server.

  • preventCache (Boolean, optional):

    Default is false. If true, then a "dojo.preventCache" parameter is sent in the request with a value that changes with each request (timestamp). Useful only with GET-type requests.

  • rawBody (String, optional):

    Sets the raw body for an HTTP request. If this is used, then the content property is ignored. This is mostly useful for HTTP methods that have a body to their requests, like PUT or POST. This property can be used instead of postData and putData for dojo/_base/xhr.rawXhrPost and dojo/_base/xhr.rawXhrPut respectively.

  • ioPublish (Boolean, optional):

    Set this explicitly to false to prevent publishing of topics related to IO operations. Otherwise, if djConfig.ioPublish is set to true, topics will be published via dojo/topic.publish() for different phases of an IO operation. See dojo/main.__IoPublish for a list of topics that are published.

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:

Parameter Type Description
args Object

An object with the following properties:

  • handleAs (String, optional):

    Acceptable values are: text (default), json, json-comment-optional, json-comment-filtered, javascript, xml. See dojo/_base/xhr.contentHandlers

  • sync (Boolean, optional):

    false is default. Indicates whether the request should be a synchronous (blocking) request.

  • headers (Object, optional):

    Additional HTTP headers to send in the request.

  • failOk (Boolean, optional):

    false is default. Indicates whether a request should be allowed to fail (and therefore no console error message in the event of a failure)

  • contentType (String|Boolean):

    "application/x-www-form-urlencoded" is default. Set to false to prevent a Content-Type header from being sent, or to a string to send a different Content-Type.

  • load:

    This function will be called on a successful HTTP response code.

  • error:

    This function will be called when the request fails due to a network or server error, the url is invalid, etc. It will also be called if the load or handle callback throws an exception, unless djConfig.debugAtAllCosts is true. This allows deployed applications to continue to run even when a logic error happens in the callback, while making it easier to troubleshoot while in debug mode.

  • handle:

    This function will be called at the end of every request, whether or not an error occurs.

  • url (String):

    URL to server endpoint.

  • content (Object, optional):

    Contains properties with string values. These properties will be serialized as name1=value2 and passed in the request.

  • timeout (Integer, optional):

    Milliseconds to wait for the response. If this time passes, the then error callbacks are called.

  • form (DOMNode, optional):

    DOM node for a form. Used to extract the form values and send to the server.

  • preventCache (Boolean, optional):

    Default is false. If true, then a "dojo.preventCache" parameter is sent in the request with a value that changes with each request (timestamp). Useful only with GET-type requests.

  • rawBody (String, optional):

    Sets the raw body for an HTTP request. If this is used, then the content property is ignored. This is mostly useful for HTTP methods that have a body to their requests, like PUT or POST. This property can be used instead of postData and putData for dojo/_base/xhr.rawXhrPost and dojo/_base/xhr.rawXhrPut respectively.

  • ioPublish (Boolean, optional):

    Set this explicitly to false to prevent publishing of topics related to IO operations. Otherwise, if djConfig.ioPublish is set to true, topics will be published via dojo/topic.publish() for different phases of an IO operation. See dojo/main.__IoPublish for a list of topics that are published.

Returns: undefined

© 2005–2017 JS Foundation
Licensed under the AFL 2.1 and BSD 3-Clause licenses.
http://dojotoolkit.org/api/1.10/dojo/_base/kernel.html