Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 103 lines (68 sloc) 5.129 kb
961c359 Leander Harding Initial commit.
lharding authored
1 Gordito
2 =======
3
4 An even faster (and possibly easier) Mustache Rendering Tool
5 ------------------------------------------------------------
6
9644fd9 Leander Harding Tweaked readme formatting for github.
lharding authored
7 Gordito is an implementation of a subset of the [Mustache](https://github.com/janl/mustache.js/) templating language. Rather than interpreting templates at runtime, it transpiles your templates to executable Javascript or PHP code for maximum performance.
961c359 Leander Harding Initial commit.
lharding authored
8
9 This should be considered to be a "developer preview" style release - although the API isn't expected to change significantly, only a limited subset of mustache is implemented (although, we find this sufficient to render the new Yahoo! Address Book).
10
11 ### Is it worth it?
12
13 That's up to you. Our own informal tests show about a 10x rendering speedup over interpreted solutions like dust.js or other Mustache renderers, and the JS output is similar in size to the original mustache templates, and can be minified by your minifier. The support code is 2K unminified.
14
15 Supported Functionality
16 -----------------------
17
18 * Variable substitution: {{identifier}} --> Value of context.identifier, same semantics as normal Mustache.
19 * Sections: {{#identifier}}Stuff!{{/identifier}} --> Outputs "Stuff!" if context.identifier is truthy, n repetitions of "Stuff!" if context.identifier is a list of length n, etc. Same semantics as normal Mustache.
20 * Inverse Sections: {{^identifier}}Stuff!{{/identifier}} --> Outputs "Stuff!" if context.identifier is falsy. Same semantics as normal mustache.
21 * Partials: {{> filename}} --> Render "filename.mu" from the working directory. Same semantics as normal mustache.
22 * Localization string namespace: Variable substitutions of the form {{str_identifier}} will perform a localization string lookup. See the usage section for details.
23
24 Important Unsupported Functionality
25 -----------------------------------
26
27 * Escaping and unescaping. Data sanitization is up to you. Unlike most mustache renderers, Gordito passes markup and any other data straight through - what you get is the toString() of whatever's in your view object.
28 * The triple-mustache {{{no_escape}}} substitution (because of the above).
29 * Everything else.
30
31 Usage
32 -----
33
34 ### Use the Source, Luke!
35
36 The documentation below is intended as a rough guide, and should be read alongside the source code of gordito for a full picture.
37
38 ### Transpiling
39
40 To transpile your templates, run the translate_mustache.py script. You will need a makefile or other mechanism to process multiple files as the script operates on one template at a time (with the exception that it will search a specified directory for any necessary partials, and produce a mirroring output directory structure for transpiled partials).
41
42 The available options are as follows:
43
9644fd9 Leander Harding Tweaked readme formatting for github.
lharding authored
44 -f, --f The mustache template to process
45 -r, --rollup Rollup this template and it's dependencies into a single file.
46 -o, --output The output file of this generated template
47 -b, --basepath Directory in which to search for partials
48 -d, --baseoutpath Directory to place output in. Overridden by -o, but not for partials.
49 -t, --type Whether to output Javascript or PHP [must be 'php' or 'js']
961c359 Leander Harding Initial commit.
lharding authored
50
51 Outputting JS creates a YUI module per file. Inspecting the code should make it obvious how to replace this with your favorite flavor of JS module system.
52
53 ### Rendering
54
55 #### Javascript
56
57 Use the included gordito.js module to render templates - simply call it's render method with the name of the template you want to render. To use the localization string mechanism, create a hash mapping your localization strings to their values for the current locale, and pass it to TemplateRenderer.setIntlStrings method. For example:
58
59 Your JS code:
60
61 //Intl Strings for Klingon/ISO-8859 phoenetic
62 TemplateRenderer.setIntlStrings({
63 success: "QAPLA'",
64 thanks: "QA TLHO'"
65 });
66
67 var output = TemplateRenderer.render("it_worked");
68
69 //output now contains the rendered template
70
71 it_worked.mu:
72
73 <h1 style="color: #f00; bgcolor: 000">{{str_success}}</h1>
74 {{str_thanks}}
75
76 #### PHP
77
78 Templates are compiled to .inc files named after the input file names. To use, simply include() the relevant template with the correct scope. To set up the scope, the following function may be useful:
79
80 //$filename is the template to render, $ctx is the view object
81 public function renderTemplate($filename, $ctx) {
82 $stk = array(); //needed by the generated templates
83 $_TEMPLATE_BASE = self::$TEMPLATES; //directory to find templates in
84
85 include(self::$TEMPLATES.$filename);
86 }
87
c9a71e5 Leander Harding Added note about PHP localization to REAMDE
lharding authored
88 Using the localization substitution mechanism in PHP will cause the $this->getIString() to be called with the string identifier and the current context object.
89
961c359 Leander Harding Initial commit.
lharding authored
90 Roadmap
91 -------
92
93 * Finish implementing Mustache featureset (pull requests welcome!)
94 * JS DOM API output target for maximum performance in the browser.
95 * More languages?
96 * Formal performance tests showing exactly how much of a win this thing is.
97
98 Legalese
99 --------
100 Copyright (c) 2012 Yahoo! Inc. All rights reserved.
101 Copyrights licensed under the MIT License. See the accompanying LICENSE file
102 for terms.
Something went wrong with that request. Please try again.