- Notifications
You must be signed in to change notification settings - Fork0
< 1KB lightweight, fast & powerful JavaScript templating engine with zero dependencies. Compatible with server-side environments like node.js, module loaders like RequireJS and all web browsers.
mikeymike/JavaScript-Templates
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Include the (minified) JavaScript Templates script in your HTML markup:
<scriptsrc="tmpl.min.js"></script>
Add a script section with type"text/x-tmpl", a uniqueid property and your template definition as content:
<scripttype="text/x-tmpl"id="tmpl-demo"><h3>{%=o.title%}</h3><p>Releasedunderthe<ahref="{%=o.license.url%}">{%=o.license.name%}</a>.</p><h4>Features</h4><ul>{%for(vari=0;i<o.features.length;i++){%}<li>{%=o.features[i]%}</li>{%}%}</ul></script>
"o" (the lowercase letter) is a reference to the data parameter of the template function (see the API section on how to modify this identifier).
In your application code, create a JavaScript object to use as data for the template:
vardata={"title":"JavaScript Templates","license":{"name":"MIT license","url":"http://www.opensource.org/licenses/MIT"},"features":["lightweight & fast","powerful","zero dependencies"]};
In a real application, this data could be the result of retrieving aJSON resource.
Render the result by calling thetmpl() method with the id of the template and the data object as arguments:
document.getElementById("result").innerHTML=tmpl("tmpl-demo",data);
The following is an example how to use the JavaScript Templates engine on the server-side withnode.js.
Create a new directory and add thetmpl.js file. Or alternatively, install theblueimp-tmpl package withnpm:
npm install blueimp-tmpl
Add a filetemplate.html with the following content:
<!DOCTYPE HTML><title>{%=o.title%}</title><h3><ahref="{%=o.url%}">{%=o.title%}</a></h3><h4>Features</h4><ul>{% for (var i=0; i<o.features.length;i++){%}<li>{%=o.features[i]%}</li>{% } %}</ul>
Add a fileserver.js with the following content:
require("http").createServer(function(req,res){varfs=require("fs"),// The tmpl module exports the tmpl() function:tmpl=require("./tmpl").tmpl,// Use the following version if you installed the package with npm:// tmpl = require("blueimp-tmpl").tmpl,// Sample data:data={"title":"JavaScript Templates","url":"https://github.com/blueimp/JavaScript-Templates","features":["lightweight & fast","powerful","zero dependencies"]};// Override the template loading method:tmpl.load=function(id){varfilename=id+".html";console.log("Loading "+filename);returnfs.readFileSync(filename,"utf8");};res.writeHead(200,{"Content-Type":"text/x-tmpl"});// Render the content:res.end(tmpl("template",data));}).listen(8080,"localhost");console.log("Server running at http://localhost:8080/");
Run the application with the following command:
node server.js
The JavaScript Templates script has zero dependencies.
Thetmpl() function is added to the globalwindow object and can be called as global function:
varresult=tmpl("tmpl-demo",data);
Thetmpl() function can be called with the id of a template, or with a template string:
varresult=tmpl("<h3>{%=o.title%}</h3>",data);
If called without second argument,tmpl() returns a reusable template function:
varfunc=tmpl("<h3>{%=o.title%}</h3>");document.getElementById("result").innerHTML=func(data);
Templates loaded by id are cached in the maptmpl.cache:
varfunc=tmpl("tmpl-demo"),// Loads and parses the templatecached=typeoftmpl.cache["tmpl-demo"]==="function",// trueresult=tmpl("tmpl-demo",data);// Uses cached template functiontmpl.cache["tmpl-demo"]=null;result=tmpl("tmpl-demo",data);// Loads and parses the template again
The methodtmpl.encode is used to escape HTML special characters in the template output:
varoutput=tmpl.encode("<>&\"'\x00");// Renders "<>&"'"
tmpl.encode makes use of the regular expressiontmpl.encReg and the encoding maptmpl.encMap to match and replace special characters, which can be modified to change the behavior of the output encoding.
Strings matched by the regular expression, but not found in the encoding map are removed from the output. This allows for example to automatically trim input values (removing whitespace from the start and end of the string):
tmpl.encReg=/(^\s+)|(\s+$)|[<>&"'\x00]/g;varoutput=tmpl.encode(" Banana! ");// Renders "Banana" (without whitespace)
The local variables available inside the templates are the following:
- o: The data object given as parameter to the template function (see the next section on how to modify the parameter name).
- tmpl: A reference to thetmpl function object.
- _s: The string for the rendered result content.
- _e: A reference to thetmpl.encode method.
- print: Helper function to add content to the rendered result string.
- include: Helper function to include the return value of a different template in the result.
To introduce additional local helper variables, the stringtmpl.helper can be extended. The following adds a convenience function forconsole.log and a streaming function, that streams the template rendering result back to the callback argument (note the comma at the beginning of each variable declaration):
tmpl.helper+=",log=function(){console.log.apply(console, arguments)}"+",st='',stream=function(cb){var l=st.length;st=_s;cb( _s.slice(l));}";
Those new helper functions could be used to stream the template contents to the console output:
<scripttype="text/x-tmpl"id="tmpl-demo"><h3>{%=o.title%}</h3>{%stream(log);%}<p>Released under the<ahref="{%=o.license.url%}">{%=o.license.name%}</a>.</p>{%stream(log);%}<h4>Features</h4><ul>{%stream(log);%}{%for(vari=0;i<o.features.length;i++){%}<li>{%=o.features[i]%}</li>{%stream(log);%}{%}%}</ul>{%stream(log);%}</script>
The generated template functions accept one argument, which is the data object given to thetmpl(id, data) function. This argument is available inside the template definitions as parametero (the lowercase letter).
The argument name can be modified by overridingtmpl.arg:
tmpl.arg="p";// Renders "<h3>JavaScript Templates</h3>":varresult=tmpl("<h3>{%=p.title%}</h3>",{title:"JavaScript Templates"});
The template contents are matched and replaced using the regular expressiontmpl.regexp and the replacement functiontmpl.func. The replacement function operates based on theparenthesized submatch strings.
To use different tags for the template syntax, overridetmpl.regexp with a modified regular expression, by exchanging all occurrences of "{%" and "%}", e.g. with "[%" and "%]":
tmpl.regexp=/([\s'\\])(?![^%]*%\])|(?:\[%(=|#)([\s\S]+?)%\])|(\[%)|(%\])/g;
By default, the plugin preserves whitespace (newlines, carriage returns, tabs and spaces). To strip unnecessary whitespace, you can override thetmpl.func function, e.g. with the following code:
varoriginalFunc=tmpl.func;tmpl.func=function(s,p1,p2,p3,p4,p5,offset,str){if(p1&&/\s/.test(p1)){if(!offset||/\s/.test(str.charAt(offset-1))||/^\s+$/g.test(str.slice(offset))){return'';}return' ';}returnoriginalFunc.apply(tmpl,arguments);};
Print variable with HTML special characters escaped:
<h3>{%=o.title%}</h3>
Print variable without escaping:
<h3>{%#o.user_id%}</h3>
Print output of function calls:
<ahref="{%=encodeURI(o.url)%}">Website</a>
Use dot notation to print nested properties:
<strong>{%=o.author.name%}</strong>
Note that the JavaScript Templates engine printsfalsy values as empty strings.
That is,undefined,null,false,0 andNaN will all be converted to''.
To be able to print e.g. the number 0, convert it to a String before using it as an output variable:
<h3>{%=0+''%}</h3>
Useprint(str) to add escaped content to the output:
<span>Year: {% var d=new Date(); print(d.getFullYear()); %}</span>
Useprint(str, true) to add unescaped content to the output:
<span>{% print("Fast & powerful", true); %}</span>
Useinclude(str, obj) to include content from a different template:
<div>{% include('tmpl-link', {name: "Website", url: "http://example.org"}); %}</div>
If else condition:
{% if (o.author.url) { %}<ahref="{%=encodeURI(o.author.url)%}">{%=o.author.name%}</a>{% } else { %}<em>No author url.</em>{% } %}For loop:
<ul>{% for (var i=0; i<o.features.length;i++){%}<li>{%=o.features[i]%}</li>{% } %}</ul>
The JavaScript Templates project comes with a compilation script, that allows you to compile your templates into JavaScript code and combine them with a minimal Templates runtime into one minified JavaScript file.
The compilation script is built fornode.js and also requiresUglifyJS.
To use it, first install both the JavaScript Templates project and UglifyJS vianpm:
npm install uglify-jsnpm install blueimp-tmpl
This will put the executablesuglifyjs andtmpl.js into the foldernode_modules/.bin. It will also make them available on your PATH if you install the packages globally (by adding the-g flag to the install command).
Thetmpl.js executable accepts the paths to one or multiple template files as command line arguments and prints the generated JavaScript code to the console output. The following command line shows you how to store the generated code in a new JavaScript file that can be included in your project:
tmpl.js templates/upload.html templates/download.html> tmpl.min.jsThe files given as command line arguments totmpl.js can either be pure template files or HTML documents with embedded template script sections. For the pure template files, the file names (without extension) serve as template ids.
The generated file can be included in your project as a replacement for the originaltmpl.js runtime. It provides you with the same API and provides atmpl(id, data) function that accepts the id of one of your templates as first and a data object as optional second parameter.
The JavaScript Templates script is released under theMIT license.
About
< 1KB lightweight, fast & powerful JavaScript templating engine with zero dependencies. Compatible with server-side environments like node.js, module loaders like RequireJS and all web browsers.
Resources
Uh oh!
There was an error while loading.Please reload this page.