template JavaScript API Module

Ben Tiedt — Fri, 08 Mar 2024 17:51:11 GMT

Current Revision posted to API Documentation by Ben Tiedt on 03/08/2024 17:51:11

jQuery.telligent.evolution.template

The template module provides a simple client-side templating. This is useful when building UI from REST responses or other cases when it's impractical to render UI in the widget on the server side.

Usage

Defining a template

Client templates can be defined either as plain JavaScript strings or embedded in HTML rendered by a widget. When rendering in HTML, the template should be defined in a script block of type text/html.

<script type="text/html" id="hello">
    <p>Hello, <%: name %>.</p>
</script>

Delimiters in the template support rendering (and optionally encoding) variables as well as embedding JavaScript logic.

The delimiter format <%= value %> renders a variable without encoding:

<p>This variable will be rendered directly without encoding <%= variableName %></p>

The delimiter format <%: value %> renders a variable after HTML-encoding it:

<p>This variable will be rendered with HTML encoding <%: variableName %></p>

The delimiter format <% %> renders nothing but allows embedding of raw JavaScript logic.

<div>
    <% if (answered) { %>
        <span class="answered">Answered</span>
    <% } else { %>
        <span class="not-answered">Not Answered</span>
    <% } %>
</div>

Looping can be performed with the template helper, foreach

<ul>
    <% foreach(users, function(user){ %>
        <li>
            <a href="<%: user.profileUrl %>">
                <%= user.displayName %>
            </a>
        </li>
    <% }); %>
</ul>

Using the template

To use a template, it must first be compiled. This transforms it from a string into an efficient function which can be passed data to template, returning a rendered string.

// given a <script type="text/html" id="hello-world"> ... </script>
var helloWorldTemplate = $.telligent.evolution.template.compile('hello-world');

// alternatively, a raw template string can be passed to compile
var helloWorldTemplate = $.telligent.evolution.template.compile('<p>Hello <%: name %></p>');

The compiled template can then be efficiently used (and re-used) by passing data to template. The data must contain keys that match those contained in the template. In this case, the template can refer to a variable named 'name'.

var renderedHello = helloWorldTemplate({
    name: 'Rob'
});

Arrays can be passed as well. In this case, a template's foreach could iterate over 'users'.

var renderedUserList = user({
    users: [
        { displayName: 'Name1', profileUrl: 'url1' },
        { displayName: 'Name2', profileUrl: 'url3' },
        { displayName: 'Name3', profileUrl: 'url3' }
    ]
});

Customizing template syntax

foreach is a platform-defined template helper. Custom helpers can also be defined by passing an object of functions during compilation.

var myTemplate = $.telligent.evolution.template.compile('myTemplate', {
    pluralize: function(raw) {
        // naive pluralization demonstration
        return raw + 's';
    }
});

Then the helper can be used within the template

<script type="text/html" id="myTemplate">
    <ul>
        <% foreach(vehicles, function(vehicle) { %>
            <li>type: <%= pluralize(vehicle.type) %><%>
        <% }); %>
    </ul>
</script>

Methods

compile

Transforms a template string into an efficient JavaScript function which can process data into a rendered string.

$.telligent.evolution.template.compile(template, extraHelpers, delimiters)

template: Either a raw JavaScript template string, or an ID of a <script type="text/html"> element containing an embedded template.
extraHelpers: Optional functions made available for use within the template
delimiters: Optional object containing overrides for re-defining what delimiter formats are used. Override object must contain both open and close delimiter keys and values.
- default:
  - open: '<%'
  - close: '%>'