Read to use Templates

ChocolateChip-UI provides its own template module. Templates are essential for efficiently creating markup in your app with dynamic content. There are many template engines out there. They are not all equal. In fact, some of the more famous and popular ones are down right slow. ChocolateChip-UI is not the fastest, but it’s faster than most. And it’s small and part of the framework. However, if you prefer a different template engine, you may certainly use it. This is just an option, not mandatory.

There are several ways you can create a template. You can define it as a string assigned to a variable. You can assign it to the $.templates object. You can define it inside a script tag. You could even store your templates as an external file that you import as a script tag, or though an Ajax request. Do what makes sense for you.

Creating and rendering a template is a three stage process. First you write the template. Then you must parse it. This turns the string template into a function that can output markup matched up with data passed to it. And finally you execute that parsed template function with data and output the result to the page:

// This assumes that masterData is an array// of people's first and last names.// Define the template:var masterTemplate ='<li>[[= data.firstName ]] [[= data.lastName ]]</li>';// Prase the template:var myTmpl8 = $.template(masterTemplate);// Loop through the data and output the template:
masterData.forEach(function(ctx){// Pass the current chunk of data// and output the result to the document:
$('.master ul').append(myTmpl8(ctx));});

ChocolateChip uses paris of square brackets as delimiters: [[ ... ]]. These allow you to include executable JavaScript in your templates. The following template would do nothing but launch an alert when the variable name is present:

To output a variable into your template’s markup you use an equals sign after the opening square brackets pair: [[= ... ]].

Creating Templates

The most straightforward way to create a template is to define it as a string. If the template will be more than one line, you will need to put a back space on each line, except for the last. Because of the way the parsing is done, to refer to a data variable in the template, you need to use a name as the base. The default is data. You can use any other name that makes sense for the data you are using and pass that name to the parse function as the last parameter.

Using a Script Tag as a template

As mentioned earlier, you can store you template in a script tag. To get the template, you use a selector to get the tag and then grab its text content as the template. Remember to give the tag a custom type. This will prevent the browser from showing the contents of the script tag in the document. Browsers ignore the contents of script tags with an unknown type. We recommend using ‘text/x-template’, but you can use whatever you want, as long as it is not a know type. In the example below we gave the script and id so we can easily get it.

Example

$.template.repeater

This method enables you to output a template repeatedly based on the value of an array of data. This method can take two types of arrays: simple or consisting of objects. Using other data types will throw and error. You could use either of the following types of arrays:

Behavior: By default, $.template.repeater appends its results to the target element. If you want it to replace the contents, then simple use $(selector).empty() before executing $.template.repeater()

Declarative Template Repeater

ChocolateChip-UI also provides a way to use declarative repeater templates. You do this by putting the attribute data-repeat with its value being the name of a variable of the array of data you want it to render with. Because of the way JavaScript scopes work, you need to expose the data to the template engine so that it can parse the template with it. You do this by assigning it to $.template.data:

With the template defined and our data assigned to the $.template.data object, we can invoke the repeater method. We do without passing any parameters. Every time you do so, it will search your document for declarative repeaters, so be careful to only do it when all templates have their data ready for render, because after rendering, that data gets deleted from the template data object.

// Parse any declarative repeaters:
$.template.repeater();

Note: You can keep the unrendered template of the declarative repeater from showing by putting the class “cloak” on it. You can see that class on the repeat above. This class hides the child elements of the repeater. When ChocolateChip-UI renders the repeater, it takes this class off before injecting the repetitive content into it.

$.template.index

When using a repeater, you may need to know what iteration your own, say, to output a numberic value. ChocolateChip-UI templates provides a way for you to do this using $.template.index. Like other JavaScript loop processes, it starts with 0 and increases after that. So, if you want to output numbers, you’ll need to increase them by 1. Here’s an example:

Images

If you want to have images in a declarative repeater, you need to use a special attribute for the source. At load time the browser will see the declarative template in the markup and try to parse the image’s source. If the path of the image is based on dynamic data, this will result in an error being logged in the browser’s console. You can avoid this by using data-src instead of src:

At parse time, ChocolateChip-UI will convert the data-src attribute into a src attribute.

Note: One last thing to bear in mind. Because template variables are actually JavaScript variables, you can perform any appropriate JavaScript operations directly on them. We are already doing that by increase the value of the $.template.index by 1 in each loop in the template above. Or you might want to do something such as capitalizing the last name using String.toUpperCase():