36 | 
413 |
414 |
415 | #### Template tags
416 |
417 | Tempo also supports tag blocks:
418 |
419 | {% if javascript-expression %} ... {% else %} ... {% endif %}
420 |
421 | The body of the tag will only be rendered if the JavaScript expression evaluates to true. The `{% else %}` is optional.
422 |
423 | #### Variable injection for inline scripts
424 |
425 | If you're using scripts inline in your template, you can access JSON object members. You reference these via the `__` variable.
426 |
427 | 
120 | Usage
150 | 151 | 161 |JSON
169 |Tempo takes information encoded as JSON and renders it according to an HTML template. Below is a sample array of JSON data.
170 |
171 | var data = [
172 | {'name':{'first':'Leonard','last':'Marx'},'nickname':'Chico','born':'March 21, 1887','actor': true,'solo_endeavours':[{'title':'Papa Romani'}]},
173 | {'name':{'first':'Adolph','last':'Marx'},'nickname':'Harpo','born':'November 23, 1888','actor':true,'solo_endeavours':[{'title':'Too Many Kisses','rating':'favourite'},{'title':'Stage Door Canteen'}]},
174 | {'name':{'first':'Julius Henry','last':'Marx'},'nickname':'Groucho','born': 'October 2, 1890','actor':true,'solo_endeavours':[{'title':'Copacabana'},{'title':'Mr. Music','rating':'favourite'},{'title':'Double Dynamite'}]},
175 | {'name':{'first':'Milton','last':'Marx'},'nickname':'Gummo','born':'October 23, 1892'},
176 | {'name':{'first':'Herbert','last':'Marx'},'nickname':'Zeppo','born':'February 25, 1901','actor':true,'solo_endeavours':[{'title':'A Kiss in the Dark'}]}
177 | ];
178 |
179 |
180 |
181 | JavaScript
182 |Include script
183 |You only need to include one little script.
184 |185 | <script src="js/tempo.js" type="text/javascript"></script> 186 |187 |
Tempo.prepare(element)
188 |To initialize Tempo, run the prepare() function to scan an HTML container for data templates, cache them in memory, and remove the data template HTML elements from the page. Tempo.prepare(element) returns an instance of a renderer that knows how to layout the data you provide to it.
element
191 |The ID of the HTML element (or the element itself) containing your data template. If you're using jQuery, you may pass in a jQuery object instead.
192 | 193 |If the container does not contain a default (that is without conditions and not nested) data-template the entire contents of the container will be considered to represent the template.
template.render()
196 |The Tempo.prepare() function returns an instance of a template ready for rendering. Once the JSON data is available, run the render(data) function to add the data to the page.
data
199 |The JSON data to be rendered. You'll first need to perform an AJAX call to the JSON data source (see below).
200 |201 | Tempo.prepare( element ).render( data ); 202 |203 |
204 | Tempo.prepare('marx-brothers').render(data);
205 |
206 |
207 | template.append()
208 |Renderer methods all return an instance of the renderer (a la fluent) so you can chain calls to it. The append(data) function will render the data you pass in and append it to the container.
data
211 |The JSON data to append.
212 |
213 | Tempo.prepare('marx-brothers').render( data ).append( more_brothers );
214 |
215 |
216 | template.prepend()
217 |The prepend(data) function will render the data you pass in and insert it before others in the container.
data
220 |The JSON data to prepend.
221 |
222 | Tempo.prepare('marx-brothers').render( data ).prepend( brothers_we_didnt_know_about );
223 |
224 |
225 | template.clear()
226 |The clear() function will empty the container, allowing you to render the data again.
228 | Tempo.prepare('marx-brothers').render( data ).clear();
229 |
230 |
231 | template.errors(errorHandler)
232 |Tempo will attempt to deal with errors and failures silently but you can pass in your own handler for exceptions:
233 |errorHandler
234 |A function which will be called with the error object from the try/catch block.
236 | Tempo.prepare('list').errors(function (err) {
237 | console.log('Whoa! something happened!');
238 | console.log(err);
239 | }).render(data);
240 |
241 |
242 | template.into(container)
243 |The into(element) function will allow you to render the original template to one or more different containers specified. The method will return a new template on which you can call the other template methods such as render() or append().
container
246 |The container to render the template to.
247 |Render to different container:
248 |
249 | Tempo.prepare('marx-brothers').into('alternative-container').render( data );
250 |
251 | Reuse template for multiple different containers:
252 |
253 | var template = Tempo.prepare('marx-brothers');
254 | template.into('alternative-container').render( data_1 );
255 | template.into('yet-another-alternative-container').render( data_2 );
256 |
257 |
258 |
259 |
260 | HTML
261 |data-template
262 |Any tag with the data-template attribute will be flagged as a data template.
For compliance the full (non-minimized) form is also supported: data-template="data-template".
{{fields}}
266 |Any field represented in the JSON data may be retrieved by referencing the field name inside double brackets.
267 |
268 | <ol id="marx-brothers">
269 | <li data-template>{{nickname}} {{name.last}}</li>
270 | </ol>
271 |
272 | The above example would be rendered as:
273 |-
275 |
- Chico Marx 276 |
- Harpo Marx 277 |
- Groucho Marx 278 |
- Gummo Marx 279 |
- Zeppo Marx 280 |
You can reference the object being iterated with {{.}}: 284 | 285 |
296 | <ol id="marx-brothers">
297 | <li data-template>{{.}}</li>
298 | </ol>
299 |
300 | If the JSON data represents an array of arrays (which can not be referenced by field/member name) for example:
301 | 302 |You can reference array elements with the following notation:
313 | 314 |
315 | <ol id="marx-brothers">
316 | <li data-template>{{[0]}} {{[1]}}</li>
317 | </ol>
318 |
319 |
320 | Both examples above would be rendered as:
321 |-
323 |
- Leonard Marx 324 |
- Adolph Marx 325 |
- Julius Henry Marx 326 |
- Milton Marx 327 |
- Herbert Marx 328 |
Using data from associative arrays (objects)
333 |Normally data being iterated is represented as an array of objects. In some cases however the data is a series of objects in a map:
334 | 335 |
336 | var data = {
337 | 'leonard': 'Leonard Marx',
338 | 'adolph': 'Adolph Marx',
339 | 'julius': 'Julius Henry Marx',
340 | 'milton': 'Milton Marx',
341 | 'herbert': Herbert Marx'
342 | };
343 |
344 |
345 | In this case you can iterate all the elements using the data-from-map attribute where the key name can be accessed with {{key}} and the value object via {{value}}:
348 | <ol id="list">
349 | <li data-template data-from-map>{{value}} - {{key | append '@marx.com'}}</li>
350 | </ol>
351 |
352 |
353 | Values are escaped by default
354 |All values are escaped by default. To disable automatic escaping pass in the 'escape': false parameter:
356 | Tempo.prepare('marx-brothers', {'escape': false}).render(data);
357 |
358 | If you disable escaping you can control this at individual value level using the escape and encodeURI filters.
Nested data-templates
362 |Data templates can even be nested within other data templates. Multiple nested templates are supported.
363 |
364 | <li data-template>
365 | {{nickname}} {{name.last}}
366 | <ul>
367 | <li data-template-for="solo_endeavours">{{title}}</li>
368 | </ul>
369 | </li>
370 |
371 | -
373 |
- Chico Marx
374 |
-
375 |
- Papa Romani 376 |
378 | - Harpo Marx
379 |
-
380 |
- Too Many Kisses 381 |
- Stage Door Canteen 382 |
384 | - Groucho Marx
385 |
-
386 |
- Copacabana 387 |
- Mr. Music 388 |
- Double Dynamite 389 |
391 | - Gummo Marx 392 |
- Zeppo Marx
393 |
-
394 |
- A Kiss in the Dark 395 |
397 |
You can (recursively) refer to parent objects within a nested template using the _parent variable.
402 | <li data-template-for="solo_endeavours">{{_parent.name.first}} acted in {{title}}</li>
403 |
404 |
405 |
406 | Nested Templates as Partial Template Files
407 |Tempo supports separating more complex nested templates in to master and partial template files. Partials templates are loaded on demand from the server and do require you to use the alternative asynchronous pattern:
408 |JavaScript:
409 |
410 | Tempo.prepare('marx-brothers', {}, function(template) {
411 | template.render(data);
412 | });
413 |
414 | Template:
415 |
416 | <li data-template>
417 | {{name.first}} {{name.last}}
418 | <ol>
419 | <li data-template-for="solo_endeavours" data-template-file="partials/movie.html"></li>
420 | </ol>
421 | </li>
422 |
423 | Partial ('partials/movie.html'):
424 |
425 | {{title}}
426 |
427 | -
429 |
- Chico Marx
430 |
-
431 |
- Papa Romani 432 |
434 | - Harpo Marx
435 |
-
436 |
- Too Many Kisses 437 |
- Stage Door Canteen 438 |
440 | - Groucho Marx
441 |
-
442 |
- Copacabana 443 |
- Mr. Music 444 |
- Double Dynamite 445 |
447 | - Gummo Marx 448 |
- Zeppo Marx
449 |
-
450 |
- A Kiss in the Dark 451 |
453 |
Conditional Templates
458 |Tempo provides boolean and value-based conditionals, as well as the ability to define multiple data templates per container (the first matching template wins).
459 |
460 | <ul id="marx-brothers3">
461 | <li data-template data-if-nickname="Groucho"">{{nickname}} (aka {{name.first}}) was grumpy!</li>
462 | <li data-template data-if-actor>{{name.first}}, nicknamed '<i>{{nickname}} {{name.last}}</i>' was born on {{born}}</li>
463 |
464 | <!-- Default template -->
465 | <li data-template>{{name.first}} {{name.last}} was not in any movies!</li>
466 | </ul>
467 |
468 | -
470 |
- Leonard, nicknamed 'Chico Marx' was born on March 21, 1887 471 |
- Adolph, nicknamed 'Harpo Marx' was born on November 23, 1888 472 |
- Groucho (aka Julius Henry) was grumpy! 473 |
- Milton Marx was not in any movies! 474 |
- Herbert, nicknamed 'Zeppo Marx' was born on February 25, 1901 475 |
You can define templates based on data member existence as well:
479 |
480 | <li data-template data-has="friend">{{friend}}></li>
481 |
482 |
483 |
484 | Fallback Template
485 |Use the data-template-fallback attribute to identify HTML containers you would like to show if JavaScript is disabled.
To ensure that your data template is not visible before being rendered (either because of JavaScript being disabled or due to latency retrieving the data), it's best practice to hide your templates with CSS. If you add an inline rule of style="display: none;" Tempo will simply remove the inline rule once the data has been rendered.
489 | <ul id="marx-brothers">
490 | <li data-template style="display: none;">{{nickname}} {{name.last}}</li>
491 | <li data-template-fallback>Sorry, JavaScript required!</li>
492 | </ul>
493 |
494 |
495 | If JavaScript is disabled in the browser the above example would be rendered as:
496 |-
498 |
- Sorry, JavaScript required! 499 |
Preserving other elements in the template container
504 |If the template container contains other elements that should be preserved or ignored you can mark these with the data-before-template and data-after-template attributes:
507 | <ol id="marx-brothers">
508 | <li data-before-template>...</li>
509 | <li data-template>{{name.first}} {{name.last}}</li>
510 | <li data-after-template>...</li>
511 | </ol>
512 |
513 |
514 |
515 | Filter and Formatting Functions
516 |Tempo supports a number of filter functions to modify individual values before they are rendered. Filters can be chained to apply multiple ones to the same value.
517 | 518 |{{ field | escape }}
519 | Escape HTML characters before rendering to page.
520 | 521 |{{ field | encodeURI }}
522 | Encodes a Uniform Resource Identifier (URI) by replacing certain characters with escape sequences representing the UTF-8 encoding of the character.
523 | 524 |{{ field | decodeURI }}
525 | Replaces each escape sequence in an encoded URI with the character that it represents.
526 | 527 |{{ field | truncate 25[, 'optional_suffix'] }}
528 | If the value of this field is longer than 25 characters, then truncate to the length provided. If a second argument is provided then it is used as the suffix instead of the default ellipsis (...).
529 | 530 |{{ field | format[, numberOfDecimals] }}
531 | Currently only formats numbers like 100000.25 by adding commas: 100,000.25. You can optionally specify the number of decimals to use.
532 | 533 |{{ field | default 'default value' }}
534 | If the field is undefined, or null, then show the default value specified.
535 | 536 |{{ field | date 'preset or pattern like HH:mm, DD-MM-YYYY'[, 'UTC'] }}
537 | Creates a date object from the field value, and formats according to presets, or using a date pattern. Available presets are localedate, localetime, date and time. The following pattern elements are supported:
-
539 |
YYYY or YY: year as 4 or 2 digits.
540 | MMMM, MMM, MM or M: month of the year as either full name (September), abbreviated (Sep), padded two digit number or simple integer.
541 | DD or D: day of the month.
542 | EEEE, EEE or E: day of the week as either full (Tuesday), abbreviated (Tue) or number.
543 | HH, H or h: hour of the day.
544 | mm or m: minutes of the hour.
545 | ss or s: seconds.
546 | SSS or S: milliseconds.
547 | a: AM/PM.
548 |
If you would like to use any of the format characters verbatim in the pattern then use \ to escape: {{ some_date | date '\at HH:mm' }}. In this case the a is not replaced with AM/PM. Additionally you can specify whether dates should be handled as UTC.
{{ field | replace 'regex_pattern', 'replacement' }}
552 | Replace all occurrences of the pattern (supports regular expressions) with the replacement. Replacement string can contain backreferences. See Twitter code sample for an example.
553 | 554 |{{ field | trim }}
555 | Trim any white space at the beginning or end of the value.
556 | 557 |{{ field | upper }}
558 | Change any lower case characters in the value to upper case.
559 | 560 |{{ field | lower }}
561 | Change any upper case characters in the value to lower case.
562 | 563 |{{ field | titlecase[, 'and for the'] }}
564 | Format strings to title case, with an optional blacklist of words that should not be titled (unless first in string e.g. 'the last of the mohicans' to 'The Last of the Mohicans'). See example.
565 | 566 |{{ field | append ' some suffix' }}
567 | If the field value is not empty, then append the string to the value. Helpful if you don't want the suffix to show up in the template if the field is undefined or null. Use if you need before or after the suffix.
568 | 569 |{{ field | prepend 'some prefix ' }}
570 | If the field value is not empty, then prepend the string to the value. Helpful if you don't want the prefix to show up in the template if the field is undefined or null. Use if you need before or after the prefix.
571 | 572 |{{ field | join 'separator' }}
573 | If the field is an array joins the elements into a string using the supplied separator.
574 | 575 | 576 |Attribute Setters
577 |If an HTML element attribute in a template is immediately followed by a second attribute with the same name, prefixed with data-, then as long as the second one is not empty will the value of the original be replaced with the value of the latter.
In the following example, will the reference to default_image.png be replaced by an actual field value if one exists. Notice here that the .png suffix is only added if the field is not empty.
581 | <img src="default_image.png" data-src="{{actual_image_if_exists | append '.png'}}" ... />
582 |
583 |
584 | Template Tags
585 |Tempo also supports tag blocks.
586 | 587 |{% if javascript-expression %} ... {% else %} ... {% endif %}
588 | The body of the tag will only be rendered if the JavaScript expression evaluates to true. The {% else %} is optional.
Variable injection for inline scripts
592 |If you're using scripts inline in your template, you can access JSON object members. You reference these via the __ variable.
595 | <a href="#" onclick="alert(__.nickname); return false;">{{name.last}}</a>
596 |
597 |
598 | Similarly you can reference array elements (shorthand for for __.this[0]):
599 |
600 | <a href="#" onclick="alert(__[0]); return false;">{{[0]}}</a>
601 |
602 |
603 | You can refer to the object being iterated with __.this. You can use normal dot notation to access members of that object.:
604 |
605 | <a href="#" onclick="alert(__.this); return false;">{{.}}</a>
606 |
607 |
608 | At render time the accessor variable will be replaced by the object it references. If the object is a
Pre-processing and Event Handling
612 | 613 |template.when(type, handler)
614 |After preparing a template you can register one or more event listeners by providing a callback function to be notified of events in the lifecycle.
615 | 616 |type
617 |The type of the event. Constant values are defined in TempoEvent.Types.
-
620 |
TempoEvent.Types.RENDER_STARTING: Indicates that rendering has started, or been manually triggered by callingstarting()on the renderer object.
621 | TempoEvent.Types.ITEM_RENDER_STARTING: Indicates that the rendering of a given individual item is starting.
622 | TempoEvent.Types.ITEM_RENDER_COMPLETE: Indicates that the rendering of a given individual item has completed.
623 | TempoEvent.Types.RENDER_COMPLETE: Indicates that the rendering of all items is completed.
624 | TempoEvent.Types.BEFORE_CLEAR: Fires before the container is cleared of all elements.
625 | TempoEvent.Types.AFTER_CLEAR: Fires after the container is cleared of all elements.
626 |
handler
629 |The handler function to call when the specified event fires.
630 | 631 |The event listener will be called with a single argument, a TempoEvent which has the following properties:
type
634 |The type of the event. Constant values are defined in TempoEvent.Types.
item
637 |The item being rendered. This is only available for the ITEM_RENDER_STARTING and ITEM_RENDER_COMPLETE events.
element
640 |The HTML element or template being used for rendering. This is only available for the ITEM_RENDER_STARTING and ITEM_RENDER_COMPLETE events.
643 | Tempo.prepare('tweets').when(TempoEvent.Types.RENDER_STARTING, function (event) {
644 | $('#tweets').addClass('loading');
645 | }).when(TempoEvent.Types.RENDER_COMPLETE, function (event) {
646 | $('#tweets').removeClass('loading');
647 | }).render(data);
648 |
649 |
650 | Even though it's possible to modify the DOM via event handlers it's worth keeping in mind that Tempo is built on the premise of keeping the templates as semantic and readable as possible. We would therefore advise that you limit the use or pre-processing to data cleansing and restructuring as opposed to template modifications.
651 | 652 |starting()
653 |In some cases you prepare the templates ahead of calling render. In those cases if you would like to e.g. set loader graphics, call the renderer's starting() method just prior to issuing e.g. a jQuery request. This will fire the ITEM_RENDER_STARTING event.
The following example demonstrates use of both methods above. In this case we prepare the templates, and register our event handler function. The event handler is then notified that the jQuery request is about to be issued (when we manually fire RENDER_STARTING with a call to starting()) adding a CSS class to the container. We are then notified that rendering is complete so we can remove the CSS class.
656 |
657 |
658 | var twitter = Tempo.prepare('tweets').when(TempoEvent.Types.RENDER_STARTING, function (event) {
659 | $('#tweets').addClass('loading');
660 | }).when(TempoEvent.Types.RENDER_COMPLETE, function (event) {
661 | $('#tweets').removeClass('loading');
662 | });
663 | twitter.starting();
664 | $.getJSON(url, function(data) {
665 | twitter.render(data.results);
666 | });
667 |
668 |
669 |
670 | Using Tempo with jQuery
671 |jQuery's getJSON() method provides an easy means of loading JSON-encoded data from the server using a GET HTTP request.
672 |
673 | var twitter = Tempo.prepare('tweets');
674 | $.getJSON("http://search.twitter.com/search.json?q='marx brothers'&callback=?", function(data) {
675 | twitter.render(data.results);
676 | });
677 |
678 | Binding event handlers
679 |
680 | Note that if you've bound event listeners to elements in your template, these will not be cloned when the template is used. In order to do this you have two options.
681 |
683 | You can either leave binding until the data has been rendered, e.g. by registering a TempoEvent.Types.RENDER_COMPLETE listener and doing the binding when that fires, or you can use jQuery live which attaches a handler to elements even though they haven't been created.
684 |
686 | The following example shows how to make a template clickable (assuming an 'ol li' selector provides a reference to a template element) and how to obtain a reference to the clicked element:
687 |
689 | $('ol li').live('click', function() {
690 | // Do something with the clicked element
691 | alert(this);
692 | });
693 |
694 |
695 |
696 | Advanced Topics
697 | 698 | 699 |Configuring the surrounding brace syntax
700 |
701 | In order to make it easier to use Tempo with other frameworks such as Django, you can configure Tempo to use surrounding braces other than the default {{ ... }} and {% ... %}.
702 |
704 | To do this you pass the var_braces and tag_braces parameters to the Tempo.prepare function. These will be split down the middle to form the left and right braces.
705 |
707 | Tempo.prepare('marx-brothers', {'var_braces' : '\\[\\[\\]\\]', 'tag_braces' : '\\[\\?\\?\\]'});
708 |
709 | You can now use this template syntax instead:
710 |711 | <ol id="marx-brothers"> 712 | <li data-template>[[nickname]] is [? if nickname == 'Groucho' ?]grouchy[? else ?]happy[? endif ?]!</li> 713 | </ol> 714 |715 | 716 |
Tempo Renderer Information - the _tempo variable
717 | You can access information about the rendering process via the _tempo variable.
_tempo.index
720 |The index variable tells you how many iterations of a given template have been carried out. This is a zero (0) based index. Nested templates have a separate counter.
721 |
The following example adds the iteration count to the class attribute, prefixed with 'item-':
723 | <ol id="marx-brothers" class="item-{{_tempo.index}}">
724 | <li data-template>{{nickname}} {{name.last}}</li>
725 | </ol>
726 |
727 | This example shows how to access the iteration counter using inline JavaScript injection:
728 |
729 | <a href="#" onclick="alert(__._tempo.index); return false;">{{name.last}}</a>
730 |
731 |
732 | _tempo.first
733 |True if the item being iterated is the first one in the collection.
734 | 735 |_tempo.last
736 |True if the item being iterated is the last one in the collection.
737 | 738 |