CHT API Reference

CHT: API Reference

dojox.jtlc.CHT

The dojox.jtlc.CHT class serves as the primary access point for the CHT API. Its instances provide parsing functionality and are used as the language definition argument by the dojox.jtlc.compile(). Normally a single instance of this class is required for the entire application.

Constructor

var cht = new dojox.jtlc.CHT( options );

Argument options is a bag of properties customizing the interpretation of the template language and embedded data queries. At this point, there are two user-accessible option properties:

filters

Can be used to pass in a dictionary containing user-defined functions or expressions encoded as strings:

var cht = new dojox.jtlc.CHT( {
  filters: {
    fromHex: function(str){ parseInt(str,16); },
    toHex: "$.toString(16)"
  }
} );

Each entry of the dictionary is treated as a built-in tag in the embedded data queries (see the section on Q+ for details).

loadTemplates

Can be used to pass in a function for automatic resolution of cross-file references to template and automatic load of the .cht dependencies:

var cht = new dojox.jtlc.CHT( {
  loadTemplates: function( unresolved_references ){ ... }
} );

The function receives a single argument: dictionary of qualified template identifiers. The CHT parser assumes that any template name of the form Prefix . Name is defined in a different input file and can only be resolved via loadTemplates(), so all of these names will end up in this dictionary (as properties with values of false). The loadTemplates() function is expected to populate these properties with references to actual parsed template bodies, received from CHT.parse() called with appropriate input. The function should then return the resulting dictionary, or, as a more likely scenario, an instance of dojo.Deferred that will resolve to such a dictionary once the asynchronous loading and parsing operation is complete. The argument may be modified in place or copied at implementor’s option.

parse()

var ns = cht.parse( input_text );

or

dojo.when( cht.parse( input_text ), function(ns){ ... } );

The parse() method executes synchronously unless it encounters an asynchronously executing call to loadTemplates(). In either case, it returns — directly or via a dojo.Deferred promise object — a namespace object (dictionary) populated with templates defined in the input_text, or throws an exception if a syntax error occurs. The namespace always contains simple identifiers as properties (without a '.' in them) and their values are syntax trees that may serve as input to dojox.jtlc.compile().

It is also possible to populate a single namespace with templates from multiple input fragments by specifying the 2nd argument in a call to parse():

var ns = {};
cht.parse( input_1, ns );
cht.parse( input_2, ns );

Compilation

var template = dojox.jtlc.compile( ns[template_name], cht, compile_time_options );

Here cht should be the same instance of dojox.jtlc.CHT that produced the namespace object ns. The third argument is optional and can be used to pass in the translation dictionary used to localize the text strings in the template:

var translations = {};
var template = dojox.jtlc.compile( ns[template_name], cht, { i18nDictionary: translations } );

The above example will populate the translations dictionary with (presumably English) strings from the compiled template and all of its dependencies by creating properties with text string as the name and the value of false. Pre-populating the dictionary with properties mapping English strings to localized ones before the call to compile() will produce a localized instance of the template.

The following pattern may be followed to cache compiled template instances in order to improve performance:

function makeTemplateCache( input, translations ) {
  var cht = new dojox.jtlc.CHT(),
      ns = cht.parse( input ),
      cache = {};
  return function( name ) {
    return cache[name]||(
      cache[name] = dojox.jtlc.compile( ns[name], cht, { i18nDictionary: translations } )
    );
  }
}

var getTemplate = makeTemplateCache( input, translations );

and then getTemplate('myTemplate')(parameters...) used to render the HTML results. In a realistic scenario this code will be more complex because loading of both input files and the translations (as well as parsing, if cross-file references are supported) is likely to be asynchronous.

Using compiled templates

Each compiled template is a self-contained Javascript function (more precisely, a closure) that can accept up to 10 arguments. The result of a template execution is an (anonymous) object with the following methods:

toString()

Returns the resulting HTML as a text string that can be assigned to innerHTML.

toDom()

Returns an HTML document fragment object that can be inspected using DOM methods or inserted into an HTML document with a call to dojo.place.

toParsedDom()

var instances = [],
    dom = getTemplate('myTemplate')(parameters).toParsedDom( { instances: instances } );

Returns an HTML document fragment after applying dojo.parser.parse to its content to process dojoType attributes and instantiate codebehind objects and widgets. This method has an optional argument (property bag) that may contain any options of dojo.parser.parse() as well as an additional option instances used to return back an array with all object instances created by the parser. This array may be useful in cases when some of the objects do not automatically connect event handlers to themselves and may therefore be garbage-collected prematurely.