templateJS - Lightweight JavaScript Template Engine

templateJS, born for iDocSet 6.0 which supports listing API documents from Guides and Sample Code docset.

In theory, templateJS is just a translator, which translate template source to JavaScript codes, then run these codes to output expected results.

A template engine does this:

Template + Data Modal = Result

One simple but not so simple example

Template

<script type="text/template" id="test-template">
<h3><@= o.title @></h3>
<ol>
<@ for (var i = 0; i < o.features.length; i++) {
     var item = o.features[i]; @>
<li><@= item.name @> <@ if (item.desc) { out += '<i>' + item.desc + '</i>'; } @></li>
<@ } @>
</ol>
<p><b><@= o.author @></b></p>
</script>

Note: this template first output title, then output features using for loop, and finally output author information. It also use out stream to output feature description.

Data Modal

var data = { 
  title: 'templateJS: lightweight JavaScript Template Engine',
  features: [
    { name: 'Build with pure JavaScript' },
    { name: 'Lightweight and Fast', desc: 'less than 600 bytes' },
    { name: 'Simple and Ease of use' }
  ],
  author: 'zhsoft88@icloud.com'
};

Note: use JavaScript Object or JSON to define data modal.

Make Template

var source = document.getElementById('test-template').innerText;
var tmpl = new Template(source);

Note: source is template contents, use new Template to create a reusable template object - tmpl.

Render

var result = tmpl.render(data);

Result:

<h3>templateJS: lightweight JavaScript Template Engine</h3>
<ol>

<li>Build with pure JavaScript </li>

<li>Lightweight and Fast <i>less than 600 bytes</i></li>

<li>Simple and Ease of use </li>

</ol>
<p><b>zhsoft88@icloud.com</b></p>

Template Language Guide

1. <@= JavaScript_Expression @>

Reference a value of JavaScript expression

2. <@ Any_JavaScript_Codes @>

You can write any JavaScript statements between <@ and @>

3. o

Use o to reference the data modal object

4. out

Use out to reference template output stream. Use out += ... to append results to template output stream.

5. Refer template source

Just use string:

var tmpl = new Template('<h3><@= o.title @></h3>...');

Note: some characters (such as newline, quotes) in string should be correctly escaped.

You can also put template source to a script node which has id attribute and its type attribute's value is "text/template", then use document.getElementById and innerText function to fetch it.

<script type="text/template" id="template-id">
.....
</script>

Note: No escape needed, but requires DOM, maybe runs in browser only.

Want to use templateJS in macOS/iOS Apps? No problem.

Link with JavaScriptCore Framework, bind a helper object in JSContext, then use specific method of helper object to fetch template source：

1) Declare protocol, which conforms to JSExport.

@protocol ZHTHelperExport <JSExport>

- (NSString*)getTemplateSourceById:(NSString*)id;

@end

2) Write a class, such as ZHTHelperImpl, implements ZHTHelperExport protocol.

@interface ZHTHelperImpl : NSObject<ZHTHelperExport>
@end

@implementation ZHTHelperImpl

- (NSString*) getTemplateSourceById:(NSString*)id {
  ...
}

@end

3) Bind helper object and get template source.

JSContext* context = ...;
context[@"helper"] = [ZHTHelperImpl new];
[context evaluateScript:@"var source = helper.getTemplateSourceById('test-template');"];

A simple templateJS test page - test-templateJS.html

GitHub: - https://github.com/zhsoft88/templateJS