Rendering templates

Templates are re-usable snippets of text, usually HTML, that various code in your apps can make use of. They are rendered with the following method:

var html = Q.Template.render(
  "First/foo",
  fields,     
  partials,
  callback,
  options
);

Qbix adds a couple helpers to facilitate rendering tools inside templates, and calling methods of objects. Here is how you would use them:

// render a tool
{{&tool "Streams/participants" "group"
  max=10 maxShow=10 showSummary=false
  showControls=true showBlanks=true }}

// setting nested properties in options
{{&tool "Streams/inplace" "foo"
  inplace-placeholder="something"
}}
  
// call a function
{{call "stream.get" "venue"}}

You can use templates to quickly render a bunch of tools, assigning ids and options to them from data passed to the template:

Q.Template.set('First/reviews',
  '{{#each reviews}}' +
  '<div class="First_reviews_title">' + 
	'{{this.title}}' + 
  '</div>' +
  '<div class="Q_tool Q_rating_tool" id="Q_rating_{{@index}}" data-q-rating='{"value": "stars"}' data-q-lazyload="waiting"></div>' +
  '{{/each}}'
);

// and to render the tools:
var reviews = [ { stars: 5 }, {stars: 4} ];
Q.Template.render('Qbix/reviews/reviews', {
  reviews: reviews
}, function (err, html) {
  Q.activate(Q.replace(someElement, html));
})

Files ending in .handlebars can also be rendered as views in PHP.

Loading templates

To minimize the number of requests, template contents can be set directly before the template is rendered:

Q.Template.set("First/foo", content)

The template engine used by default is Handlebars. It was chosen because the same template can be rendered in PHP and Javascript, the two languages used in Qbix. Soon, Qbix will support other templating engines.

When rendering a template, Qbix checks if a template with this name was already set. If not, it looks through the document for a script tag like this:

<script id="First/foo" type="text/handlebars">
  // template contents here
</script>

If found, the contents of this script element are set for the template and the element is removed from the document.

Otherwise, Qbix proceeds to load the following url: Q.url(o.dir+'/'+name+'.'+o.type) which becomes, with default values for the options, Q.url('Q/views/First/foo.handlebars')

Exporting templates

When a page is loaded from the server, Qbix checks the JSON data for "templates" and automatically loads them.

On the PHP side, views can be exported as client-side templates by calling

Q_Response::addTemplate("First/foo", "handlebars");