Skip to Content | Skip to Navigation


dojo.cache

Project owner:James Burke
since:V1.4

A getter and setter method for storing the string content associated with the module and url arguments. It is a generic version of the functionality provided by dijit’s templatePath method.

This method’s functionality has been superseded by the dojo/text! plugin. The documentation below is left for legacy purposes.

Introduction

There are many times where you will want to inject some raw HTML into the DOM. However, it can be cumbersome to write the HTML as a string literal in JavaScript.

dojo.cache allows you to specify a path to a file that has the HTML, and dojo.cache will load it via a synchronous XMLHttpRequest (XHR) call. Because of this, the HTML file should live on the same domain as the web page that uses the JavaScript module that has the dojo.cache call.

The Dojo build system will inline the HTML as a string where the dojo.cache call happens, so it allows for better performance just by doing a build. Doing a build also allows the module to be used in xdomain loading scenarios.

Usage

dojo.cache is a Dojo Core module, To include the Dojo cache on your page, require the module dojo.cache. When use dojo 1.7, you should require dojo/text.js because the related functions used to define in dojo/cache.js have been moved.

// Dojo 1.7 (AMD)
require("dojo/text", function(){
    // write your code here
});
// Dojo < 1.7
dojo.require("dojo.cache");

dojo.cache takes the following arguments:

dojo.cache(module, url, configValue);

Examples

This is the usual, most common use of the dojo.cache call:

// Dojo 1.7 (AMD)
require("dojo/text", function(){
  var text = dojo.cache("my.module", "template.html");
});
// Dojo 1.7
dojo.require("dojo.cache");
var text = dojo.cache("my.module", "template.html");

If my/module/template.html contained the text “<div>Hello World</div>”, then the text variable will have that value.

An example using the sanitize: true option:

// Dojo 1.7 (AMD)
require("dojo/text", function(){
  var text = dojo.cache("my.module", "template.html", {sanitize: true});
});
// Dojo < 1.7
dojo.require("dojo.cache");
var text = dojo.cache("my.module", "template.html");

If my/module/template.html contains “<html><body><h1>Hello</h1></body></html>”, the text variable will contain just “<h1>Hello</h1>”.

Example using an object that has like the previous example, but uses an object whose toString() method represents a file path:

// Dojo 1.7 (AMD)
require("dojo/text", function(){
  var text = dojo.cache(new dojo._Url("my/module/template.html"), {sanitize: true});
});
// Dojo < 1.7
dojo.require("dojo.cache");
var text = dojo.cache(new dojo._Url("my/module/template.html"), {sanitize: true});

API Info

full API:http://dojotoolkit.org/api/dojo/cache
summary:A getter and setter for storing the string content associated with the module and url arguments.

Parameters

Signature

dojo.cache( /* String||Object */ module,  /* String */ url,  /* String||Object */ value)

Overview

  • module String||Object

    If a String with slashes, a fully resolved path; if a String without slashes, the module name to use for the base part of the URL, similar to module argument to dojo.moduleUrl. If an Object, something that has a .toString() method that generates a valid path for the cache item. For example, a dojo._Url object.

  • 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 &quot;value&quot; argument instead.

  • value String||Object

    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.

Examples

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. var text = dojo[“cache”](“my.module”, “template.html”);

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>”. var text = dojo[“cache”](“my.module”, “template.html”, {sanitize: true});

Same example as previous, but demostrates 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>”. var text = dojo[“cache”](new dojo._Url(“my/module/template.html”), {sanitize: true});