pure.js - Javascript Template Engine

Write your templates in pure HTML

Clean of any inline logic or special tags
CSS selectors are used to bridge the HTML with Javascript actions
Providing a radical separation between the representation and the logic

Here we explain why we did pure.js back in 2008
And you can ask your questions to the user group

Download pure.js on Github

We have been happily using pure.js since 2008 for our own web app, BeeBole Timesheet
Why don't you try it too?

Where to use pure.js?

pure.js can be used where Javascript and DOM are available
It can be run server side, but shines client side

If a Javascript library is present in the page( jQuery, dojo, domassistant, mootools, prototype, sizzle or sly )
pure.js will automatically extend it with the method described here below.

Here is a simple example

The template:

How to render it:

The result:

Directive

A directive, is the instruction you give to render a template
It is a JSON object, with the format {CSS_selector: action}
pure.js will do that action on the node matching the CSS_selector

Actions you can use in a directive

Here are the type of actions you can do on HTML nodes and attributes:

  • Assign the text value of a node

    { 'a': 'who' }
    Will assign the value of the property who from the JSON data, to the text of the a tag

  • Assign the value of a node attribute

    To assign the value of an attribute, we use @ at the end of the selector
    { 'a@href': 'url' }
    Will assign the value of the property url from JSON data, to the href of the a tag

  • Make a loop

    Using <- in a directive, we can repeat a node

    From the HTML template: And the data: This directive: Will repeat the LI tag, for each entry in the array animals
    Naming an internal variable called animal
    Then will look for a span and fill it with the name of the animal

    Unnamed Array

    If your data is not an object but directly an array, like this: There is no property name for the array, thus use directly nameOfItem<-

  • Using a javascript function

    You can use a Javascript function as the action
    This brings you all the flexibility of Javascript to render your templates The function will be called at render time, and return the value of the property name as the text value of the span
    this inside such function, can either be the root of your JSON data
    Or will represent the current element, if you are inside a loop

    An argument is passed to that function, called a here below:

    It is an object with the following properties:
    • context : This is the full JSON that was passed for transformation
    • item* : the current loop item
    • items * : all the items of the loop
    • pos * : the current position in the loop. An integer when iterating an array, a property name iterating on a collection

    *The last 3 properties(*) are only present when the directive is inside a loop

The methods of the object $p

When you load pure.js in your page, a global variable called $p is available

Here is a description of its methods:

  • compile

    $p( selector ).compile( directive )

    compile takes an HTML node found by selector and returns a Javacript function
    Provide your JSON data as the argument of that function, and you will get a string of the HTML result In the example above, the HTML string is injected as the innerHTML of the node found on the selector .result

  • render

    $p( selector ).render( data, directive | compiledFunction )

    render takes the JSON data, and a directive(or its compiled function) as arguments
    And replace the node found on selector

    Here above, the node found by the selector .result, will be replaced by the new HTML

    Note: If you plan to render multiple times a template, eg: when the data change, you must use the compiled version instead of using the directive

  • autoRender

    $p( selector ).autoRender( data )

    autoRender automatically maps the JSON data to the class attributes in the HTML
    There is no need to give directive for the rendering

    In the example above, there are two classes for the A tag
    who will give the value of its text
    While site@href will put the value of site as its href attribute

    Note: If the property is an array, the node will be repeated

    Consider autoRender just for basic rendering. You can't format or use functions with it
    In addition, if forces you to have a relative coherence between both structures( your data and the HTML )
    A directive allows a better abstraction

  • Use your favorite Javascript library

    pure.js detects if you are using a JS framework in the same page(dojo, domassistant, jquery, mootools, prototype, sizzle or sly) and adds automatically the 3 methods above to your familiar environment

    i.e: with jQuery, you can render a template by calling $( selector ).render( data, directive )

Special notations in a directive

We tried to keep the syntax minimal and standard
Using only HTML, CSS selectors and JSON
However some additional notations were introduced to cover some specific cases.

Here they are:

  1. Access the current node repeated in a loop using a . ( dot ) as the selector

    A node that you repeat may be empty. To access its node text value, you can use the . as the selector

  2. Prepend or append to a current value by using +

    By default, a selected node text or attribute will be replaced by the value coming from the data
    The + is useful if you want to keep the existing value of the node text or attribute, and just add something before or after it

    The directive below will append the value of the property email
    And put it as the href attribute of the node matching the selector .email

  3. Concatenate multiple values using #{ ... }

    The directive below will concatenate the properties site and page separated by a /
    Then set the href attribute of the node matching the selector .site

  4. How to sort a loop

    The "a" and "b" parameters are items of the array
    The function will be used as a usual Array.sort( function( a, b ){ ... }) style

    The "sort" function will work only when you loop on an array.
    If you add a sort function on an object properties loop, pure.js will throw an exception.

  5. How to filter out rows from a loop

    The a parameter of the function is the same object that is passed to loops directive functions( with the properties context, pos, item, items )
    In the example above only the items with a name starting with "a" or "A" will be kept
    If the function returns true the item is kept, if false the item won't be rendered

    The filter works on both arrays and object properties loops

    Notes: a.pos will continue to indicate the current index of the innermost loop, even if items are skipped
    The node to loop must have a parent node, the template root can't be looped

Copyright © 2018 BeeBole