Templ8.js

Templ8 as you can probably guess is a JavaScript template engine, with a Django'ish style of syntax.

It's fast, light weight and unlike a lot of other JavaScript template engines: Templ8 does not use the JavaScript with statement. This actually makes Templ8 parse templates faster than it would if it did use the with statement!

Templ8 does not restrict you to generating HTML. All outputs are strings so if you want to generate HTML, CSS, JavaScript or whatever, the choice is yours...

#TODO:

• documentation is not yet complete

Dependencies

Templ8.js only has one dependency m8.js.

NOTE: If you are using Templ8 within a commonjs module, you don't need to require m8 before requiring Templ8 as this is done internally and a reference to m8 is available as: Templ8.m8.

   var Templ8 = require( 'Templ8' ),
       m8     = Templ8.m8; // <= reference to m8

// if running in a sandboxed environment remember to:
   m8.x( Object, Array, Boolean, Function, String ); // and/ or any other Types that require extending.

See m8: Extending into the future for more information on working with sandboxed modules.

Support

Tested to work with nodejs, FF4+, Safari 5+, Chrome 7+, IE9+. Should technically work in any browser that supports ecma 5 without throwing any JavaScript errors.

API

If all you want to do is swap out values you can use one of the following two smaller template functions.

<static> Templ8.format( template:String, param1:String[, param2:String, ..., paramN:String] ):String

This function takes a minimum of two parameters. The first is the template you want perform substitutions over.

The template should use zero based tokens, e.g. {0}, {1} ... {N} that increment for each argument passed to the function.

e.g.

    Templ8.format( 'Hello {0}! Nice {1} we\'re having.', 'world', 'day' );

returns: Hello world! Nice day we're having.

---

 

<static> Templ8.gsub( template:String, dict:Object[, pattern:RegExp] ):String

gsub works similarly to format only it takes an Object with the values you want to substitute, instead of a sequence of parameters. Actually format calls gsub internally.

e.g.

    Templ8.gsub( 'Hello {name}! Nice {time} we\'re having.', { name : 'world', time : 'day' } );

returns: Hello world! Nice day we're having.

The default pattern for substitutions is /\{([^\}]+)\}/g. However, you can supply a third argument to gsub which is your own custom pattern to use instead of the default.

If you want to do fancy stuff, you'll want to use the Templ8 constructor.

---

 

new Templ8( template:String, options:Object )

The Templ8 constructor actually takes an arbitrary number of String arguments which form the template body.

The last argument to the Templ8 can -- optionally -- be a configuration Object which defines any custom Filters you want to use for this Templ8 and any sub Templates it contains.

It also accepts the following four parameters (needless to say that these cannot be used as Filter names):

<table border="0" cellpadding="0" cellspacing="0"> <tr> <td><strong>compiled</strong></td><td>If this is set to <code>true</code> then the Templ8 will be compiled straight away, otherwise it will wait until the first time you call it's <code>parse()</code> method to compile. <strong>Default</strong> is <code>false</code>.</td> </tr><tr> <td><strong>debug</strong></td><td>Useful for debugging. Set this to <code>true</code> to have the Templ8 method body logged to the console. <strong>Default</strong> is <code>false</code>.</td> </tr><tr> <td><strong>fallback</strong></td><td>This is the String to use as a fallback value in case any values are not present when parsing a Templ8 instance. <strong>Default</strong> is <code>""</code>, Empty String.</td> </tr><tr> <td><strong>id</strong></td><td>The ID of your Templ8. This is handy (and mandatory) if you want to use a Templ8 from within another Templ8. Otherwise an anonymous ID will be generated for your Templ8.</td> </tr> </table>

---

 

Templ8 instance methods

To keep it simple, a Templ8 instance only contains one method.

parse( dictionary:Object ):String

This method accepts one parameter: an Object of values you want to substitute and returns a String of the parsed Templ8.

Any tokens in the Templ8 that do not have a dictionary value will use the fallback value described above,

---

 

Templ8 variables

basic global variables

$_

This is based on perl's $_ and is a reference to the the current dictionary value being parsed.

For instance if you are in a loop, rather than access the value using iter.current you could also access it via $_.

e.g. instead of this:

    {[ iter.current|parse:'sub_template' for each ( items ) ]}

or this:

    {[ item|parse:'sub_template' for each ( item in items ) ]}

you could do this:

    {[ $_|parse:'sub_template' for each ( items ) ]}

iter

This is the current iterator being parsed. It is an instance of an internal class called Iter. Iter instances are created internally, when you use a {% for %} loop or an Array Comprehension {[ for each ]} tag you should not need to create one yourself.

It has the following properties available for both Arrays and Objects:

<table border="0" cellpadding="0" cellspacing="0"> <tr> <td><strong>count</strong></td><td>the total number of all items in the Array or Object</td> </tr><tr> <td><strong>current</strong></td><td>The current item being iterated over.</td> </tr><tr> <td><strong>empty</strong></td><td>Whether or not the item to iterate over is empty – has no items. Note: if the item is not iterable, this will never be true.</td> </tr><tr> <td><strong>first</strong></td><td>The first item in the Array/ Object. Note: you cannot guarantee iteration order in an Object.</td> </tr><tr> <td><strong>firstKey</strong></td><td>The first key in the Array/ Object.</td> </tr><tr> <td><strong>index</strong></td><td>The zero based index of the current iteration.</td> </tr><tr> <td><strong>index1</strong></td><td>The one based index of the current iteration.</td> </tr><tr> <td><strong>key</strong></td><td>The key of the current item being iterated over in the Array/ Object. For Arrays this will be the same as <code>index</code>.</td> </tr><tr> <td><strong>last</strong></td><td>The last item in the Array/ Object.</td> </tr><tr> <td><strong>lastIndex</strong></td><td>The zero based index of the last item in the Array/ Object.</td> </tr><tr> <td><strong>lastKey</strong></td><td>The key of the last item in the Array/ Object.</td> </tr><tr> <td><strong>next</strong></td><td>The next item in the iteration, or undefined if we're at the last item.</td> </tr><tr> <td><strong>nextKey</strong></td><td>The next key in the iteration, or undefined if we're at the last item.</td> </tr><tr> <td><strong>parent</strong></td><td>If you are in a nested loop and want to call the parent iter, you can access it via this property.</td> </tr><tr> <td><strong>prev</strong></td><td>The previous item in the iteration, or undefined if we're at the first item.</td> </tr><tr> <td><strong>prevKey</strong></td><td>The previous key in the iteration, or undefined if we're at the first item.</td> </tr><tr> <td><strong>stopped</strong></td><td>Whether or not the iteration has been stopped..</td> </tr><tr> <td><strong>val</strong></td><td>The same as <code>current</code>.</td> </tr> </table>

It also has the following two methods:

<table border="0" cellpadding="0" cellspacing="0"> <tr> <td><strong>hasNext</strong></td><td>returns <code>false</code> if there is no value after the current iteration to iterate over. Otherwise it will return the <code>Iter</code> instance (this).</td> </tr><tr> <td><strong>stop</strong></td><td>will stop the <code>Iter</code> instance from iterating after the current iteration has completed.</td> </tr> </table>

---

 

Templ8 internal variables

Along with the above Templ8 has some internal variables accessible for the more advanced user, should they require access to them.

$C:ContextStack

Templ8 does not use the JavaScript with statement. It implements its own version of a with statement using an internal class called ContextStack.

It has five methods (you should NOT call these if you DO NOT know what you're doing):

<table border="0" cellpadding="0" cellspacing="0"> <tr> <td><strong>current</strong></td><td>returns the current context Object</td> </tr><tr> <td><strong>get</strong></td><td>attempts to return the value of a dictionary Object, if it is in the ContextStack, otherwise it will return the fallback value or undefined.</td> </tr><tr> <td><strong>pop</strong></td><td>removes the most recently added dictionary Object from the ContextStack.</td> </tr><tr> <td><strong>push</strong></td><td>adds a dictionary Object to the ContextStack.</td> </tr> </table>

__OUTPUT__:String

This is where all parsed template output is stored.

__ASSERT__:Function{}

This is a reference to Templ8.Assertions.

__FILTER__:Function{}

This is a reference to Templ8.Filters.

__UTIL__:Function{}

This is a reference to the internal utility functions used by Templ8.

---

 

Tags & Statements

Tag: {{}} - Interpolation

This tag is used for interpolating dictionary values with their respective template tokens. At it simplest a tag which will be replaced by a dictionary value foo would look something like this:

    var tpl = new Templ8( '{{foo}}' );
    tpl.parse( { foo : 'bar'