Cht loader

How to load template modules and localized string resources?

Singleton dojox.jtlc.CHT.loader provides a higher-level facility for automatic loading, parsing and compiling the template files and localization dictionaries NLS bundles associated with them. It also implements the logic necessary to resolve cross-module references in CHT, opening the way to reusable template libraries.

dojo.require( 'dojox.jtlc.CHT.loader' );

CHT modules

The loader adopts the following hierarchical naming convention for referencing the templates and template files:

[ Prefix. ] FileName.TemplateName

The optional Prefix could be a sequence of one or more dot-separated names. The combination of Prefix and FileName is the name of a CHT module and serves to positively identify the template file containing specific template.

Templates within the same CHT file refer to each other by their unqualified names (i.e. TemplateName). Cross-file (cross-module) references as well as references from the Javascript code (via the get() method of the loader object) should always use fully qualified names.

Please note that circular references between CHT modules could not be resolved by the loader and will not be detected as runtime errors: the operation will simply never finish!

Module names can be mapped to paths using the configuration mechanism provided by Dojo. It is often desirable to separate similarly named CHT and Javascript modules, and especially their associated NLS bundles, into separate directories. In order to support this capability the CHT module names are converted to Dojo module names in the following way:

Prefix.CHT.FileName

Thus, Javascript module app with its localization resources and the associated CHT module app with its resources will be, by default, stored as follows:

rootPath/
  CHT/
    nls/
      ru/
        app.js
    app.cht
  nls/
    ru/
      app.js
    app.js
  app.js

Note that default localization bundle for the CHT module CHT/nls/app.js is not required since CHT localization resources are keyed to the English strings rather than symbolic names.

Preloaded template files

Loader consults a global dictionary, preloadedCHT, to check for template files that have already been preloaded. The keys in this dictionary should be resource URLs identical to what the module names resolve to, and the values are either file content (as a string) or a promise object resolving to it. Here’s an example of how the template files may be preloaded:

preloadedCHT = {
  'CHT/app.cht': dojo.xhrGet({ url: 'CHT/app.cht' }).then( 
     function( text ) {
       preloadedCHT['CHT/app.cht'] = text;
    }
  )
};

Asynchronous operation

Unlike the Dojo loader, the template loader is asynchronous: if the operation (get() or require()) cannot be completed immediately, it returns a promise object. In simple cases this complication can be ignored by the application code because of a provision in the get() method: instead of an instance of dojo.Deferred it returns a forwarder function that, if used immediately, will delay the template execution till loading is complete. This makes it possible to write code like

dojox.jtlc.CHT.loader.get( 'app.MyTemplate' )( data ).render( 'placeholder', 'only' );

without first making sure that app.cht has indeed been loaded and parsed. Precise control over the point in time at which template rendering will occur can be achieved with an explicit dojo.when():

dojo.when(
dojox.jtlc.CHT.loader.get( 'app.MyTemplate' ),
  function( tpl ) {
    tpl( data ).render( 'placeholder', 'only' );
  }
);

and/or with an explicit call to require():

dojo.when(
  dojox.jtlc.CHT.loader.require( 'app' ),
  function() {
    dojox.jtlc.CHT.loader.get( 'app.MyTemplate' )( data ).render( 'placeholder', 'only' );
  }
);

Loader object API

See CHT.loader API for details.