From a3d32fea25b5ab67c7ad8c2a45b51a4a0aac0773 Mon Sep 17 00:00:00 2001 From: Michael Jackson Date: Thu, 12 Jan 2012 15:45:37 -0800 Subject: [PATCH] wip --- README.md | 215 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 195 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 7d941df..a7c35d3 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# mustache.js — Logic-less {{mustache}} templates with JavaScript +# mustache.js - Logic-less {{mustache}} templates with JavaScript > What could be more logical awesome than no logic at all? @@ -39,42 +39,217 @@ Below is quick example how to use mustache.js: } }; - var html = Mustache.to_html("{{title}} spends {{calc}}", view); + var html = Mustache.render("{{title}} spends {{calc}}", view); -In this example, the `Mustache.to_html` function takes two parameters: 1) the +In this example, the `Mustache.render` function takes two parameters: 1) the [mustache](http://mustache.github.com/) template and 2) a `view` object that contains the data and code needed to render the template. +## Templates -## Template Tag Types +A [mustache](http://mustache.github.com/) template is a string that contains +any number of mustache tags. Tags are indicated by the double mustaches that +surround them. *{{person}}* is a tag, as is *{{#person}}*. In both examples we +refer to *person* as the tag's key. -There are several types of tags currently implemented in mustache.js. +There are several types of tags available in mustache.js. -### Simple Tags +### Variables -Tags are always surrounded by mustaches like this `{{foobar}}`. +The most basic tag type is a simple variable. A *{{name}}* tag renders the value +of the *name* key in the current context. If there is no such key, nothing is +rendered. - var view = {name: "Joe", say_hello: function(){ return "hello" }} +All variables are HTML-escaped by default. If you want to render unescaped HTML, +use the triple mustache: *{{{name}}}*. You can also use *&* to unescape a +variable. - template = "{{say_hello}}, {{name}}" +Template: + + * {{name}} + * {{age}} + * {{company}} + * {{{company}}} + * {{&company}} + +View: + + { + "name": "Chris", + "company": "GitHub" + } + +Output: + + * Chris + * + * <b>GitHub</b> + * GitHub + * GitHub + +JavaScript's dot notation may be used to access keys that are properties of +objects in a view. + +Template: + + * {{name.first}} {{name.last}} + * {{age}} + +View: + + { + "name": { + "first": "Michael", + "last": "Jackson" + }, + "age": "RIP" + } + +Output: + + * Michael Jackson + * RIP -#### Accessing values in nested objects (Dot Notation) +### Sections -To access data logically grouped into nested objects, specify a '.' delimited -path to the value. +Sections render blocks of text one or more times, depending on the value of the +key in the current context. - var contact = { - name: {first: "Bill", last: "Bobitybob" }, - age: 37 +A section begins with a pound and ends with a slash. That is, *{{#person}}* +begins a *person* section, while *{{/person}}* ends it. The text between the two +tags is referred to as that section's "block". + +The behavior of the section is determined by the value of the key. + +#### False Values or Empty Lists + +If the *person* key exists and has a value of `null`, `undefined`, or `false`, +or is an empty list, the block will not be rendered. + +Template: + + Shown. + {{#nothin}} + Never shown! + {{/nothin}} + +View: + + { + "person": true, } - template = "Hello, {{name.first}} {{name.last}}. You are {{age}} years old." +Output: + + Shown. + +#### Non-Empty Lists + +If the *person* key exists and is not `null`, `undefined`, or `false`, and is +not an empty list the block will be rendered one or more times. + +When the value is a list, the block is rendered once for each item in the list. +The context of the block is set to the current item in the list for each +iteration. In this way we can loop over collections. + +Template: + + {{#stooges}} + {{name}} + {{/stooges}} + +View: + + { + "stooges": [ + { "name": "Moe" }, + { "name": "Larry" }, + { "name": "Curly" }, + ] + } + +Output: + + Moe + Larry + Curly + +When looping over an array of strings, a `.` can be used to refer to the current +item in the list. + +Template: + + {{#musketeers}} + * {{.}} + {{/musketeers}} + +View: + + { + "musketeers": ["Athos", "Aramis", "Porthos", "D'Artagnan"] + } + +Output: + + * Athos + * Aramis + * Porthos + * D'Artagnan + + +#### Functions + +If the value of a key is a function, it is called with the section's literal +block of text, unrendered, as its first argument. The second argument is a +special rendering function that uses the current view as its view argument. It +is called in the context of the current view object. + + +Template: + + {{#users}} + {{#employee}} + * {{email}} + {{/employee}} + {{/users}} + +View: + + { + "domain": "example.com", + "users": [ + { "handle": "joe", "employee": true }, + { "handle": "bob", "employee": false }, + { "handle": "jim", "employee": true } + ], + "employee": function () { + this. + }, + "email": function () { + return function (text, render) { + return this.handle + "@" + this.domain; + } + } + } + +Output: + + * joe@example.com + * bob@example.com + * jim@example.com + * Porthos + * D'Artagnan + + +TODO - pick up here + + + + + + -*NOTICE*: The dot notation feature was recently implemented for the 0.4 - release, which is not out as of Nov 9 2011. You can find the feature in the - current master branch of mustachejs. -### Conditional Sections Conditional sections begin with `{{#condition}}` and end with `{{/condition}}`. When `condition` evaluates to true, the section is rendered,