type: utility

release: 0.0

status: in planning

TODOs

• Specify syntax for nesting tags, if any
• Specify how the implicit context works
• On top level, within a block tag...
• Will context be in issue inside of an #each, in terms of only having access to the current item being iterated, and not also the parent context it came from? 

For a comparative study of template engines and implementations, see Template-Comparison.

1 - Description:

A template language is a domain-specific language for creating content in an output language by mixing data with snippets of the output language that contain embedded flow control.  In other words, a template is a way of specifying a function that produces a string in the output language (either in string or AST form) from a bundle of data using a syntax that is reminiscent of the output produced.

Existing HTML template implementations usable by JavaScript/jQuery apps include:

• jquery-tmpl
• see in-progress optimized version for 'pure string rendering':  JsRender
• and templated-data-linked views - e.g. for editable data scenarios (requires JsRender): JsViews 
• KiTE
• mustache.js
• Tempo
• Handlebars
• Dust.js
• ICanHaz.js
• PURE
• Closure Templates
• jQuery View
• Nano
• jQote2
• Underscore.js template
• doT.js
• Tim
• Liquid.js 

Some discussion well worth reading on escaping: Using type inference to make web templates robust against XSS

For a potential grammar, semantics of directives an more, see Template-Strawman.

2 - Visual Design:

N/A

3 - Functional Specifications/Requirements:

Informal spec:

• Fast: Compilation and rendering performance should be reasonably close to existing fast templating engines such as doT, jQote2 and underscore.js. 
• Text-centric rather than DOM dependent. Primarily produces strings, creating DOM objects is a convenience method.
• This allows use of this template engine in server side javascript environments, e.g. node.js and rhino. Currently JsRender and Strappend both retain dependency on jQuery, however, and jQuery itself has DOM dependencies, and is not generally available in server contexts. They could both be made available in non-jQuery-dependent versions. The client versions could continue to depend on jQuery and provide jQuery plugin APIs such as $( "#my-tmpl" ).tmpl( model ).
• Dot.notation: Allow access to nested properties.
• Non-jQuery Namespace? We think about using an totally independent namespace, such as jqTemplate.*** for when we include this library on a non-DOM/jQuery context.   
• Status: JsRender and Strappend depends on jQuery (e.g. $.each). TODO: Create a conformance suite mode that does not load jquery.   

Proposal, using Tmpl (pronounced temple) as the name placeholder:

Arguments:

• name: String, name to use for registering a template or retrieving registered templates
• template: String, template content to compile or render
• data: Object, data to use for rendering a template  

Base Library methods:

• Tmpl(template)
• returns an object with register and render method 
• Tmpl("Title: {{=title}}").register("movie")
• Tmpl("Title: {{=title}}").render(movie) 
• Tmpl.templates[name].render(data)
• access a template by name, call it's render method
• Tmpl.templates.movie.render(movie)
• Tmpl(template, data)
• take a template, render it with the given data, no registration step
• Tmpl("Title: {{=title}}", movie)

Adding custom tags:

• Tmpl.addTag(name, callback)
• adds a new custom tag available to all templates
• TODO what's the callback's signature? 
• Tmpl.templates[name].addTag(name, callback)
• Add a new custom tag just for this template. This will override global registered tags of the same name for this template.

Optional jQuery methods: 

• jQuery.prototype.tmpl()
• returns a template object with .render() and .register() methods 
• $("#movie-tmpl").tmpl().register("movie").render(movie)
• jQuery.prototype.tmpl(data)
• compiles and renders template and returns jQuery object 
• $("#movie-tmpl").tmpl(movie).appendTo(movieList)  
• jQuery.prototype.tmpl(name) 
• registers template with name - returns template object with .render() method 
• $("#movie-tmpl").tmpl("movie")  
• jQuery.tmpl(name)
• returns template object with .render() method for the given name 
• $.tmpl("Title: {{=title}}").render(movie)  
• jQuery.tmpl(name, data)
• looks up the template by name, calls the .render( dataObj ) method, passes the string result to $() and returns the resulting jQuery object
• $.tmpl("movie", movie).appendTo(movieList)   

Syntax:

{{tag}}, {{tag arguments}}, {{#blocktag}}content{{/blocktag}}, {{#blocktag arguments}}content{{/blocktag}}

Built-in tags and block tags:

4 - Markup & Style:

n/a

5 - Latest version of plugin:

n/a

6 - Open issues being discussed

n/a