--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/cm/media/js/lib/yui/yui_3.10.3/docs/handlebars/index.html Tue Jul 16 14:29:46 2013 +0200
@@ -0,0 +1,1401 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="utf-8">
+ <title>Handlebars</title>
+ <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=PT+Sans:400,700,400italic,700italic">
+ <link rel="stylesheet" href="../../build/cssgrids/cssgrids-min.css">
+ <link rel="stylesheet" href="../assets/css/main.css">
+ <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
+ <link rel="shortcut icon" type="image/png" href="../assets/favicon.png">
+ <script src="../../build/yui/yui-min.js"></script>
+
+</head>
+<body>
+<!--
+<a href="https://github.com/yui/yui3"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
+-->
+<div id="doc">
+ <div id="hd">
+ <h1><img src="http://yuilibrary.com/img/yui-logo.png"></h1>
+ </div>
+
+ <a href="#toc" class="jump">Jump to Table of Contents</a>
+
+
+ <h1>Handlebars</h1>
+ <div class="yui3-g">
+ <div class="yui3-u-3-4">
+ <div id="main">
+ <div class="content"><style scoped>
+.handlebars-code pre.code {
+ height: 100%;
+ margin: 0;
+}
+
+.handlebars-code td,
+.handlebars-code th {
+ background: #fff;
+ padding: 0 0 0 12px;
+}
+
+.handlebars-code td:first-child,
+.handlebars-code th:first-child { padding-left: 0; }
+</style>
+
+<div class="intro">
+<p>
+Handlebars is a simple template language inspired by <a href="http://mustache.github.com/">Mustache</a>. This component is a YUI port of the <a href="https://github.com/wycats/handlebars.js">original Handlebars project</a>.
+</p>
+
+<p>
+This guide covers the YUI port of Handlebars, which differs from the original Handlebars in only <a href="#differences-from-original-handlebars">a few minor ways</a> and is kept closely in sync with the original. The official Handlebars documentation can be found at <a href="http://handlebarsjs.com/">handlebarsjs.com</a>.
+</p>
+</div>
+
+<h2 id="getting-started">Getting Started</h2>
+
+<p>
+To include the source files for Handlebars and its dependencies, first load
+the YUI seed file if you haven't already loaded it.
+</p>
+
+<pre class="code prettyprint"><script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script></pre>
+
+
+<p>
+Next, create a new YUI instance for your application and populate it with the
+modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
+YUI will automatically load any dependencies required by the modules you
+specify.
+</p>
+
+<pre class="code prettyprint"><script>
+// Create a new YUI instance and populate it with the required modules.
+YUI().use('handlebars', function (Y) {
+ // Handlebars is available and ready for use. Add implementation
+ // code here.
+});
+</script></pre>
+
+
+<p>
+For more information on creating YUI instances and on the
+<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
+documentation for the <a href="../yui/index.html">YUI Global Object</a>.
+</p>
+
+
+<h2 id="using-handlebars">Using Handlebars</h2>
+
+<h3 id="quick-start">Quick Start</h3>
+
+<p>
+A Handlebars template is just some text that contains Handlebars <a href="#basic-expressions">expressions</a> like <code>{{foo}}</code>. Although most people use Handlebars to generate HTML, it can easily generate JSON, XML, YAML, or any other plain text format.</p>
+
+<p>
+When you render a template, Handlebars evaluates expressions and replaces them with data. <a href="#block-expressions">Block expressions</a> can be used for iteration, simple if/else branching, and executing <a href="#helper-functions">helper functions</a>, but otherwise Handlebars is completely logic-less. This makes it ideal for separating content from functionality.
+</p>
+
+<p>
+First, you need to define a template string somewhere. Most template strings are long and contain lots of newlines and indentation, which makes them hard to read and maintain if you store them directly in JavaScript. A common pattern in apps that use Handlebars is to use <strong>micro-templating</strong>, which means embedding template strings in a static HTML document, wrapped in a <code><script></code> element with the attribute <code>type="text/x-handlebars-template"</code>. Thanks to the <code>type</code> attribute, the browser won't try to execute the script, and you can fetch the template string whenever you need it using <code>Y.one()</code>.
+</p>
+
+<p>
+Here's a simple micro-template that creates a list of links:
+</p>
+
+<pre class="code prettyprint lang-handlebars"><script id="list-template" type="text/x-handlebars-template">
+ <p>YUI is brought to you by:</p>
+
+ <ul>
+ {{#items}}
+ <li><a href="{{url}}">{{name}}</a></li>
+ {{/items}}
+ </ul>
+</script></pre>
+
+
+<p>
+Once you have a template string, the next step is to <strong>compile</strong> that string into a Handlebars template function. You can then <strong>render</strong> the template by passing a data object (also known as a <a href="#contexts-paths">context</a>) into that function.
+</p>
+
+<pre class="code prettyprint"><script>
+YUI().use('handlebars', 'node-base', function (Y) {
+ // Extract the template string and compile it into a reusable function.
+ var source = Y.one('#list-template').getHTML(),
+ template = Y.Handlebars.compile(source),
+ html;
+
+ // Render the template to HTML using the specified data.
+ html = template({
+ items: [
+ {name: 'pie', url: 'http://pieisgood.org/'},
+ {name: 'mountain dew', url: 'http://www.mountaindew.com/'},
+ {name: 'kittens', url: 'http://www.flickr.com/search/?q=kittens'},
+ {name: 'rainbows', url: 'http://www.youtube.com/watch?v=OQSNhk5ICTI'}
+ ]
+ });
+
+ // Append the rendered template to the page.
+ Y.one('body').append(html);
+});
+</script></pre>
+
+
+<p>
+After it's rendered and appended to the page, the output looks like this:
+</p>
+
+<div class="example">
+ <p>YUI is brought to you by:</p>
+
+ <ul>
+ <li><a href="http://pieisgood.org/">pie</a></li>
+ <li><a href="http://www.mountaindew.com/">mountain dew</a></li>
+ <li><a href="http://www.flickr.com/search/?q=kittens">kittens</a></li>
+ <li><a href="http://www.youtube.com/watch?v=OQSNhk5ICTI">rainbows</a></li>
+ </ul>
+</div>
+
+<p>
+You can re-render the template at any time simply by executing the stored <code>template</code> function again and passing in new data. Templates only need to be parsed once, which makes rendering a template multiple times very fast.
+</p>
+
+<pre class="code prettyprint">// Re-render the template with new data. No need to parse the template again.
+var html = template({
+ items: [
+ {name: 'caffeine', url: 'http://en.wikipedia.org/wiki/Caffeine'},
+ {name: 'git', url: 'http://git-scm.com/'},
+ {name: 'numberwang', url: 'http://www.youtube.com/watch?v=qjOZtWZ56lc'}
+ ]
+});</pre>
+
+
+<p>
+Alternatively, if you only need to render something once, you can use the convenient <a href="http://yuilibrary.com/yui/docs/api/classes/Handlebars.html#method_render"><code>render()</code></a> method to parse and render a template in a single step.
+</p>
+
+<pre class="code prettyprint">// Parse and render a template in a single step.
+var html = Y.Handlebars.render(source, {
+ // ... data ...
+});</pre>
+
+
+<h3 id="template-syntax">Template Syntax</h3>
+
+<h4 id="basic-expressions">Basic Expressions</h4>
+
+<p>
+A basic Handlebars expression starts with <code>{{</code>, contains some text, and ends with <code>}}</code>. These delimiters are often referred to as "mustaches", since they look a little bit like fancy mustaches if you turn your head sideways, squint a bit, and use your imagination. When a template is rendered, Handlebars will replace expressions with rendered data.
+</p>
+
+<p>
+A simple Handlebars expression looks like this:
+</p>
+
+<pre class="code prettyprint lang-handlebars"><h1>{{title}}</h1></pre>
+
+
+<p>
+This tells Handlebars:
+</p>
+
+<ol>
+ <li><p>If there's a <a href="#helper-functions">helper function</a> named "title", execute it and insert its return value here.</p></li>
+
+ <li><p>Otherwise, if there exists a <code>title</code> property in the current <a href="#contexts-paths">context</a>, and that property is not falsy or an empty array, insert its value here.</p></li>
+
+ <li><p>Otherwise, insert an empty string.</p></li>
+</ol>
+
+<h5 id="html-escaping">HTML Escaping</h5>
+
+<p>
+By default, content rendered using a double-mustache expression like <code>{{foo}}</code> will automatically be HTML-escaped for safety. To render unescaped HTML output, use a triple-mustache expression like <code>{{{foo}}}</code>. Only use a triple-mustache expression for content you trust! Never use it to render unfiltered user input.
+</p>
+
+<p>
+Handlebars also supports an alternative <code>{{&foo}}</code> syntax to render unescaped content, but this syntax is less commonly used. That said, some people find it preferable to the triple-mustache syntax since it's easier to spot at a glance.
+</p>
+
+<h5 id="contexts-paths">Contexts & Paths</h5>
+
+<p>
+All expressions are evaluated relative to the current <strong>context</strong>. The default context for a template is the data object passed in when the template is rendered.
+</p>
+
+<p>
+Here's the default context used for the examples in the rest of this section:
+</p>
+
+<pre class="code prettyprint">{
+ site: {
+ title: 'AwesomeBlog',
+ url: 'http://blog.example.com'
+ },
+
+ article: {
+ id: 1,
+ title: 'My blog is awesome'
+ }
+}</pre>
+
+
+<p>
+You can change the context using a <a href="#block-expressions">block expression</a>. Inside the block, the context will be set to the value referenced in the block's opening tag.
+</p>
+
+<pre class="code prettyprint lang-handlebars"><div class="header">
+ {{#site}}
+ <h1><a href="{{url}}">{{title}}</a></h1>
+ {{/site}}
+</div>
+
+<div class="content">
+ {{#article}}
+ <h2>{{title}}</h2>
+ {{/article}}
+</div></pre>
+
+
+<p>
+Certain <a href="#built-in-block-helpers">block helpers</a> also change the context within the block. For example, when iterating over an array of items using <code>{{#each items}} ... {{/each}}</code> or <code>{{#items}} ... {{/items}}</code>, the context inside the block will be set to the current item.
+</p>
+
+<p>
+The special expression <code>{{.}}</code> always evaluates to the current context, sort of like <code>this</code> in JavaScript. In fact, <code>{{.}}</code> and <code>{{this}}</code> do exactly the same thing! This is especially useful when <a href="#each">iterating over an array of strings</a>, since it allows you to output each string value.
+</p>
+
+<p>
+Using blocks to change the context is optional. Expressions can reference deeply-nested properties using dot notation:
+</p>
+
+<pre class="code prettyprint lang-handlebars"><div class="content">
+ <h2>{{article.title}}</h2>
+</div></pre>
+
+
+<p>
+The special expression <code>../</code> references the current context's parent scope.
+</p>
+
+<pre class="code prettyprint lang-handlebars"><div class="content">
+ {{#article}}
+ <h2><a href="{{../site.url}}/article/{{id}}">{{title}}</a></h2>
+ {{/article}}
+</div></pre>
+
+
+<p>
+Note that <code>../</code> references the parent scope, but not necessarily the previous level in the context hierarchy. Block helpers can invoke a block with any context, so a purely hierarchical reference wouldn't make much sense.
+</p>
+
+<h4 id="block-expressions">Block Expressions</h4>
+
+<p>
+Block expressions are used to change the current <a href="#contexts-paths">context</a> or to pass a block of content to a <a href="#helper-functions">helper function</a>. A block expression starts with an opening tag prefixed by <code>#</code>, contains some content, and ends with a closing tag prefixed by <code>/</code>, similar to an HTML element.
+</p>
+
+<p>
+The following example uses the <a href="#each">built-in <code>each</code> helper</a> to iterate over an array named <code>gadgets</code> and render the block's content in the context of each item in the array.
+</p>
+
+<table class="handlebars-code">
+ <thead>
+ <tr>
+ <th>Template Source</th>
+ <th>Data</th>
+ <th>Output</th>
+ </tr>
+ </thead>
+
+ <tbody>
+ <tr>
+ <td width="33%">
+<pre class="code prettyprint lang-handlebars"><ul>
+{{#each gadgets}}
+ <li>{{name}}</li>
+{{/each}}
+</ul></pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint">{
+ gadgets: [
+ {name: 'iPhone'},
+ {name: 'Android'},
+ {name: 'Windows Phone'}
+ ]
+}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint"><ul>
+ <li>iPhone</li>
+ <li>Android</li>
+ <li>Windows Phone</li>
+</ul></pre>
+
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<p>
+The <code>each</code> helper is so useful that Handlebars will actually use it as the default helper if you create a block expression with an identifier that points to an array value. So we could also write the template above like this and get the same result:
+</p>
+
+<pre class="code prettyprint lang-handlebars"><ul>
+{{#gadgets}}
+ <li>{{name}}</li>
+{{/gadgets}}
+</ul></pre>
+
+
+<p>
+If a block expression refers to an empty array, a falsy value, or a value that doesn't exist in the current context, the block's contents won't be rendered.
+</p>
+
+<p>
+A block expression that refers to a non-array value such as an object or string will change the context to that value inside the block. See <a href="#contexts-paths">Contexts & Paths</a> for an example of this.
+</p>
+
+<h4 id="built-in-block-helpers">Built-in Block Helpers</h4>
+
+<p>
+Handlebars provides several built-in block helpers that are always available to templates.
+</p>
+
+<h5 id="each">each</h5>
+
+<p>
+The <code>each</code> helper iterates over an array. The block will be rendered once for each item, and its context will be set to the current item.
+</p>
+
+<table class="handlebars-code">
+ <thead>
+ <tr>
+ <th>Template Source</th>
+ <th>Data</th>
+ <th>Output</th>
+ </tr>
+ </thead>
+
+ <tbody>
+ <tr>
+ <td width="33%">
+<pre class="code prettyprint lang-handlebars"><h1>Bands Ryan likes</h1>
+
+<ul>
+{{#each bands}}
+ <li>{{.}}</li>
+{{/each}}
+</ul></pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint">{
+ bands: [
+ 'The Dandy Warhols',
+ 'The Brian Jonestown Massacre',
+ 'The Black Keys',
+ 'Black Rebel Motorcycle Club'
+ ]
+}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint"><h1>Bands Ryan likes</h1>
+
+<ul>
+ <li>The Dandy Warhols</li>
+ <li>The Brian Jonestown Massacre</li>
+ <li>The Black Keys</li>
+ <li>Black Rebel Motorcycle Club</li>
+</ul></pre>
+
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<p>
+If you create a block expression with an identifier that points to an array value, Handlebars will automatically use the <code>each</code> helper to iterate over that array, so we could rewrite the template above like this and get the same result:
+</p>
+
+<pre class="code prettyprint lang-handlebars"><h1>Bands Ryan likes</h1>
+
+<ul>
+{{#bands}}
+ <li>{{.}}</li>
+{{/bands}}
+</ul></pre>
+
+
+<h5 id="with">with</h5>
+
+<p>
+The <code>with</code> block helper renders the given block in a different context. This can save you some typing in a template that will render a lot of namespaced data.
+</p>
+
+<table class="handlebars-code">
+ <thead>
+ <tr>
+ <th>Template Source</th>
+ <th>Data</th>
+ <th>Output</th>
+ </tr>
+ </thead>
+
+ <tbody>
+ <tr>
+ <td width="33%">
+<pre class="code prettyprint lang-handlebars"><p class="author">
+{{#with author}}
+ {{firstName}} {{lastName}}
+{{/with}}
+</p></pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint">{
+ author: {
+ firstName: 'Ryan',
+ lastName: 'Grove'
+ }
+}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint"><p class="author">
+ Ryan Grove
+</p></pre>
+
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<p>
+If you create an expression with an identifier that points to an object value, Handlebars will automatically use the <code>with</code> helper to render the block in the context of that object, so we could rewrite the template above like this and get the same result:
+</p>
+
+<pre class="code prettyprint lang-handlebars"><p class="author">
+{{#author}}
+ {{firstName}} {{lastName}}
+{{/author}}
+</p></pre>
+
+
+<h5 id="if">if</h5>
+
+<p>
+The <code>if</code> block helper accepts a single parameter, which may be either a literal value or a reference to a value. If the value is truthy and not an empty array, the contents of the block will be rendered. If an optional <code>else</code> block is provided, its contents will be rendered if the value is falsy or an empty array. Inside an <code>if</code> or <code>else</code> block, the context remains the same as it was outside the block.
+</p>
+
+<p>
+In order to prevent templates from becoming bogged down with logic that should be implemented in JavaScript or in a helper function, the <code>if</code> helper only supports simple true/false logic based on a single value. It doesn't support comparisons or logical operators like <code>&&</code> and <code>||</code>.
+</p>
+
+<table class="handlebars-code">
+ <thead>
+ <tr>
+ <th>Template Source</th>
+ <th>Data</th>
+ <th>Output</th>
+ </tr>
+ </thead>
+
+ <tbody>
+ <tr>
+ <td width="33%">
+<pre class="code prettyprint lang-handlebars"><h1>Currently online</h1>
+
+{{#if users}}
+ <ul>
+ {{#users}}
+ <li>{{.}}</li>
+ {{/users}}
+ </ul>
+{{/if}}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint">{
+ users: [
+ 'Ryan Grove',
+ 'Eric Ferraiuolo',
+ 'Lucas Smith',
+ 'Dav Glass'
+ ]
+}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint"><h1>Currently online</h1>
+
+<ul>
+ <li>Ryan Grove</li>
+ <li>Eric Ferraiuolo</li>
+ <li>Lucas Smith</li>
+ <li>Dav Glass</li>
+</ul></pre>
+
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<p>
+If we empty the <code>users</code> array and re-render the template, the list won't be included in the output.
+</p>
+
+<table class="handlebars-code">
+ <thead>
+ <tr>
+ <th>Template Source</th>
+ <th>Data</th>
+ <th>Output</th>
+ </tr>
+ </thead>
+
+ <tbody>
+ <tr>
+ <td width="33%">
+<pre class="code prettyprint lang-handlebars"><h1>Currently online</h1>
+
+{{#if users}}
+ <ul>
+ {{#users}}
+ <li>{{.}}</li>
+ {{/users}}
+ </ul>
+{{/if}}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint">{
+ users: []
+}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint"><h1>Currently online</h1></pre>
+
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<p>
+We can add an <code>else</code> block to display an informative message when no users are online.
+</p>
+
+<table class="handlebars-code">
+ <thead>
+ <tr>
+ <th>Template Source</th>
+ <th>Data</th>
+ <th>Output</th>
+ </tr>
+ </thead>
+
+ <tbody>
+ <tr>
+ <td width="33%">
+<pre class="code prettyprint lang-handlebars"><h1>Currently online</h1>
+
+{{#if users}}
+ <ul>
+ {{#users}}
+ <li>{{.}}</li>
+ {{/users}}
+ </ul>
+{{else}}
+ <p>Nobody's here!</p>
+{{/if}}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint">{
+ users: []
+}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint"><h1>Currently online</h1>
+
+<p>Nobody's here!</p></pre>
+
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<h5 id="unless">unless</h5>
+
+<p>
+The <code>unless</code> block helper does exactly the opposite of the <code>if</code> helper: it renders the contents of the block if the provided value is falsy or an empty array.
+</p>
+
+<table class="handlebars-code">
+ <thead>
+ <tr>
+ <th>Template Source</th>
+ <th>Data</th>
+ <th>Output</th>
+ </tr>
+ </thead>
+
+ <tbody>
+ <tr>
+ <td width="33%">
+<pre class="code prettyprint lang-handlebars"><h1>Currently online</h1>
+
+{{#unless users}}
+ <p>Nobody's here!</p>
+{{else}}
+ <ul>
+ {{#users}}
+ <li>{{.}}</li>
+ {{/users}}
+ </ul>
+{{/unless}}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint">{
+ users: [
+ 'Ryan Grove',
+ 'Eric Ferraiuolo',
+ 'Lucas Smith',
+ 'Dav Glass'
+ ]
+}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint"><h1>Currently online</h1>
+
+<ul>
+ <li>Ryan Grove</li>
+ <li>Eric Ferraiuolo</li>
+ <li>Lucas Smith</li>
+ <li>Dav Glass</li>
+</ul></pre>
+
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<h4 id="comment-expressions">Comment Expressions</h4>
+
+<p>
+An expression beginning with <code>{{!</code> is treated as a comment and won't show up in the rendered output.
+</p>
+
+<pre class="code prettyprint lang-handlebars">{{! I'm a Handlebars comment! I won't show up in rendered output. }}
+<!-- I'm an HTML comment! I will show up in rendered output. --></pre>
+
+
+<p>
+Multi-line comments work too.
+</p>
+
+<pre class="code prettyprint lang-handlebars">{{!
+ I'm a multi-line comment!
+}}</pre>
+
+
+<p>
+Unfortunately, Handlebars doesn't ignore expressions inside comments, so you can't actually comment out an expression.
+</p>
+
+<pre class="code prettyprint lang-handlebars"><!-- This won't work (it'll leave a trailing "}}" behind) -->
+{{! {{expression}} }}</pre>
+
+
+<h4 id="partial-expressions">Partial Expressions</h4>
+
+<p>
+An expression like <code>{{> partialName}}</code> will render the named partial template at that position in the output, inheriting the current data context. A partial is a reusable template that's registered using the <a href="http://yuilibrary.com/yui/docs/api/classes/Handlebars.html#method_registerPartial"><code>registerPartial()</code></a> method.
+</p>
+
+<p>
+See the <a href="#partials">Partials</a> section of this guide for more details on creating and using partials.
+</p>
+
+<h3 id="helper-functions">Helper Functions</h3>
+
+<p>
+Helper functions (often referred to simply as "helpers") are functions that are registered with the Handlebars runtime using the <a href="http://yuilibrary.com/yui/docs/api/classes/Handlebars.html#method_registerHelper"><code>registerHelper()</code></a> method and can then be called from within a template at render-time. Helper functions can transform text, iterate over arbitrary data, implement branching logic, and more.
+</p>
+
+<p>
+A helper function can accept parameters and even entire blocks of template content. Here's how you might call a simple inline helper to render an HTML link, passing in the link text and URL:
+</p>
+
+<pre class="code prettyprint lang-handlebars">{{link "Handlebars docs" "http://handlebarsjs.com"}}</pre>
+
+
+<p>
+Block helpers have a slightly different syntax, using an opening and closing tag to delimit an entire block of template content. The helper name is specified in the opening and closing tags of the block:
+</p>
+
+<pre class="code prettyprint lang-handlebars">{{#list contents}}
+ {{link text url}}
+{{/list}}</pre>
+
+
+<p>
+Many of Handlebars' own features are implemented as <a href="#built-in-block-helpers">Built-in Block Helpers</a>.
+</p>
+
+<p>
+Helper functions are executed when a template is rendered, not when it's compiled. This allows helper functions to take advantage of the state of the rendering environment (since a template may have been pre-compiled somewhere else), and to return different content even when the same template is rendered multiple times.
+</p>
+
+<h4 id="defining-custom-helpers">Defining Custom Helpers</h4>
+
+<p>
+To define a custom helper function, call the <a href="http://yuilibrary.com/yui/docs/api/classes/Handlebars.html#method_registerHelper"><code>registerHelper()</code></a> method and provide a name and a function to execute when the helper is called. The function may accept any number of arguments from the template, which may be provided either as literal values or as references to data properties. The final argument passed to the function will always be an <code>options</code> object (more on this <a href="#hash-arguments">later</a>).
+</p>
+
+<h5 id="basic-helpers">Basic Helpers</h5>
+
+<p>
+Here's a simple helper that takes two parameters and spits out an HTML link.
+</p>
+
+<pre class="code prettyprint">// Register a {{{link}}} helper for creating HTML links.
+Y.Handlebars.registerHelper('link', function (text, url) {
+ return '<a href="' + url + '">' + text + '</a>';
+});</pre>
+
+
+<p>
+We can use this helper to render the following template:
+</p>
+
+<p style="margin-bottom: -1em;">
+<strong>Template Source</strong>
+</p>
+
+<pre class="code prettyprint lang-handlebars"><ul>
+ <li>{{{link "Pie" "http://pieisgood.org/"}}}</li>
+ <li>{{{link kittens.text kittens.url}}}</li>
+</ul></pre>
+
+
+<p style="margin-bottom: -1em;">
+<strong>Data</strong>
+</p>
+
+<pre class="code prettyprint">{
+ kittens: {
+ text: "Kittens",
+ url : "http://www.flickr.com/search/?q=kittens"
+ }
+}</pre>
+
+
+<p style="margin-bottom: -1em;">
+<strong>Output</strong>
+</p>
+
+<pre class="code prettyprint"><ul>
+ <li><a href="http://pieisgood.org/">Pie</a></li>
+ <li><a href="http://www.flickr.com/search/?q=kittens">Kittens</a></li>
+</ul></pre>
+
+
+<p>
+Notice the use of the triple-mustache for the <code>{{{link}}}</code> expressions? That was necessary in order to prevent the helper's return value from being HTML-escaped. As an alternative to using a triple-mustache, we could modify the helper to return an instance of <code>Y.Handlebars.SafeString</code>, which will bypass HTML escaping even when used with a double-mustache expression.
+</p>
+
+<pre class="code prettyprint">// Register a {{link}} helper for creating HTML links. The return value of this
+// helper will never be automatically HTML-escaped, so the helper does its own
+// internal escaping.
+Y.Handlebars.registerHelper('link', function (text, url) {
+ text = Y.Escape.html(text);
+ url = Y.Escape.html(url);
+
+ return new Y.Handlebars.SafeString('<a href="' + url + '">' + text + '</a>');
+});</pre>
+
+
+<p>
+Now we can simply use <code>{{link "Text" "http://example.com/"}}</code> to call the helper, and we don't need to worry about escaping in the template itself since we know the helper will take care of it.
+</p>
+
+<h5 id="hash-arguments">Hash Arguments</h5>
+
+<p>
+In the example above, we created a helper that accepts two unnamed arguments. Unnamed arguments work fine for simple helpers, but you can also choose to supply a helper function with a hash of named parameters. This may be more intuitive if your helper accepts a lot of options.
+</p>
+
+<p>
+The final argument passed to a helper function is always a special <code>options</code> object. The <code>options.hash</code> property is an object hash that contains any named parameters that were passed from the template.
+</p>
+
+<pre class="code prettyprint">// Register a {{link}} helper that accepts a hash of named parameters instead
+// of individual arguments.
+Y.Handlebars.registerHelper('link', function (options) {
+ var text = Y.Escape.html(options.hash.text),
+ url = Y.Escape.html(options.hash.url);
+
+ return new Y.Handlebars.SafeString('<a href="' + url + '">' + text + '</a>');
+});</pre>
+
+
+<p>
+In the template, pass hash arguments as key/value pairs delimited by <code>=</code> and separated by a space. Keys must be simple identifiers. Values may be literal values (strings, bools, integers) or references to data properties.
+</p>
+
+<pre class="code prettyprint lang-handlebars"><ul>
+ <li>{{link text="Pie" url="http://pieisgood.org/"}}</li>
+ <li>{{link text=kittens.text url=kittens.url}}</li>
+</ul></pre>
+
+
+<p>
+A helper function can even accept a combination of standard arguments and hash arguments.
+</p>
+
+<pre class="code prettyprint">// Register a {{link}} helper that accepts a combination of standard args and
+// hash arguments.
+Y.Handlebars.registerHelper('link', function (text, options) {
+ var url = Y.Escape.html(options.hash.url);
+
+ text = Y.Escape.html(text);
+
+ return new Y.Handlebars.SafeString('<a href="' + url + '">' + text + '</a>');
+});</pre>
+
+
+<pre class="code prettyprint lang-handlebars"><ul>
+ <li>{{link "Pie" url="http://pieisgood.org/"}}</li>
+ <li>{{link kittens.text url=kittens.url}}</li>
+</ul></pre>
+
+
+<h5 id="block-helpers">Block Helpers</h5>
+
+<p>
+A block helper works similarly to a basic helper, with a couple of differences:
+</p>
+
+<ul>
+ <li>
+ <p>
+ The <code>options</code> object passed to a block helper function contains an <code>fn</code> property, which is a function that accepts a context as an argument and returns a string containing the rendered contents of the block.
+ </p>
+ </li>
+
+ <li>
+ <p>
+ The <code>options</code> object passed to a block helper function also contains an <code>inverse</code> property. This is a function that accepts a context just like the <code>fn</code> property, except that it renders the block following an <code>else</code> statement. If there isn't an <code>else</code> statement, the <code>inverse</code> function will be a noop.
+ </p>
+ </li>
+
+ <li>
+ <p>
+ The return value of a block helper is not automatically HTML-escaped, but the return value of <code>options.fn()</code> <em>is</em> automatically escaped. This ensures that block helpers don't return double-escaped content.
+ </p>
+ </li>
+</ul>
+
+<p>
+Here's a simple block helper that wraps its contents in a <code><p></code> element:
+</p>
+
+<pre class="code prettyprint">Y.Handlebars.registerHelper('gamera', function (options) {
+ return '<p class="' + this.animal + '">' + options.fn(this) + '</p>';
+});</pre>
+
+
+<table class="handlebars-code">
+ <thead>
+ <tr>
+ <th>Template Source</th>
+ <th>Data</th>
+ <th>Output</th>
+ </tr>
+ </thead>
+
+ <tbody>
+ <tr>
+ <td width="33%">
+<pre class="code prettyprint lang-handlebars"><p>Gamera is really neat!</p>
+
+{{#gamera}}
+ He is made of {{animal}} meat!
+{{/gamera}}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint">{
+ animal: 'turtle'
+}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint"><p>Gamera is a really neat!</p>
+
+<p class="turtle">
+ He is made of turtle meat!
+</p></pre>
+
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<p>
+Here's how Handlebars implements its own <a href="#if"><code>if</code></a> block helper. The <code>options.inverse()</code> function makes it possible to render the contents of an <code>else</code> block if one is provided.
+</p>
+
+<pre class="code prettyprint">Y.Handlebars.registerHelper('if', function (condition, options) {
+ if (condition) {
+ return options.fn(this);
+ } else {
+ return options.inverse(this);
+ }
+});</pre>
+
+
+<h3 id="partials">Partials</h3>
+
+<p>
+A partial is like a mini-template that can be called from a larger template. Partials are often used to render frequently-used chunks of content, such as a header, footer, or a common view of some data.
+</p>
+
+<p>
+Partials are registered with Handlebars through the <a href="http://yuilibrary.com/yui/docs/api/classes/Handlebars.html#method_registerPartial"><code>registerPartial()</code></a> method. Once registered, a partial can be referenced from a template using an expression like <code>{{> partialName }}</code>. Partials may be registered as string templates or as compiled template functions.
+</p>
+
+<p>
+A partial will inherit the current context of the position at which it's included.
+</p>
+
+<pre class="code prettyprint">// Register a couple of reusable partials.
+Y.Handlebars.registerPartial('header', '<h1>{{title}}</h1>');
+Y.Handlebars.registerPartial('footer', '<p>Copyright (c) 2012 by Me.</p>');</pre>
+
+
+<table class="handlebars-code">
+ <thead>
+ <tr>
+ <th>Template Source</th>
+ <th>Data</th>
+ <th>Output</th>
+ </tr>
+ </thead>
+
+ <tbody>
+ <tr>
+ <td width="33%">
+<pre class="code prettyprint lang-handlebars"><div>
+ {{> header}}
+
+ <p>Mustaches are awesome!</p>
+
+ {{> footer}}
+</div></pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint">{
+ title: 'My Page About Mustaches'
+}</pre>
+
+ </td>
+
+ <td width="33%">
+<pre class="code prettyprint"><div>
+ <h1>My Page About Mustaches</h1>
+
+ <p>Mustaches are awesome!</p>
+
+ <p>Copyright (c) 2012 by Me.</p>
+</div></pre>
+
+ </td>
+ </tr>
+ </tbody>
+</table>
+
+<h3 id="compiling-and-rendering-templates">Compiling and Rendering Templates</h3>
+
+<p>
+Handlebars templates must be compiled before they can be rendered. One benefit of this is that a template only needs to be compiled once, and it can then be rendered multiple times without being recompiled. Templates can even be <a href="#precompiling-templates">precompiled</a> on the server or on the command line and then rendered on the client for optimal performance.
+</p>
+
+<p>
+To compile a template string, pass it to the <a href="http://yuilibrary.com/yui/docs/api/classes/Handlebars.html#method_compile"><code>Y.Handlebars.compile()</code></a> method. You'll get back a function.
+</p>
+
+<pre class="code prettyprint">// Compile a template into a reusable function.
+var template = Y.Handlebars.compile('My favorite food is {{food}}.');</pre>
+
+
+<p>
+When you're ready to render the template, execute the function and pass in some data. You'll get back a rendered string.
+</p>
+
+<pre class="code prettyprint">// Render a previously compiled template.
+var output = template({food: 'pie'});
+// => "My favorite food is pie.";</pre>
+
+
+<p>
+You can re-render the template at any time just by calling the function again. You can even pass in completely different data.
+</p>
+
+<pre class="code prettyprint">// Re-render a previously compiled template.
+output = template({food: 'cheesecake'});
+// => "My favorite food is cheesecake."</pre>
+
+
+<p>
+If you don't plan to use a template more than once, you can compile and render it in a single step with <a href="http://yuilibrary.com/yui/docs/api/classes/Handlebars.html#method_render"><code>Y.Handlebars.render()</code></a>.
+</p>
+
+<pre class="code prettyprint">// Compile and render a template in a single step.
+output = Y.Handlebars.render('My favorite food is {{food}}.', {food: 'pie'});
+// => "My favorite food is pie."</pre>
+
+
+<h3 id="precompiling-templates">Precompiling Templates</h3>
+
+<p>
+Since Handlebars templates can be compiled and rendered in separate steps, it's possible to precompile a template for use later. You can precompile a template into raw JavaScript on the server or even on the command line, serve this precompiled JavaScript template to the client, and then render it on the client using any data the client has at its disposal.
+</p>
+
+<p>
+The main benefit of precompilation is performance. Not only does the client not need to go through the compile step, you don't even have to load the Handlebars compiler on the client! All the client needs in order to render a precompiled template is a very small (about 1KB minified and gzipped) piece of JavaScript provided by the <code>handlebars-base</code> module.
+</p>
+
+<h5 id="on-the-server">On the Server</h5>
+
+<p>
+To precompile Handlebars templates on the server using <a href="http://nodejs.org/">Node.js</a>, first install the YUI <a href="http://npmjs.org/">npm</a> module by running the following in a terminal from the directory that contains your server application (this assumes you already have Node and npm installed):
+</p>
+
+<pre class="code terminal"><span class="noselect">$ </span>npm install yui</pre>
+
+
+<p>
+This will install the <code>yui</code> npm module in the current directory and make it available to your application.
+</p>
+
+<p>
+Next, in your application code, call the <a href="http://yuilibrary.com/yui/docs/api/classes/Handlebars.html#method_precompile"><code>precompile()</code></a> method to precompile a Handlebars template. It will return a string containing JavaScript code.
+</p>
+
+<pre class="code prettyprint">// Load the YUI Handlebars module.
+var Handlebars = require('yui/handlebars').Handlebars;
+
+// Precompile a template string (pass any string you like here).
+var precompiled = Handlebars.precompile('My favorite food is {{food}}.');</pre>
+
+
+<p>
+The <code>precompiled</code> variable will contain a string of JavaScript code that looks something like this:
+</p>
+
+<pre class="code prettyprint">function (Handlebars,depth0,helpers,partials,data) {\n helpers = helpers || Handlebars.helpers; data = data || {};\n var buffer = "", stack1, foundHelper, functionType="function", escapeExpression=this.escapeExpression;\n\n\n buffer += "My favorite food is ";\n foundHelper = helpers.food;\n if (foundHelper) { stack1 = foundHelper.call(depth0, {hash:{},data:data}); }\n else { stack1 = depth0.food; stack1 = typeof stack1 === functionType ? stack1.apply(depth0) : stack1; }\n buffer += escapeExpression(stack1) + ".";\n return buffer;}</pre>
+
+
+<p>
+The <code>precompile()</code> method differs from the <code>compile()</code> method in a couple of important ways:
+</p>
+
+<ul>
+<li><p>The <code>precompile()</code> method returns a string of JavaScript code that's meant to be parsed and executed later, whereas <code>compile()</code> returns a live JavaScript function.</p></li>
+
+<li><p>The code returned by the <code>precompile()</code> method contains no references to any outside objects. Once it's evaluated, the resulting precompiled function must be passed to the <a href="http://yuilibrary.com/yui/docs/api/classes/Handlebars.html#method_template"><code>Y.Handlebars.template()</code></a> method, which will "revive" it and make the functionality of the current page's Handlebars class available to it.</p></li>
+</ul>
+
+<p>
+You can now serve this precompiled JS to the client in whatever way makes the most sense for your application. On the client, load the <code>handlebars-base</code> YUI module and pass the precompiled template to the <a href="http://yuilibrary.com/yui/docs/api/classes/Handlebars.html#method_template"><code>Y.Handlebars.template()</code></a> method to convert it into a renderable template function.
+</p>
+
+<p>
+Here's a simple <a href="http://expressjs.com/">Express</a> app that precompiles a template on the server and renders it on the client:
+</p>
+
+<pre class="code prettyprint">#!/usr/bin/env node
+var Handlebars = require('yui/handlebars').Handlebars,
+ app = require('express').createServer(),
+
+ precompiled = Handlebars.precompile('My favorite food is {{food}}.');
+
+app.get('/', function (req, res) {
+ res.send(
+ '<html><body>' +
+ '<script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script>' +
+ '<script>' +
+ 'YUI().use("handlebars-base", "node", function (Y) {' +
+ 'var template = Y.Handlebars.template(' + precompiled + ');' +
+ 'Y.one("body").append(template({food: "pie"}));' +
+ '});' +
+ '</script>' +
+ '</body></html>'
+ );
+});
+
+app.listen(7000);</pre>
+
+
+<p>
+To see this simple server in action, save it to a file, install Express and YUI by running <code>npm i express yui</code>, then execute the file with Node.js and browse to <a href="http://localhost:7000/" target="_blank">http://localhost:7000/</a>.
+</p>
+
+<h5 id="on-the-command-line">On the Command Line</h5>
+
+<p>
+The original Handlebars project provides a Node.js-based Handlebars command-line application that can be installed via npm and used to precompile Handlebars template files. Since the precompiled templates produced by the original Handlebars are compatible with YUI Handlebars, this is a great way to precompile your Handlebars templates manually or as part of a build process.
+</p>
+
+<p>
+First, you'll need to install <a href="http://nodejs.org/">Node.js</a> and <a href="http://npmjs.org/">npm</a> if you haven't already. See their respective websites for instructions.
+</p>
+
+<p>
+Next, install the Handlebars npm module. Note that this program is maintained by the maintainers of the <a href="https://github.com/wycats/handlebars.js">original Handlebars project</a>, so there's a chance it could change or break compatibility with YUI Handlebars without notice.
+</p>
+
+<pre class="code terminal"><span class="noselect">$ </span>npm install -g handlebars</pre>
+
+
+<p>
+Now you can run the <code>handlebars</code> executable to precompile a template into JavaScript code.
+</p>
+
+<pre class="code terminal"><span class="noselect">$ </span>handlebars my-template.handlebars -f precompiled-template.js</pre>
+
+
+<p>
+This will compile a template to a JavaScript file which you can load on your page. You could render it like this:
+</p>
+
+<pre class="code prettyprint"><!DOCTYPE html>
+<meta charset="utf-8">
+<title>My Favorite Food</title>
+
+<body>
+<div id="content"></div>
+
+<script src="http://yui.yahooapis.com/3.10.3/build/yui/yui-min.js"></script>
+<script>
+YUI().use('handlebars-base', 'get', 'node', function (Y) {
+ // Create a global Handlebars variable that points to Y.Handlebars. This is
+ // necessary for compatibility with precompiled templates generated by the
+ // original Handlebars project.
+ window.Handlebars = Y.Handlebars;
+
+ // Load the precompiled template JS onto the page.
+ Y.Get.js('precompiled-template.js', function (err) {
+ if (err) {
+ Y.error('Template failed to load: ' + err);
+ return;
+ }
+
+ // Render the template and insert its output into the page.
+ var output = Y.Handlebars.templates['my-template']({food: 'pie'});
+ Y.one('#content').append(output);
+ });
+});
+</script>
+</body></pre>
+
+
+<h2 id="differences-from-original-handlebars">Differences From Original Handlebars</h2>
+
+<p>
+The YUI Handlebars component is mostly just a YUI wrapper around the <a href="https://github.com/wycats/handlebars.js">original Handlebars code</a>. It's kept closely in sync with the latest code from the upstream Handlebars project, and our intent is to ensure that YUI Handlebars and original Handlebars can be used interchangeably to render the same templates. To see what upstream Handlebars version YUI uses, inspect <code>Y.Handlebars.VERSION</code>.
+</p>
+
+<p>
+YUI Handlebars differs from the original Handlebars in the following minor ways:
+</p>
+
+<ul>
+ <li>
+ <p>
+ YUI Handlebars is a first-class YUI module intended to be loaded via <code>YUI().use()</code> or as a dependency of a module created via <code>YUI.add()</code>. Like all YUI modules, it adds its API to the <code>Y</code> namespace, so the YUI Handlebars object is <code>Y.Handlebars</code> instead of the global <code>Handlebars</code> namespace used by the original Handlebars.
+ </p>
+ </li>
+
+ <li>
+ <p>
+ The <code>Y.Handlebars.log()</code> function and the <code>log</code> helper call <code>Y.log()</code> under the hood. The log implementation in original Handlebars is a noop that's meant to be overridden.
+ </p>
+ </li>
+
+ <li>
+ <p>
+ YUI Handlebars appends a "-yui" suffix to the <code>Y.Handlebars.VERSION</code> property.
+ </p>
+ </li>
+</ul>
+</div>
+ </div>
+ </div>
+
+ <div class="yui3-u-1-4">
+ <div class="sidebar">
+
+ <div id="toc" class="sidebox">
+ <div class="hd">
+ <h2 class="no-toc">Table of Contents</h2>
+ </div>
+
+ <div class="bd">
+ <ul class="toc">
+<li>
+<a href="#getting-started">Getting Started</a>
+</li>
+<li>
+<a href="#using-handlebars">Using Handlebars</a>
+<ul class="toc">
+<li>
+<a href="#quick-start">Quick Start</a>
+</li>
+<li>
+<a href="#template-syntax">Template Syntax</a>
+<ul class="toc">
+<li>
+<a href="#basic-expressions">Basic Expressions</a>
+<ul class="toc">
+<li>
+<a href="#html-escaping">HTML Escaping</a>
+</li>
+<li>
+<a href="#contexts-paths">Contexts & Paths</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#block-expressions">Block Expressions</a>
+</li>
+<li>
+<a href="#built-in-block-helpers">Built-in Block Helpers</a>
+<ul class="toc">
+<li>
+<a href="#each">each</a>
+</li>
+<li>
+<a href="#with">with</a>
+</li>
+<li>
+<a href="#if">if</a>
+</li>
+<li>
+<a href="#unless">unless</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#comment-expressions">Comment Expressions</a>
+</li>
+<li>
+<a href="#partial-expressions">Partial Expressions</a>
+</li>
+</ul>
+</li>
+<li>
+<a href="#helper-functions">Helper Functions</a>
+<ul class="toc">
+<li>
+<a href="#defining-custom-helpers">Defining Custom Helpers</a>
+<ul class="toc">
+<li>
+<a href="#basic-helpers">Basic Helpers</a>
+</li>
+<li>
+<a href="#hash-arguments">Hash Arguments</a>
+</li>
+<li>
+<a href="#block-helpers">Block Helpers</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<a href="#partials">Partials</a>
+</li>
+<li>
+<a href="#compiling-and-rendering-templates">Compiling and Rendering Templates</a>
+</li>
+<li>
+<a href="#precompiling-templates">Precompiling Templates</a>
+<ul class="toc">
+<li>
+<a href="#on-the-server">On the Server</a>
+</li>
+<li>
+<a href="#on-the-command-line">On the Command Line</a>
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+<a href="#differences-from-original-handlebars">Differences From Original Handlebars</a>
+</li>
+</ul>
+ </div>
+ </div>
+
+
+
+
+
+ </div>
+ </div>
+ </div>
+</div>
+
+<script src="../assets/vendor/prettify/prettify-min.js"></script>
+<script>prettyPrint();</script>
+
+<script>
+YUI.Env.Tests = {
+ examples: [],
+ project: '../assets',
+ assets: '../assets/handlebars',
+ name: 'handlebars',
+ title: 'Handlebars',
+ newWindow: '',
+ auto: false
+};
+
+</script>
+<script src="../assets/yui/test-runner.js"></script>
+
+
+
+</body>
+</html>