API Documentation

Choose a stylesheet:

dojo.string.substitute

dojo.require("dojo.string");

defined in dojo/string.js

Performs parameterized substitutions on a string. Throws an exception if any parameter is unmatched.

parameter	type	description
template	String	a string with expressions in the form `${key}` to be replaced or `${key:format}` which specifies a format function. keys are case-sensitive.
map	Object\|Array	hash to search for substitutions
transform	Function	Optional. a function to process all parameters before substitution takes place, e.g. dojo.string.encodeXML
thisObject	Object	Optional. where to look for optional format function; default to the global namespace

Usage

var foo=dojo.string.substitute(template: String, map: Object|Array, transform: Function?, thisObject: Object?);

Examples

Example 1

// returns "File 'foo.html' is not found in directory '/temp'."
dojo.string.substitute(
    "File '${0}' is not found in directory '${1}'.",
    ["foo.html","/temp"]
);
 
 
// also returns "File 'foo.html' is not found in directory '/temp'."
dojo.string.substitute(
    "File '${name}' is not found in directory '${info.dir}'.",
    { name: "foo.html", info: { dir: "/temp" } }
);

Example 2

use a transform function to modify the values:

// returns "file 'foo.html' is not found in directory '/temp'."
dojo.string.substitute(
    "${0} is not found in ${1}.",
    ["foo.html","/temp"],
    function(str){
        // try to figure out the type
        var prefix = (str.charAt(0) == "/") ? "directory": "file";
        return prefix + " '" + str + "'";
    }
);

Example 3

use a formatter

// returns "thinger -- howdy"
dojo.string.substitute(
    "${0:postfix}", ["thinger"], null, {
        postfix: function(value, key){
            return value + " -- howdy";
        }
    }
);

Navigating the Dojo API Tool

There are several different methods of navigating through the object structure of the Dojo Toolkit:

Use the namespace list (to the left). The simplest method would be to use the list of namespaces defined by the Dojo Toolkit, on the left side of every page.
Drill-down from where you are. The API Tool was designed to give you as much information via drill-down as possible. Everything defined in an object can be clicked on, for more information.
Use the search. At the top of the namespace list to the left is a search box; type in the terms you are looking for, and you will be taken to a result page that spans the entire toolkit.

In addition, objects with large numbers of contained types have a simple way of jumping to sections on a page; simply look at the right side of any heading, and you will see a set of quick navigation icons. Clicking a type icon will take you to that section; clicking the up arrow icon will return you to the top of the page.

Inherited and private members

The Dojo API Tool will show the full ancestry of an object's members (including how that member was defined and whether or not it overrides an original). By default, all members of an object that are inherited are shown with the object's API listing, and all private members are hidden.

To toggle either inherited or private members, look just beneath the breadcrumb bar (above the name of the object you are viewing) and click the appropriate link.

Switching styles

The Dojo API Tool was designed with several themes in mind; we know that some people prefer light on dark, while others might prefer dark on light. With this in mind, two themes (Noir and Blanc) are currently available, with more on the way.

To switch visual styles, click on the theme you want to use, near the top right corner of the page. The API Tool will remember which style you prefer and automatically load that theme on subsequent visits.

Key/Legend

Namespaces

A namespace in Dojo parlance is an object/property bag that can contain almost anything: constructors, methods, properties, etc. Usually is expressly defined to serve a particular purpose; for example, dojo.date.locale is a namespace defined to deal with locale-specific date handling.

Constructors

A constructor is a function designed to create instances of objects. With the Dojo Toolkit, there are two ways of creating constructors: the "old school" way (i.e. defining a function with the this keyword in the body) or using dojo.declare.

Singletons

A singleton is a constructor that is defined and then immediately executed so that only one instance may ever exist during an application's lifetime. Usually this is done to capture some information in the environment, or to ensure a set of private variables that cannot be accessed from outside of the declaration. Examples include dojox.encoding.crypto.Blowfish.

Data Types

Array

Arrays are ordered lists, native to Javascript.

Boolean

Native data type representing a simple "true/false" value.

Date

Native Javascript data type to handle common date and time representations.

Node

An object that represents any kind of element being referenced/used by Javascript code. Note that the type of element is not dictated by this data type; only that it is a node of some sort.

Error

A special, native Javascript object used to indicate an error in code. Can be subclassed and used in conjunction with the throw statement, i.e. throw new MySubError(...);

Function

Functions/methods are pieces of invocable code; in JavaScript, they are also considered data and can be passed around like any other object.

Number

A Number object is used to represent any kind of numeric value; note that Javascript does not guarentee the actual underlying datatype (though the most common is a 64-bit float).

Object

Objects are the base data type of Javascript. With the Dojo API Tool, a type that cannot be determined is usually marked with this icon, in addition to straight objects.

RegExp (Regular Expression)

A regular expression is an object used for fast string search and parsing.

String

A string is any sequence of characters.

Input formats

Filtered HTML:
- Web page addresses and e-mail addresses turn into links automatically.
- Allowed HTML tags: <a> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd>
 
 This site allows HTML content. While learning all of HTML may feel intimidating, learning how to use a very small number of the most basic HTML "tags" is very easy.
 
 For more information see W3C's HTML Specifications or use your favorite search engine to find other sites that explain HTML.
 
 Most unusual characters can be directly entered without any problems.
 
 If you do encounter problems, try using HTML character entities. A common example looks like & for an ampersand & character. For a full list of entities see HTML's entities page.
- Lines and paragraphs are automatically recognized. The line break, paragraph and close paragraph tags are inserted automatically. If paragraphs are not recognized simply add a couple blank lines.
PHP code:
- Using custom PHP code
  
  If you know how to script in PHP, Drupal gives you the power to embed any script you like. It will be executed when the page is viewed and dynamically embedded into the page. This gives you amazing flexibility and power, but of course with that comes danger and insecurity if you do not write good code. If you are not familiar with PHP, SQL or with the site engine, avoid experimenting with PHP because you can corrupt your database or render your site insecure or even unusable! If you do not plan to do fancy stuff with your content then you are probably better off with straight HTML.
  
  Remember that the code within each PHP item must be valid PHP code - including things like correctly terminating statements with a semicolon. It is highly recommended that you develop your code separately using a simple test script on top of a test database before migrating to your production environment.
  
  Notes:
  - You can use global variables, such as configuration parameters, within the scope of your PHP code but remember that global variables which have been given values in your code will retain these values in the engine afterwards.
  - register_globals is now set to off by default. If you need form information you need to get it from the "superglobals" $_POST, $_GET, etc.
  - You can either use the print or return statement to output the actual content for your item.
  A basic example:
  You want to have a box with the title "Welcome" that you use to greet your visitors. The content for this box could be created by going:
```
print t("Welcome visitor, ... welcome message goes here ...");
								
```
  If we are however dealing with a registered user, we can customize the message by using:
```
global $user;
if ($user->uid) {
	print t("Welcome $user->name, ... welcome message goes here ...");
}
else {
	print t("Welcome visitor, ... welcome message goes here ...");
}
								
```
  For more in-depth examples, we recommend that you check the existing Drupal code and use it as a starting point, especially for sidebar boxes.
Full HTML:
- Web page addresses and e-mail addresses turn into links automatically.
- Lines and paragraphs are automatically recognized. The line break, paragraph and close paragraph tags are inserted automatically. If paragraphs are not recognized simply add a couple blank lines.
Markdown:
- Quick Tips:
  - Two or more spaces at a line's end = Line break
  - Double returns = Paragraph
  - *Single asterisks* or _single underscores_ = Emphasis
  - **Double** or __double__ = Strong
  - This is [a link](http://the.link.com "The optional title text")
  For complete details on the Markdown syntax, see the Markdown documentation.