Login Register Help
API Documentation
Choose a stylesheet:
dojo » string » substitute

Functiondojo.string.substitute

dojo.require("dojo.string");
Performs parameterized substitutions on a string. Throws an exception if any parameter is unmatched.
parametertypedescription
templateStringa string with expressions in the form ${key} to be replaced or ${key:format} which specifies a format function. keys are case-sensitive.
mapObject|Arrayhash to search for substitutions
transformFunctionOptional. a function to process all parameters before substitution takes place, e.g. mylib.encodeXML
thisObjectObjectOptional. 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";
        }
    }
);

Example 4

Substitutes two expressions in a string from an Array or Object

// returns "File 'foo.html' is not found in directory '/temp'."
// by providing substitution data in an Array
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'."
// but provides substitution data in an Object structure.  Dotted
// notation may be used to traverse the structure.
dojo.string.substitute(
    "File '${name}' is not found in directory '${info.dir}'.",
    { name: "foo.html", info: { dir: "/temp" } }
);

Example 5

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 6

Use a formatter

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