Precompilation

Precompilation is a means by which the use of templates can be made faster. This can be particularly useful for mobile devices.

There are two means by which a template can be precompiled.

Individual Precompilation

Templates may be individually precompiled using Emboss.compile().

var precompiledTemplate = Emboss.compile(document.getElementById('template'));

The method expects one argument, being the source of a template. You can provide a HTML <script> element containing a template source. Alternatively, you can provide a string representing a template source.

var precompiledTemplate = Emboss.compile('{{print message}}');

The method will return a compiled template in the form of an anonymous function.

The Emboss.render() method accepts a compiled template as its first argument. Its second argument is data in the form of an object.

var compiledTemplate = Emboss.render(precompiledTemplate, {message: 'This template was precompiled!'});

This would output the following.

This template was precompiled!

Bulk Precompilation

It would be quite tedious to individually precompile the many templates which make up your project.

Luckily, Emboss makes it easy to precompile all of your templates in bulk.

All you need do is call Emboss.bulkPrecompile(). It does not expect any arguments.

The method will search through <script> elements in your page. It will only include elements which have their type attribute set to text/x-html-emboss, the MIME type of Emboss.

<script type="text/x-html-emboss" id="template1">
	<h1>This template will be included for bulk precompilation.</h1>
</script>
<script type="text/x-html-emboss" id="template2" data-emboss-ignore="true">
	<h1>This template will be ignored for bulk precompilation.</h1>
</script>
<script type="text/x-html-emboss" id="template3">
	<h1>This template will also be included for bulk precompilation.</h1>
</script>

If you wish, you may exempt some templates from the bulk precompilation. This is simply achieved by assigning the emboss-ignore data attribute to the relevant <script> elements, with the value of "true".

Emboss.bulkPrecompile();

Once the method has precompiled all of your templates, it will create a precompiledTemplates.js file which your browser will ask you to save. You can rename precompiledTemplates.js to whatever you wish.

In order to use precompiledTemplates.js, simply include it in your webpage as you would any other JavaScript file.

<script type="application/javascript" src="./js/precompiledTemplates.js"></script>

You can have as many of these precompiled template files included in your webpage as you wish.

Precompiled template scripts will automatically integrate themselves into Emboss.

In order to retrieve a precompiled template included in a precompiled template script, simply call Emboss.getPrecompiledTemplate(). It expects its first argument to be the ID of the template you wish to retrieve.

document.body.innerHTML = Emboss.render(Emboss.getPrecompiledTemplate('template1'));

How does it work?

In essence, when a template is precompiled, a JavaScript function is generated representing the template. This precompiled template can be provided to Emboss, which will return compiled HTML.