API compile

API: Mustache.compile

Description

Given a set of Mustache template fragment(s), this function will return a function that takes an associated data object which can be used to return the results of an interpolation. This function is useful when a particular Mustache template needs to be interpolated many times or if it contains complex template code. In these instances, it is much more performant than the to_html API function.

Signatures

Mustache.compile(template)
Mustache.compile(template, partials)

The template parameter specifies the "entry point" into the Mustache template and must be present. From this template, you can reference other template fragments using the partials paramter. The format of this string must match the Mustache Syntax.

The partials parameter is a key/value pair of Mustache template fragments. The keys are the partials specified in the template Mustache fragment or the partials specified in other partials.

Returns

The function returns a function with the following signature:

function(view, send_func)

Where

The view parameter specifies the associated data object that the interpolation is to run on. All JavaScript constructs are accepted in for this key/value pair. That is, this paramter is not necessarily just a JSON object, functions and Date objects are also accepted.

The send_func parameter is a callback function that allows the user to view a "stream" of the results of the interpolation. That is, using this function it is not necessary to wait until the end of the interpolation to see the results, the user can see the result as it is being constructed. The signature of the callback function must match the following:

function(str)

Where str is the current output fragment that is being sent to the user.

Examples

At a minimum the template parameter must be supplied:

var compiled = Mustache.compile('{{interpolate}}');
var result = compiled({ interpolate: 'Bugs Bunny' });
result === 'Bugs Bunny'; // true

When using partials in the entry point template, you must include the partials argument as well:

var compiled = Mustache.compile('{{>a_partial}}', { a_partial: '{{interpolate}}' });
var result = compiled({ interpolate: 'Bugs Bunny' });
result === 'Bugs Bunny'; // true

Sometimes it can be important to "stream" the results of the interpolation. This can be achieved using the send_func parameter:

var compiled = Mustache.compile('{{a}} {{b}} {{c}}');
var result = compiled({ 
	a: 'Bugs Bunny',
	b: 'Daffy Duck',
	c: 'Wile E. Coyote'
}, function(token) {
	// the first time, token will be 'Bugs Bunny'
	// the second time, token will be ' '
	// the third time, token will be 'Daffy Duck'
	// etc.
});

In general, the streaming is triggered before and after Mustache tags, but this is not guaranteed and is subject to change.

Exceptions

Note that if the Mustache templates provided to the to_html function are not conformant to the Mustache syntax, the function will throw a Mustache.Error specifying where in the code block it failed. Therefore, it is prudent to wrap the to_html call in a try/catch block:

try {
	var compiled = Mustache.compile('{{=');
	//compiled === ??
} catch (e) {
	if (e instanceof Mustache.Error) {
		// e contains information about the error
	}
}