olado/doT — Issue #16: More on docs
Author: kgcab
Created: 2011-12-12 19:45:25+00:00
State: open

I wrote up some docs for doT. Do these look largely correct?

-------

doT is a JavaScript package that supports runtime expansion of string templates.
It was inspired by templating functions from jQote2.js (a jQuery plugin)
by aefxx (http://aefxx.com/jquery-plugins/jqote2/)
and underscore.js (http://documentcloud.github.com/underscore/).

You can find doT at https://github.com/olado/doT
It was created and is maintained by Laura Doktorova.
It is licensed under the MIT license.

The doT package:
doT.template(template, templateSettings, defininitions) - Function
template = string (or stringifiable object) representing the template to be compiled.
templateSettings = associative array that defines various compiler settings (see Template Settings)
definitions = associative array accessed using the 'def' directive in templates
these are intended to support interpolation at template compile time
(note: examples imply this contains functions such as loadFile by default. It does not.
That example assumes the function loadFile is available in the current JavaScript context.)

Compiles the given template and returns a function that can be used to expand that template on demand.
The resulting function takes one argument, whose name may be changed using Template Settings:
it = an associative array of values that may be referenced during expansion of the template

doT.templateSettings - associative array
evaluate = regular expression used to locate and replace runtime evaluations in the template string
interpolate = regular expression used to locate and replace runtime interpolations in the template string
encode = regular expression used to locate and replace runtime interpolations which will be HTML encoded
prior to insertion in the template string
use = regular expression used to locate and replace compile time interpolation in the template string
define = regular expression used to locate and replace compile time variable definitions in the template string
varname = the name of the single argument to the function produced by doT.template
this is the associative array referenced by runtime interpolation and evaluation
strip = Boolean that controls whether or not end of line characters, CDATA tags, and comments
will be removed from compiled templates
defaults to true
append = Boolean that controls how interpolations are written in the compiled template.
The compiled template is just a JS function that binds a string to 'out'.
If true then interpolations are written as "+()+", resulting in one long string concatenation.
if false then interpolations are written as ";out+=();out+=", resulting in a series of
separate concatenations.
In some browsers, options one will be faster while option two will be faster in others. The choice is left to the user.
Note: I believe the second case will break if two interpolations are placed with no characters between them. Check.
defaults to true

Some definitions:
template - a string containing directives that fetch values from the JavaScript environment in order to construct a new string
this can be used to dynamically construct portions of your web page using values fetched, for example, using AJAX calls to a service.
interpolate - to add text to either the template itself at compiletime or to the expanded string at runtime
evaluate - to execute a bit of JavaScript and use the value returned
expansion - the process of taking each of the directives in a template and performing the task it specifies
the results are inserted into the result string in place of the directive
because the results are often larger than the directives themselves, we think of this as expanding the template
into the result
HTML encode - sometimes strings contain letters (characters) that have special meanings in HTML
HTML encoding such a string marks those letters such that a browsers will just display the letters and not treat
them as directions

doT directives:
compiletime definition = evaluate code at compile time and store in the 'definitions' associative array
Note that the 'definitions' are only available at compiletime (via the 'def' variable in JavaScript)
so these values will be consumed by 'use' directives, presumably
default syntax has several options:
"{{##:}}"
"{{##def.=}}"

if the 'definitions' argument passed to doT.template does not contain an entry that matches
if our assignment character is ':' we set definitions[] to the string
if our assignment character is '=' we evaluate in the current JavaScript context and set
definitions[] to that value
The 'definition' directive is removed from the template and no new text is inserted in its place.
The 'definitions' associative array is exposed as 'def' in the current JavaScript environment for 'use' directives.
Authors may rely on 'definition' and 'use' directives being evaluated in the order they occur in the template.

Note:
The examples supplied actually cannot all be parsed by default (they lack the assignment character and value).

compiletime use = interpolate at compiletime, with recursive expansion of 'definition' and 'use' directives.
default syntax:
"{{#}}"
Evaluates in the current JavaScript context.
if is not undefined, recursively expand 'definition' and 'use' directives that might be found in that string.
call toString() on other types of objects returned before performing this expansion.
The resulting string is inserted into the compiled template in place of the 'use' directive.
Authors may rely on 'definition' and 'use' directives being evaluated in the order they occur in the template.
The 'definitions' associative array is exposed as 'def' in the current JavaScript environment.
Note: there is no attempt to prevent infinite recursion. A recursion counter would be a VERY VERY good idea.

runtime interpolate = evaluate code in the current JavaScript context and insert the value returned into the resulting string
default syntax:
"{{=}}"
Evaluates in the current JavaScript context.
The result is inserted into the result string in place of the 'interpolate' directive.
Note: the code is evaluated after all other runtime directives have been expanded into code.
All runtime code is then evaluated en masse. One should not count on these being evaluated in order
as that assumption is subject to the whim of the JavaScript interpreter.

runtime encode = evaluate code in the current JavaScript context and insert the value returned into the resulting string
default syntax:
"{{!}}"
Evaluates in the current JavaScript context.
The result is first HTM encoded (lightly) then inserted into the result string in place of the 'encode' directive.
Note: the code is evaluated after all other runtime directives have been expanded into code.
All runtime code is then evaluated en masse. One should not count on these being evaluated in order
as that assumption is subject to the whim of the JavaScript interpreter.

runtime evaluate = evaluate code in the current JavaScript context but DO NOT insert the value into the result string
default syntax:
"{{}}"
Evaluates in the current JavaScript context.
The result is NOT inserted into the result string.
The strings resulting from 'print' calls in WILL be inserted into the result string in the order they occur.
The 'evaluate' directive is removed from the result string.
Note: the code is evaluated after all other runtime directives have been expanded into code.
All runtime code is then evaluated en masse. One should not count on these being evaluated in order
as that assumption is subject to the whim of the JavaScript interpreter.