Jsrender

JsRender: best-of-breed templating

Simple and intuitive, powerful and extensible, lightning fast

For templated content in the browser or on Node.js (with Express 4, Hapi and Browserify integration)

JsRender is a light-weight but powerful templating engine, highly extensible, and optimized for high-performance rendering, without DOM dependency. It is designed for use in the browser or on Node.js, with or without jQuery.

JsRender and JsViews together provide the next-generation implementation of the official jQuery plugins JQuery Templates, and JQuery Data Link -- and supersede those libraries.

Documentation and downloads

Documentation, downloads, samples and API docs and tutorials are available on the www.jsviews.com website.

The content of this ReadMe is available also as a JsRender Quickstart.

JsRender and JsViews

JsRender is used for data-driven rendering of templates to strings, ready for insertion in the DOM.

It is also used by the JsViews platform, which adds data binding to JsRender templates, and provides a fully-fledged MVVM platform for easily creating interactive data-driven single page apps and websites.

JsRender installation

jsrender.js is available from downloads on the jsviews.com site.

CDN delivery is available from the jsdelivr CDN at jsdelivr.com/package/npm/jsrender, and from the cdnjs CDN at cdnjs.com/libraries/jsrender. Alternatively:

• It can be installed with Bower, using $ bower install jsrender
• It can be loaded using an AMD script loader, such as RequireJS
• For installation using Node.js (npm) see JsRender Node.js Quickstart
• (For browser loading using Browserify or webpack - see JsRender Node.js Quickstart, JsRender as a Browserify module and JsRender as a webpack module)

Using JsRender with jQuery

When jQuery is present, JsRender loads as a jQuery plugin and adds $.views, $.templates and $.render to the jQuery namespace object, $ (or window.jQuery).

Example HTML page: JsRender with jQuery

Using JsRender without jQuery

When jQuery is not present, JsRender provides its own global namespace object: jsrender (or window.jsrender)

The jsrender namespace provides the same methods/APIs as with jQuery, so if jQuery is not present you can still use all the API examples, by simply writing:

var $ = window.jsrender;

// Now use code as in samples/examples, with $.views... $.templates... $.render...

(Note: If jQuery is not loaded, then passing a jQuery selector to $.templates() will only work for the ID selector)

Example HTML page: JsRender without jQuery

JsRender on Node.js

JsRender can be used to render templates on the server (using Node.js) as well as in the browser. JsRender on Node.js has all the features and APIs of JsRender in the browser, plus some additional ones specific to Node.js.

It also provides built-in Express, Hapi and Browserify integration -- which makes it easy to register templates as simple .html files on the file system, and then load and render them either server-side, client-side or both.

Learn more: JsRender Node.js Quickstart and JsRender APIs for Node.js.

Code samples: See JsRender Node Starter for running code examples of Node.js scenarios, including with Express, Hapi and Browserify.

JsRender usage

Define a template

From a string:

var tmpl = $.templates("Name: {{:name}}");

From a template declared as markup in a script block:

<script id="myTemplate" type="text/x-jsrender">
Name: {{:name}}
</script>

then, somewhere in your script:

var tmpl = $.templates("#myTemplate"); // Pass in a jQuery selector for the script block

On Node.js, from an .html file containing the template markup:

var $ = require('jsrender'); // returns the jsrender namespace object
var tmpl = $.templates("./templates/myTemplate.html");

Learn more...

Render a template

tmpl.render(object) (or shortcut form: tmpl(object)) renders the template with the object as data context.

var tmpl = $.templates(" Name: {{:name}}<br/> ");

var person = {name: "Jim"};

// Render template for person object
var html = tmpl.render(person); // ready for insertion, e.g $("#result").html(html);

// result: "Name: Jim<br/> "

tmpl.render(array) (or tmpl(array)) renders the template once for each item in the array.

var people = [{name: "Jim"}, {name: "Pedro"}];

// Render template for people array
var html = tmpl.render(people); // ready for insertion...

// result: "Name: Jim<br/> Name: Pedro<br/> "

Learn more...

Register a named template - and render it

// Register named template - "myTmpl1
$.templates("myTmpl1", "Name: {{:name}}<br/> ");

var person = {name: "Jim"};

// Render named template
var html = $.templates.myTmpl1(person);

// Alternative syntax: var html = $.render.myTmpl1(person);

// result: "Name: Jim<br/> "

Learn more...

Template tags

Template tag syntax

• All tags other than {{: ...}} {{> ...}} {{* ...}} {{!-- --}} behave as block tags

• Block tags can have content, unless they use the self-closing syntax:

  • Block tag - with content: {{someTag ...}} content {{/someTag}}
  • Self-closing tag - no content (empty): {{someTag .../}}

• A particular case of self-closing syntax is when any block tag uses the named parameter tmpl=... to reference an external template, which then replaces what would have been the block content:

  • Self-closing block tag referencing an external template: {{someTag ... tmpl=.../}} (This lets you do template composition. See example.)

• Tags can take both unnamed arguments and named parameters:

  • {{someTag argument1 param1=...}} content {{/someTag}}
  • an example of a named parameter is the tmpl=... parameter mentioned above
  • arguments and named parameters can be assigned values from simple data-paths such as address.street or from richer expressions such as product.quantity * 3.1 / 4.5, or name.toUpperCase()

Learn more...

Built-in tags

{{: ...}} (Evaluate)

{{: pathOrExpr}} inserts the value of the path or expression.

var data = {address: {street: "Main Street"} };
var tmpl = $.templates("<b>Street:</b> {{:address.street}}");
var html = tmpl.render(data);

// result: "<b>Street:</b> Main Street"

Learn more...

{{> ...}} (HTML-encode)

{{> pathOrExpr}} inserts the HTML-encoded value of the path or expression.

var data = {condition: "a < b"};
var tmpl = $.templates("<b>Formula:</b> {{>condition}}");
var html = tmpl.render(data);

// result: "<b>Formula:</b> a &lt; b"

Learn more...

{{include ...}} (Template composition - partials)

{{include pathOrExpr}}...{{/include}}evaluates the block content against a specified/modified data context.

{{include ... tmpl=.../}} evaluates the specified template against an (optionally modified) context, and inserts the result. (Template composition).

var data = {name: "Jim", address: {street: "Main Street"} };

// Register two named templates
$.templates({
  streetTmpl: "<i>{{:street}}</i>",
  addressTmpl: "{{:name}}'s address is {{include address tmpl='streetTmpl'/}}."
});

// Render outer template
var html = $.templates.addressTmpl(data);

// result: "Jim's address is <i>Main Street</i>"

Learn more...

{{for ...}} (Template composition, with iteration over arrays)

{{for pathOrExpr}}...{{/for}}evaluates the block content against a specified data context. If the new data context is an array, it iterates over the array, renders the block content with each data item as context, and concatenates the result.

{{for pathOrExpr tmpl=.../}} evaluates the specified template against a data context. If the new data context is an array, it iterates over the array, renders the template with each data item as context, and concatenates the result.

<script id="peopleTmpl" type="text/x-jsrender">
  <ul>{{for people}}
    <li>Name: {{:name}}</li>
  {{/for}}</ul>
</script>

var data = {people: [{name: "Jim"}, {name: "Pedro"}] };
var tmpl = $.templates("#peo