force-refresh / node_modules / handlebars / README.markdown

README.markdown in Force Refresh 2.0.0, at node_modules/handlebars/README.markdown

169 lines 8.7 KB

Raw Download Zip

1	[![Travis Build Status](https://img.shields.io/travis/wycats/handlebars.js/master.svg)](https://travis-ci.org/wycats/handlebars.js)
2	[![Appveyor Build Status](https://ci.appveyor.com/api/projects/status/github/wycats/handlebars.js?branch=master&svg=true)](https://ci.appveyor.com/project/wycats/handlebars-js)
3	[![Selenium Test Status](https://saucelabs.com/buildstatus/handlebars)](https://saucelabs.com/u/handlebars)
4
5	Handlebars.js
6	=============
7
8	Handlebars.js is an extension to the [Mustache templating
9	language](http://mustache.github.com/) created by Chris Wanstrath.
10	Handlebars.js and Mustache are both logicless templating languages that
11	keep the view and the code separated like we all know they should be.
12
13	Checkout the official Handlebars docs site at
14	[http://www.handlebarsjs.com](http://www.handlebarsjs.com) and the live demo at [http://tryhandlebarsjs.com/](http://tryhandlebarsjs.com/).
15
16	Installing
17	----------
18
19	See our [installation documentation](http://handlebarsjs.com/installation.html).
20
21	Usage
22	-----
23	In general, the syntax of Handlebars.js templates is a superset
24	of Mustache templates. For basic syntax, check out the [Mustache
25	manpage](http://mustache.github.com/mustache.5.html).
26
27	Once you have a template, use the `Handlebars.compile` method to compile
28	the template into a function. The generated function takes a context
29	argument, which will be used to render the template.
30
31	```js
32	var source = "<p>Hello, my name is {{name}}. I am from {{hometown}}. I have " +
33	"{{kids.length}} kids:</p>" +
34	"<ul>{{#kids}}<li>{{name}} is {{age}}</li>{{/kids}}</ul>";
35	var template = Handlebars.compile(source);
36
37	var data = { "name": "Alan", "hometown": "Somewhere, TX",
38	"kids": [{"name": "Jimmy", "age": "12"}, {"name": "Sally", "age": "4"}]};
39	var result = template(data);
40
41	// Would render:
42	// <p>Hello, my name is Alan. I am from Somewhere, TX. I have 2 kids:</p>
43	// <ul>
44	// <li>Jimmy is 12</li>
45	// <li>Sally is 4</li>
46	// </ul>
47	```
48
49	Full documentation and more examples are at [handlebarsjs.com](http://handlebarsjs.com/).
50
51	Precompiling Templates
52	----------------------
53
54	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).
55
56	Differences Between Handlebars.js and Mustache
57	----------------------------------------------
58	Handlebars.js adds a couple of additional features to make writing
59	templates easier and also changes a tiny detail of how partials work.
60
61	- [Nested Paths](http://handlebarsjs.com/#paths)
62	- [Helpers](http://handlebarsjs.com/#helpers)
63	- [Block Expressions](http://handlebarsjs.com/#block-expressions)
64	- [Literal Values](http://handlebarsjs.com/#literals)
65	- [Delimited Comments](http://handlebarsjs.com/#comments)
66
67	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.
68
69	### Compatibility
70
71	There are a few Mustache behaviors that Handlebars does not implement.
72	- Handlebars deviates from Mustache slightly in that it does not perform recursive lookup by default. The compile time `compat` flag must be set to enable this functionality. Users should note that there is a performance cost for enabling this flag. The exact cost varies by template, but it's recommended that performance sensitive operations should avoid this mode and instead opt for explicit path references.
73	- The optional Mustache-style lambdas are not supported. Instead Handlebars provides its own lambda resolution that follows the behaviors of helpers.
74	- Alternative delimiters are not supported.
75
76
77	Supported Environments
78	----------------------
79
80	Handlebars has been designed to work in any ECMAScript 3 environment. This includes
81
82	- Node.js
83	- Chrome
84	- Firefox
85	- Safari 5+
86	- Opera 11+
87	- IE 6+
88
89	Older versions and other runtimes are likely to work but have not been formally
90	tested. The compiler requires `JSON.stringify` to be implemented natively or via a polyfill. If using the precompiler this is not necessary.
91
92	[![Selenium Test Status](https://saucelabs.com/browser-matrix/handlebars.svg)](https://saucelabs.com/u/handlebars)
93
94	Performance
95	-----------
96
97	In a rough performance test, precompiled Handlebars.js templates (in
98	the original version of Handlebars.js) rendered in about half the
99	time of Mustache templates. It would be a shame if it were any other
100	way, since they were precompiled, but the difference in architecture
101	does have some big performance advantages. Justin Marney, a.k.a.
102	[gotascii](http://github.com/gotascii), confirmed that with an
103	[independent test](http://sorescode.com/2010/09/12/benchmarks.html). The
104	rewritten Handlebars (current version) is faster than the old version,
105	with many [performance tests](https://travis-ci.org/wycats/handlebars.js/builds/33392182#L538) being 5 to 7 times faster than the Mustache equivalent.
106
107
108	Upgrading
109	---------
110
111	See [release-notes.md](https://github.com/wycats/handlebars.js/blob/master/release-notes.md) for upgrade notes.
112
113	Known Issues
114	------------
115
116	See [FAQ.md](https://github.com/wycats/handlebars.js/blob/master/FAQ.md) for known issues and common pitfalls.
117
118
119	Handlebars in the Wild
120	----------------------
121
122	* [Assemble](http://assemble.io), by [@jonschlinkert](https://github.com/jonschlinkert)
123	and [@doowb](https://github.com/doowb), is a static site generator that uses Handlebars.js
124	as its template engine.
125	* [Cory](https://github.com/leo/cory), by [@leo](https://github.com/leo), is another tiny static site generator
126	* [CoSchedule](http://coschedule.com) An editorial calendar for WordPress that uses Handlebars.js
127	* [dashbars](https://github.com/pismute/dashbars) A modern helper library for Handlebars.js.
128	* [Ember.js](http://www.emberjs.com) makes Handlebars.js the primary way to
129	structure your views, also with automatic data binding support.
130	* [Ghost](https://ghost.org/) Just a blogging platform.
131	* [handlebars_assets](http://github.com/leshill/handlebars_assets): A Rails Asset Pipeline gem
132	from Les Hill (@leshill).
133	* [handlebars-helpers](https://github.com/assemble/handlebars-helpers) is an extensive library
134	with 100+ handlebars helpers.
135	* [handlebars-layouts](https://github.com/shannonmoeller/handlebars-layouts) is a set of helpers which implement extendible and embeddable layout blocks as seen in other popular templating languages.
136	* [hbs](http://github.com/donpark/hbs): An Express.js view engine adapter for Handlebars.js,
137	from Don Park.
138	* [koa-hbs](https://github.com/jwilm/koa-hbs): [koa](https://github.com/koajs/koa) generator based
139	renderer for Handlebars.js.
140	* [jblotus](http://github.com/jblotus) created [http://tryhandlebarsjs.com](http://tryhandlebarsjs.com)
141	for anyone who would like to try out Handlebars.js in their browser.
142	* [jQuery plugin](http://71104.github.io/jquery-handlebars/): allows you to use
143	Handlebars.js with [jQuery](http://jquery.com/).
144	* [Lumbar](http://walmartlabs.github.io/lumbar) provides easy module-based template management for
145	handlebars projects.
146	* [Marionette.Handlebars](https://github.com/hashchange/marionette.handlebars) adds support for Handlebars and Mustache templates to Marionette.
147	* [sammy.js](http://github.com/quirkey/sammy) by Aaron Quint, a.k.a. quirkey,
148	supports Handlebars.js as one of its template plugins.
149	* [SproutCore](http://www.sproutcore.com) uses Handlebars.js as its main
150	templating engine, extending it with automatic data binding support.
151	* [YUI](http://yuilibrary.com/yui/docs/handlebars/) implements a port of handlebars
152	* [Swag](https://github.com/elving/swag) by [@elving](https://github.com/elving) is a growing collection of helpers for handlebars.js. Give your handlebars.js templates some swag son!
153	* [DOMBars](https://github.com/blakeembrey/dombars) is a DOM-based templating engine built on the Handlebars parser and runtime DEPRECATED
154	* [promised-handlebars](https://github.com/nknapp/promised-handlebars) is a wrapper for Handlebars that allows helpers to return Promises.
155	* [just-handlebars-helpers](https://github.com/leapfrogtechnology/just-handlebars-helpers) A fully tested lightweight package with common Handlebars helpers.
156
157	External Resources
158	------------------
159
160	* [Gist about Synchronous and asynchronous loading of external handlebars templates](https://gist.github.com/2287070)
161
162	Have a project using Handlebars? Send us a [pull request][pull-request]!
163
164	License
165	-------
166	Handlebars.js is released under the MIT license.
167
168	[pull-request]: https://github.com/wycats/handlebars.js/pull/new/master
169