If you haven’t used or never heard of jQote before you might want to check out this post first, as it provides a quick insight into jQote’s way of client-side templating.

I’ve set up a repository over at GitHub. That’s where you will find the latest releases.

So, what’s new for v2 you ask? Quite a lot, actually. But let’s see one by one:

1.  jQote2 breaks compatibility with its predecessor

- jQote2 now returns a flat string representation of the converted template whereas its predecessor would give you a jQuery object.

The reason behind this substantial change is mainly speed. Appending the converted string as a whole cuts back greatly on the time it takes to generate the corresponding DOM fragment. On top of that you’ll now gain full control over your template’s outcome, to whom and when you want it to be appended etc.

2.  jQote2 improves on template handling

- jQote2 now provides an interface to precompile your templates to lambda functions.

This is probably the most exiting new feature as it lets you precompile templates during development and simply use them in production afterwards – without the need to dish out your template code to your customers.

- jQote2 now supports on-the-fly template strings.

For quick and dirty templating jQote2 now enables you to process template strings. This will make it easy for you to realize minor templating tasks on-the-fly without added the overhead.

3.  jQote2 is powered by a faster and more robust parsing engine

- jQote2 now offers full multiline and escaping quotes support.

The previous version had issues regarding line breaks within the scope of shorttags which are used to echo out the result of Javascript expressions. jQote2 now fully supports your way of coding style: what goes inbetween the tags (be it shorttags or standard notation) is pure Javascript and you decide how it is layed out.

Pure Javascript support implies proper escaping of quotes, though. And you will have to take care of that yourself. Outside the tags however the engine now correctly escapes qoutes within your markup, thus letting you concentrate on your work rather than the plugin’s internals.

- Speed, speed and again – speed!

Brian Landau has set up a bunch of benchmarks comparing the runtime of Javascript templating libraries. jQote didn’t perform all that bad but in the end couldn’t gain the crown.

With the release of jQote2 though the picture has changed quite a bit: jQote2 is now on a par with Underscore, the former sole sovereign, making both the natural choice for heavy Ajax powered sites. Please note though: Since Underscore internally uses John Resig’s conversion engine it replicates its flawed multiline and escaping quotes handling, leaving you with runtime errors whenever you need to have single quotes (both escaped or unescaped) inside the Javascript parts.

To backup my claims I forked Brian Landau’s benchmarks and put together a single file benchmarking suite at github. To offer you some eye candy I’ve integrated the powerful flot plotting library. Here’s an example of my findings running the benchmark 25 times with a 1000 conversions each in Firefox 3.5.7.

From left to right: Srender, mustache.js, Underscore, jQote2, Tempest, nano.
Less is better. All times in ms.

As you see Underscore and jQote2 vastly outperform the other contestants and moreover are superior in their ability to embed pure Javascript within the templates.

Enough said! Try it for yourself. Due to repeated requests I have finally set up a repository over at github. You may fetch the latest versions there. So long …

The three biggest changes with jQote2’s API are:

1. it now returns a “stringified” representation of your generated HTML markup
2. it’s now possible to precompile your templates to closures (no need to deliver template markup within your documents anymore)
3. it now supports on-the-fly templating strings

Here’s a quick overview of jQote2 ’s new interface:

• .jqote(data[, tag])
• .jqoteapp(template, data[, tag])
• .jqotepre(template, data[, tag])
• .jqotesub(template, data[, tag])

• $.jqote(template, data[, tag])
• $.jqotec(template[, tag])
• $.jqotefn(template)
• $.jqotetag(string)

$(template).jqote(data[, tag]) : function

jQote2 is able to operate on an arbitrary number of templates, each of which may process an arbitrary number of data objects, thus effectively allowing you to trigger n:m conversions with a single call.

Each time a template of yours is run, it is passed a couple of auxiliary variables:

• two counting variables i and j
  (the former iterating over the processed templates, the latter iterating over your data objects array)
• the data objects array data itself
• the current processed template’s compiled lambda fn
  
  (which comes in handy with recursive calls)

To not be forced to use data[j] to access a template’s current data object, its compiled lambda is fired in the context of the data object, so you may just as well use the this keyword to reference your data.

Additionally, during the process of conversion (the execution of the lambda, that is) you may access the by then converted output using the out variable. This gives you total control over the output even from within a template at any time.

By the way: all of the above is also true for any of the jqoteXXX convenience methods explained below.

Returns

out : string (the processed outcome)

Parameters

data : object | array of object

One or more objects that carry the template’s dynamic data. Each data object that’s passed in here will get merged with any of the templates you called the conversion upon.

tag : string (optional, defaults to "%")

You may use the optional tag parameter to specify different template tag character(s) for a single conversion. Keep in mind though that whatever char(s) C you opt for here will result in <C ... C>.

Called upon

template : jQuery object

Every template within the jQuery collection will be merged with any of your data objects.

Example

The infamous and obligatory “Hello World” … generated with a different start- and ending tag (the * star).

Note: data[j] is essentially the same as this!

<p id="example"></p>

<script type="text/x-jqote-template" id="template">
    <![CDATA[
    I said <strong><*= this.greet + " " + data[j].who *></strong> !!!
    <* out = out.replace(/John/, 'World'); *>
    ]]>
</script>

<script type="text/javascript">
    // let's do some jQote magic
    $('#example').append(
        $('#template').jqote({greet: 'Hello', who: 'John'}, '*')
    );
</script>

$(elem).jqoteapp(template, data[, tag]) : function

This is one of three convenience methods jQote2 has to offer. It allows you to append the processed template’s outcome directly to any DOM element that is part of the jQuery object.

Returns

jQuery : jQuery object

The returned jQuery object keeps the method chain intact. It is the same object that you called the convenience method upon.

Parameters

template : jQuery object | jQuery selector |
           DOM element | array of DOM element |
           lambda | array of lambda |
           template string

This parameter can be passed as about anything you possibly could think of. It’ll work with a collection of template elements (either as jQuery object or array of DOM elements) as well as single template elements (again jQuery object or DOM element).

Furthermore you could pass it a single or multiple (just wrap them up in an array) precompiled lambda which gets you the best performance as it will skip the compilation and execute right away.

For quick and dirty on-the-fly templating you may also choose to supply a template string which won’t get cached but other than that behaves just as any other template.

data : object | array of object

tag : string (optional)

Called upon

elem : jQuery object

The outcome of the conversion will be appended to every single DOM element within the jQuery object.

Example

The “Hello World” example from above rewritten.

<p id="example"></p>

<script type="text/html" id="template">
    <![CDATA[
    I said <strong><%= this.greet + " " + this.who %></strong> !!!
    <% out = out.replace(/John/, 'World'); %>
    ]]>
</script>

<script type="text/javascript">
    // let's do some jQote magic
    $('#example').jqoteapp('#template', {greet: 'Hello', who: 'John'});
</script>

Example

This makes use of the on-the-fly templating support.

<ul id="example"></ul>

<script type="text/javascript">
    $('#example').jqoteapp(
        '<li><<%= this.tag %>>Styled!</<%= this.tag %></li>',
        [ {tag: 'strong'}, {tag: 'em'} ]
    );
</script>

$(elem).jqotepre(template, data[, tag]) : function

This is jqoteapp’s counterpart as it behaves just the same way with one major difference: it prepends the outcome rather than appends it.

Returns

jQuery : jQuery object

Parameters

template : jQuery object | jQuery selector |
           DOM element | array of DOM element |
           lambda | array of lambda |
           template string

data : object | array of object

tag : string (optional)

Called upon

elem : jQuery object

$(elem).jqotesub(template, data[, tag]) : function

If you need to substitute an element’s “innerHTML” more than once, this function is for you. It replaces whatever resides within a DOM element with the outcome of your template’s processing.

Returns

jQuery : jQuery object

Parameters

template : jQuery object | jQuery selector |
           DOM element | array of DOM element |
           lambda | array of lambda |
           template string

data : object | array of object

tag : string (optional)

Called upon

elem : jQuery object

Example

Replace the target’s “innerHTML” with something more “up to date” …

<p id="up_to_date"></p>

<script type="text/javascript">
    $(function() {
        var now = function() {
            return new Date().toString().replace(/ GMT.*$/, '');
        };

        $('#up_to_date').bind('uptodate', function() {
            var self = $(this);

            setTimeout(function() {
                self.jqotesub('<%= this.date %>', {date: now()})
                    .triggerHandler('uptodate');
            }, 1000);
        }).triggerHandler('uptodate');
    });
</script>

$.jqote(template, data[, tag]) : function

This basically offers the same functionality as its object associated counterpart with the added possibility to have it process precompiled lambdas or on-the-fly template strings.

Returns

out : string (the processed outcome)

Parameters

template : jQuery object | jQuery selector |
           DOM element | array of DOM element |
           lambda | array of lambda |
           template string

data : object | array of object

tag : string (optional)

Example

Calculating the famous Fibonacci sequence (using just a small n due to Javascript’s limited recursion stack).

<ul id="fibonacci">
    <li></li>
    <li></li>
    <li></li>
    <li></li>
    <li></li>
    <li></li>
    <li></li>
    <li></li>
</ul>

<script type="text/x-jqote-template" id="template">
    <![CDATA[
    <%= ( ( this.n == 0 ) ?
            0 : ( this.n == 1 || this.n == 2 ) ?
                1 : parseInt($.jqote(fn, {n: this.n-1})) +
                        parseInt($.jqote(fn, {n: this.n-2})) ) %>
    ]]>
</script>

<script type="text/javascript">
    $(function() {
        var lambda = $.jqotec('#template');

        $('#fibonacci li').each(function(i) {
            $(this).text($.jqote(lambda, {n: i}));
        });
    });
</script>

$.jqotec(template[, tag]) : function

This is jQote2’s heart, its engine that powers the template parsing and lambda generation. It transforms a single template into a compiled function that – once processed – is cached internally to speed up successive usage.

You may assign the returned lambda to a variable and/or pass it to any of the before mentioned functions or let jQote2 fetch it from its internal cache for you (just pass the associated DOM element in this case).

Please note that on-the-fly template strings won’t get cached as there’s no element to associate the lambda to. Moreover, if for whatever reason you need to recompile a cached template, jQote2 makes sure to replace the cached lambda for you.

Returns

lambda : function

The compiled lambda is merely a Javascript function like any other. Once called and fired in the context of a data object the lambda returns a “stringified” representation of your template’s and data object’s merge. In most cases this will be an “HTML string”, though it could be anything that goes into a string (i.e. plain text or a JSON string etc.).

The lambda’s signature is defined as: ?(i, j, data, fn), where fn is a reference to ? (this is important when you need to have recursion within your templates).

For an explanation of what each paramter stands for, see this paragraph.

Parameters

template : jQuery object | jQuery selector |
           DOM element |
           template string

Please note that only the very first template of a set of matched templates within a supplied jQuery object (or selected by means of a jQuery selector) is chosen for compilation.

tag : string (optional)

Example

See what the lambda of above’s “Hello World” example looks like once it’s been compiled.

<pre id="lambda"></pre>

<script type="text/x-jqote-template" id="template">
    <![CDATA[
    I said <strong><*= this.greet + " " + this.who *></strong> !!!
    <* out = out.replace(/John/, 'World'); *>
    ]]>
</script>

<script type="text/javascript">
    $(function() {
        $('#lambda').text(
            $.jqotec('#template', '*').toString()
        );
    });
</script>

$.jqotefn(template) : function

jQote2 exposes its internal cache $.jqotecache and gives access to a template’s compilate by means of the its DOM element’s internal cache ID (just a plain integer starting at zero and running up). This cache ID is assigned to the template’s DOM element and may be read with elem.jqote or $(template selector)[0].jqote.

As it is a tedious task to type in $.jqotecache[$('#mytmpl')[0].jqote] over and over, you may as well just use the more convenient way: $.jqotefn('#mytmpl') !!!

Returns

lambda : function (or false if nonexistent)

Parameters

template : jQuery object | jQuery selector |
           DOM element

$.jqotetag(string) : function

Calling this function you will be able to permanently alter jQote2’s default tag char from being % to something more suitable to your needs.

Returns

void

Parameters

tag : string

You aren’t forced to have a single tag char, at all. You might just as well use some crazy ass string like ^^. Keep in mind though, that whatever char(s) you opt for you always have to prepend/append angle brackets within your templates!

jQote2 has been released. Please consider upgrading now!!! Click here for a quick summary of what’s new and what’s changed.

jQote allows you to operate on a single template as well as a collection of templates. Any template you call jQote upon will get converted using the data object you provide.

Note: Since objects are passed by reference you may easily alter the data object inside a template and have these changes carried over to the next iteration.

To make your life easier you may just as well pass an array of data objects to jQote to have your template(s) iterate over every data object provided, thus inducing n x m conversions.

$.jqote_tag(tag) : method

This may be used to change the default start- and ending tag character from % to anything you want to. Be aware that changing the tag’s char(s) this way every successive call to jQote expects the templates to be compliant to the newly set default.

Returns

void

Parameters

tag : String

$().jqote(data[, tag]) : function

Inside your templates you may use the this keyword to reference the data object’s properties. Additionally two counting variables i and j are defined (the former iterating over your templates, the latter iterating over your data objects).

You may use the optional second paramter to temporarily specify different start- and ending tag char(s). The change will overwrite the default tag char(s) just for the single call!

Returns

jQuery : object

Parameters

data : object | array of object

tag : String (optional)

Example

The infamous and obligatory “Hello World” …

Notice that this temporarily uses a different start- and ending tag char (the * star)!!!

<p id="greet"></p>

<script type="text/html" id="tmpl">
    <![CDATA[
    I said <strong><*= this.what *></strong> !!!
    ]]>
</script>

<script type="text/javascript">
    // let's do some jQote magic
    $('#tmpl').jQuote({what: 'Hello World'}, '*').appendTo($('#greet'));
</script>

Example

This example will list some names of european capitals …

<ul id="capitals"><ul>

<!-- let's define our city template -->
<script type="text/html" id="city_tmpl">
    <![CDATA[
    <li class="city">
        <%= this.name %>
        <% if ( this.info ) { %>
        <ul class="info">
            <% for ( key in this.info) %>
            <li><%= key + ': ' +  this.info[key] %></li>
            <% ; %>
        </ul>
        <% } %>
    </li>
    ]]>
</script>

<script type="text/javascript">
    var cities = [{
        name: 'Paris',
        info: { language: 'french', sight: 'tour Eiffel' }
    }, {
        name: 'Berlin',
        info: { language: 'german', sight: 'Brandenburger Tor' }
    }];

    // let's do some jQote magic
    $('#city_tmpl').jQuote(cities).appendTo($('#capitals'));
</script>

jQote2 has been released. Please consider upgrading now!!! Click here for a quick summary of what’s new and what’s changed.

jQote (pronounced like Star Trek’s Chakotey) is basically a rewrite of John Resig’s awesome JavaScript Micro-Templating utility. I took his code and ported it to jQuery, overhauled the parsing / conversion part and extended it’s functionality to minimize everyone’s coding efforts.

See the jQote API reference.

PLEASE NOTE:
Version 1.1.0 now gives you the possibility of changing the tag character to something else than <% and %>. Please referr to the jQote API reference to see how to do it.

So, let’s get started writing down a basic template:

<script type="text/html" id="template">
<![CDATA[
    <p class="greetings">
        Hello <%= this.name %>, how are you doing?
        May I offer you
        <% this.is_starving() ? %>
            some tasty peasant?
        <% : %>
            a refreshing Singha?
        <% ; %>
    </p>
]]>
</script>

This well-mannered code snippet – though it may not seem like much – shows some very special markup, namely <%= expression %> and <% statement %>, respectively (please notice the extra ‘=’ sign on the first one).

As you may have guessed already, the code in-between these tags is mere JavaScript. To simplify things you should use the <%= %> tag whenever you want to directly echo a variable’s value (you may as well call a function or use any other expression, as long as it returns a string).

Pretty self-explanatory so far, hu? But what’s with all that <script type="text/html"> and <![CDATA[ ... ]]> shmoo, you ask? Well let’s cite John Resig here:
“Embedding scripts in your page that have a unknown content-type (such is the case here – the browser doesn’t know how to execute a text/html script) are simply ignored by the browser – and by search engines and screenreaders. It’s a perfect cloaking device for sneaking templates into your page. [...]“

Good news, that is we will be able to put our template code right into our HMTL source files and it won’t show up anywhere but in the sources (btw. thanks to the usage of CDATA it’s perfectly valid markup).

Now for the final part of our little example we’ll need some basic scripting to induce the conversion:

<script type="text/javascript">
    var obj= {
        name: 'Jabberwocky',
        is_starving: function() {
            return Math.random() > 0.5;
        }
    };
    $('#template').jqote(obj).appendTo($('body'));
</script>

That’s it, there’s nothing more to it than calling jQote on our template and providing it with some data object to get things started. jQote really is fun to use and cuts down on the time spent trying to inject arbitrary data into your sites. You’ll learn to love it pretty fast, I promise! Give it a try.

One final word: I’d like to thank John Resig for bringing this up. You rock, dude.