Permalink
Browse files

Initial commit.

  • Loading branch information...
0 parents commit 961c3598226e4f7d0f3c9d26ac80222cd7ace920 @lharding lharding committed Mar 3, 2012
Showing with 583 additions and 0 deletions.
  1. +3 −0 .gitignore
  2. +7 −0 LICENSE
  3. +102 −0 README.md
  4. +90 −0 gordito.js
  5. +381 −0 translate_mustache.py
@@ -0,0 +1,3 @@
+.svn
+.project
+.pydevproject
@@ -0,0 +1,7 @@
+Copyright (c) 2012 Yahoo! Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
102 README.md
@@ -0,0 +1,102 @@
+Gordito
+=======
+
+An even faster (and possibly easier) Mustache Rendering Tool
+------------------------------------------------------------
+
+Gordito is an implementation of a subset of the [Mustache][1] templating language. Rather than interpreting templates at runtime, it transpiles your templates to executable Javascript or PHP code for maximum performance.
+
+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).
+
+### Is it worth it?
+
+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.
+
+Supported Functionality
+-----------------------
+
+* Variable substitution: {{identifier}} --> Value of context.identifier, same semantics as normal Mustache.
+* 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.
+* Inverse Sections: {{^identifier}}Stuff!{{/identifier}} --> Outputs "Stuff!" if context.identifier is falsy. Same semantics as normal mustache.
+* Partials: {{> filename}} --> Render "filename.mu" from the working directory. Same semantics as normal mustache.
+* Localization string namespace: Variable substitutions of the form {{str_identifier}} will perform a localization string lookup. See the usage section for details.
+
+Important Unsupported Functionality
+-----------------------------------
+
+* 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.
+* The triple-mustache {{{no_escape}}} substitution (because of the above).
+* Everything else.
+
+Usage
+-----
+
+### Use the Source, Luke!
+
+The documentation below is intended as a rough guide, and should be read alongside the source code of gordito for a full picture.
+
+### Transpiling
+
+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).
+
+The available options are as follows:
+
+-f, --f The mustache template to process
+-r, --rollup Rollup this template and it's dependencies into a single file.
+-o, --output The output file of this generated template
+-b, --basepath Directory in which to search for partials
+-d, --baseoutpath Directory to place output in. Overridden by -o, but not for partials.
+-t, --type Whether to output Javascript or PHP [must be 'php' or 'js']
+
+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.
+
+### Rendering
+
+#### Javascript
+
+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:
+
+Your JS code:
+
+ //Intl Strings for Klingon/ISO-8859 phoenetic
+ TemplateRenderer.setIntlStrings({
+ success: "QAPLA'",
+ thanks: "QA TLHO'"
+ });
+
+ var output = TemplateRenderer.render("it_worked");
+
+ //output now contains the rendered template
+
+it_worked.mu:
+
+ <h1 style="color: #f00; bgcolor: 000">{{str_success}}</h1>
+ {{str_thanks}}
+
+#### PHP
+
+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:
+
+ //$filename is the template to render, $ctx is the view object
+ public function renderTemplate($filename, $ctx) {
+ $stk = array(); //needed by the generated templates
+ $_TEMPLATE_BASE = self::$TEMPLATES; //directory to find templates in
+
+ include(self::$TEMPLATES.$filename);
+ }
+
+Roadmap
+-------
+
+* Finish implementing Mustache featureset (pull requests welcome!)
+* JS DOM API output target for maximum performance in the browser.
+* More languages?
+* Formal performance tests showing exactly how much of a win this thing is.
+
+Legalese
+--------
+Copyright (c) 2012 Yahoo! Inc. All rights reserved.
+Copyrights licensed under the MIT License. See the accompanying LICENSE file
+for terms.
+
+[1] https://github.com/janl/mustache.js/ "Mustache.js"
@@ -0,0 +1,90 @@
+/*
+Copyright (c) 2012 Yahoo! Inc. All rights reserved.
+Copyrights licensed under the MIT License. See the accompanying LICENSE file
+for terms.
+*/
+
+YUI.add('gordito', function(Y){
+ var _strings = [];
+
+ function _setIntlStrings(strMap) {
+ _strings = strMap;
+ }
+
+ function _handleHashsign(__closure, __varname, __ctx, __world) {
+ var __var = __ctx[__varname];
+
+ if(__var) {
+ if(typeof(__var) !== 'object') {
+ __closure(__ctx, __world);
+ }
+ else if(__var instanceof Array) {
+ for (var i = 0; i < __var.length; i++) {
+ __closure(__var[i], __world);
+ }
+ }
+ else {
+ __closure(__var, __world);
+ }
+ }
+ }
+
+ function _getString(strname, ctx, world) {
+ var str = _strings[strname];
+
+ //Return blank if str is not found.
+ if(!str) {
+ return "";
+ }
+
+ if(str.indexOf("{{") >= 0) {
+ var start = 0, res = "", end = 0, name = "";
+
+ while(true) {
+ end = str.indexOf("{{", start);
+ if(end === -1) {
+ res += str.slice(start, str.length);
+ break;
+ }
+
+ res += str.slice(start, end);
+
+ start = str.indexOf("}}", end)+2;
+
+ name = str.slice(end+2, start-2);
+
+ if(name.indexOf("str_") === 0) {
+ res += _strings[name];
+ }
+ else {
+ res += ctx[name];
+ }
+ }
+
+ return res;
+ }
+
+ return str;
+ }
+
+ function _render(templateName, data) {
+ var world = {
+ ctx : data,
+ templates : Y.ui.MuTemplates,
+ outbuffer : [],
+ strings : _getString,
+ handleHashsign: _handleHashsign
+ };
+
+ Y.ui.MuTemplates[templateName](data, world);
+ return world.outbuffer.join('');
+ }
+
+ Y.namespace('tools.gordito');
+ Y.tools.gordito.TemplateRenderer = {
+ getString: _getString,
+ setIntlStrings: _setIntlStrings,
+ render: _render
+ };
+
+}, '1.0.0',{requires:[]});
Oops, something went wrong.

0 comments on commit 961c359

Please sign in to comment.