diff options
| -rw-r--r-- | README.markdown | 281 |
1 files changed, 10 insertions, 271 deletions
diff --git a/README.markdown b/README.markdown index 6500966..d39d131 100644 --- a/README.markdown +++ b/README.markdown @@ -57,231 +57,25 @@ var result = template(data); // </ul> ``` +Full documentation and more examples are at [handlebarsjs.com](http://handlebarsjs.com/). -Registering Helpers -------------------- - -You can register helpers that Handlebars will use when evaluating your -template. Here's an example, which assumes that your objects have a URL -embedded in them, as well as the text for a link: - -```js -Handlebars.registerHelper('link_to', function() { - return new Handlebars.SafeString("<a href='" + Handlebars.Utils.escapeExpression(this.url) + "'>" + Handlebars.Utils.escapeExpression(this.body) + "</a>"); -}); - -var context = { posts: [{url: "/hello-world", body: "Hello World!"}] }; -var source = "<ul>{{#posts}}<li>{{link_to}}</li>{{/posts}}</ul>" - -var template = Handlebars.compile(source); -template(context); - -// Would render: -// -// <ul> -// <li><a href='/hello-world'>Hello World!</a></li> -// </ul> -``` - -Helpers take precedence over fields defined on the context. To access a field -that is masked by a helper, a path reference may be used. In the example above -a field named `link_to` on the `context` object would be referenced using: - -``` -{{./link_to}} -``` - -Escaping --------- - -By default, the `{{expression}}` syntax will escape its contents. This -helps to protect you against accidental XSS problems caused by malicious -data passed from the server as JSON. - -To explicitly *not* escape the contents, use the triple-mustache -(`{{{}}}`). You have seen this used in the above example. +Precompiling Templates +---------------------- +Handlebars allows templates to be precompiled and included as javascript code rather than the handlebars template allowing for faster startup time. Full details are located [here](http://handlebarsjs.com/precompilation.html). Differences Between Handlebars.js and Mustache ---------------------------------------------- Handlebars.js adds a couple of additional features to make writing templates easier and also changes a tiny detail of how partials work. -### Paths - -Handlebars.js supports an extended expression syntax that we call paths. -Paths are made up of typical expressions and `.` characters. Expressions -allow you to not only display data from the current context, but to -display data from contexts that are descendants and ancestors of the -current context. - -To display data from descendant contexts, use the `.` character. So, for -example, if your data were structured like: - -```js -var data = {"person": { "name": "Alan" }, "company": {"name": "Rad, Inc." } }; -``` - -You could display the person's name from the top-level context with the -following expression: - -``` -{{person.name}} -``` - -You can backtrack using `../`. For example, if you've already traversed -into the person object you could still display the company's name with -an expression like `{{../company.name}}`, so: - -``` -{{#with person}}{{name}} - {{../company.name}}{{/with}} -``` - -would render: - -``` -Alan - Rad, Inc. -``` - -### Strings - -When calling a helper, you can pass paths or Strings as parameters. For -instance: - -```js -Handlebars.registerHelper('link_to', function(title, options) { - return "<a href='/posts" + this.url + "'>" + title + "!</a>" -}); - -var context = { posts: [{url: "/hello-world", body: "Hello World!"}] }; -var source = '<ul>{{#posts}}<li>{{{link_to "Post"}}}</li>{{/posts}}</ul>' - -var template = Handlebars.compile(source); -template(context); - -// Would render: -// -// <ul> -// <li><a href='/posts/hello-world'>Post!</a></li> -// </ul> -``` - -When you pass a String as a parameter to a helper, the literal String -gets passed to the helper function. - - -### Block Helpers - -Handlebars.js also adds the ability to define block helpers. Block -helpers are functions that can be called from anywhere in the template. -Here's an example: - -```js -var source = "<ul>{{#people}}<li>{{#link}}{{name}}{{/link}}</li>{{/people}}</ul>"; -Handlebars.registerHelper('link', function(options) { - return '<a href="/people/' + this.id + '">' + options.fn(this) + '</a>'; -}); -var template = Handlebars.compile(source); - -var data = { "people": [ - { "name": "Alan", "id": 1 }, - { "name": "Yehuda", "id": 2 } - ]}; -template(data); - -// Should render: -// <ul> -// <li><a href="/people/1">Alan</a></li> -// <li><a href="/people/2">Yehuda</a></li> -// </ul> -``` - -Whenever the block helper is called it is given one or more parameters, -any arguments that are passed into the helper in the call, and an `options` -object containing the `fn` function which executes the block's child. -The block's current context may be accessed through `this`. - -Block helpers have the same syntax as mustache sections but should not be -confused with one another. Sections are akin to an implicit `each` or -`with` statement depending on the input data and helpers are explicit -pieces of code that are free to implement whatever behavior they like. -The [mustache spec](http://mustache.github.io/mustache.5.html) -defines the exact behavior of sections. In the case of name conflicts, -helpers are given priority. - -### Partials - -You can register additional templates as partials, which will be used by -Handlebars when it encounters a partial (`{{> partialName}}`). Partials -can either be String templates or compiled template functions. Here's an -example: - -```js -var source = "<ul>{{#people}}<li>{{> link}}</li>{{/people}}</ul>"; - -Handlebars.registerPartial('link', '<a href="/people/{{id}}">{{name}}</a>') -var template = Handlebars.compile(source); - -var data = { "people": [ - { "name": "Alan", "id": 1 }, - { "name": "Yehuda", "id": 2 } - ]}; - -template(data); - -// Should render: -// <ul> -// <li><a href="/people/1">Alan</a></li> -// <li><a href="/people/2">Yehuda</a></li> -// </ul> -``` - -Partials can also accept parameters - -```js -var source = "<div>{{> roster rosterProperties people=listOfPeople}}</div>"; - -Handlebars.registerPartial('roster', '<h2>{{rosterName}}</h2>{{#people}}<span>{{id}}: {{name}}</span>{{/people}}') -var template = Handlebars.compile(source); - -var data = { - "listOfPeople": [ - { "name": "Alan", "id": 1 }, - { "name": "Yehuda", "id": 2 } - ], - "rosterProperties": { - "rosterName": "Cool People" - } -}; - -template(data); - -// Should render: -// <div> -// <h2>Cool People</h2> -// <span>1: Alan</span> -// <span>2: Yehuda</span> -// </div> - -``` - -### Comments - -You can add comments to your templates with the following syntax: - -```js -{{! This is a comment }} -``` - -You can also use real html comments if you want them to end up in the output. - -```html -<div> - {{! This comment will not end up in the output }} - <!-- This comment will show up in the output --> -</div> -``` +- [Nested Paths](http://handlebarsjs.com/#paths) +- [Helpers](http://handlebarsjs.com/#helpers) +- [Block Expressions](http://handlebarsjs.com/#block-expressions) +- [Literal Values](http://handlebarsjs.com/#literals) +- [Delimited Comments](http://handlebarsjs.com/#comments) +Block expressions have the same syntax as mustache sections but should not be confused with one another. Sections are akin to an implicit `each` or `with` statement depending on the input data and helpers are explicit pieces of code that are free to implement whatever behavior they like. The [mustache spec](http://mustache.github.io/mustache.5.html) defines the exact behavior of sections. In the case of name conflicts, helpers are given priority. ### Compatibility @@ -291,61 +85,6 @@ There are a few Mustache behaviors that Handlebars does not implement. - Alternative delimiters are not supported. -Precompiling Templates ----------------------- - -Handlebars allows templates to be precompiled and included as javascript -code rather than the handlebars template allowing for faster startup time. - -### Installation -The precompiler script may be installed via npm using the `npm install -g handlebars` -command. - -### Usage - -<pre> -Precompile handlebar templates. -Usage: handlebars template... - -Options: - -a, --amd Create an AMD format function (allows loading with RequireJS) [boolean] - -f, --output Output File [string] - -k, --known Known helpers [string] - -o, --knownOnly Known helpers only [boolean] - -m, --min Minimize output [boolean] - -s, --simple Output template function only. [boolean] - -r, --root Template root. Base value that will be stripped from template names. [string] - -c, --commonjs Exports CommonJS style, path to Handlebars module [string] - -h, --handlebarPath Path to handlebar.js (only valid for amd-style) [string] - -n, --namespace Template namespace [string] - -p, --partial Compiling a partial template [boolean] - -d, --data Include data when compiling [boolean] - -e, --extension Template extension. [string] - -b, --bom Removes the BOM (Byte Order Mark) from the beginning of the templates. [boolean] -</pre> - -If using the precompiler's normal mode, the resulting templates will be -stored to the `Handlebars.templates` object using the relative template -name sans the extension. These templates may be executed in the same -manner as templates. - -If using the simple mode the precompiler will generate a single -javascript method. To execute this method it must be passed to -the `Handlebars.template` method and the resulting object may be used as normal. - -### Optimizations - -- Rather than using the full _handlebars.js_ library, implementations that - do not need to compile templates at runtime may include _handlebars.runtime.js_ - whose min+gzip size is approximately 1k. -- If a helper is known to exist in the target environment they may be defined - using the `--known name` argument may be used to optimize accesses to these - helpers for size and speed. -- When all helpers are known in advance the `--knownOnly` argument may be used - to optimize all block helper references. -- Implementations that do not use `@data` variables can improve performance of - iteration centric templates by specifying `{data: false}` in the compiler options. - Supported Environments ---------------------- |