From bd643ce12b4ce5223f4db5cc124456994f4b481b Mon Sep 17 00:00:00 2001 From: kpdecker Date: Mon, 3 Aug 2015 21:13:47 -0500 Subject: Pull out duplicated documentation from readme Fixes #1006 --- README.markdown | 281 ++------------------------------------------------------ 1 file 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); // ``` +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("" + Handlebars.Utils.escapeExpression(this.body) + ""); -}); - -var context = { posts: [{url: "/hello-world", body: "Hello World!"}] }; -var source = "" - -var template = Handlebars.compile(source); -template(context); - -// Would render: -// -// -``` - -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 "" + title + "!" -}); - -var context = { posts: [{url: "/hello-world", body: "Hello World!"}] }; -var source = '' - -var template = Handlebars.compile(source); -template(context); - -// Would render: -// -// -``` - -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 = ""; -Handlebars.registerHelper('link', function(options) { - return '' + options.fn(this) + ''; -}); -var template = Handlebars.compile(source); - -var data = { "people": [ - { "name": "Alan", "id": 1 }, - { "name": "Yehuda", "id": 2 } - ]}; -template(data); - -// Should render: -// -``` - -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 = ""; - -Handlebars.registerPartial('link', '{{name}}') -var template = Handlebars.compile(source); - -var data = { "people": [ - { "name": "Alan", "id": 1 }, - { "name": "Yehuda", "id": 2 } - ]}; - -template(data); - -// Should render: -// -``` - -Partials can also accept parameters - -```js -var source = "
{{> roster rosterProperties people=listOfPeople}}
"; - -Handlebars.registerPartial('roster', '

{{rosterName}}

{{#people}}{{id}}: {{name}}{{/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: -//
-//

Cool People

-// 1: Alan -// 2: Yehuda -//
- -``` - -### 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 -
- {{! This comment will not end up in the output }} - -
-``` +- [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 - -
-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]
-
- -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 ---------------------- -- cgit v1.1