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 bothopen
andclose
delimiter keys and values.-
default:
open
:'<%'
close
:'%>'
-
default: