lib/yuilib/3.13.0/template-micro/template-micro-debug.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('template-micro', function (Y, NAME) {
   9
  10 /*jshint expr:true */
  11
  12 /**
  13 Adds the `Y.Template.Micro` template engine, which provides fast, simple
  14 string-based micro-templating similar to ERB or Underscore templates.
  15
  16 @module template
  17 @submodule template-micro
  18 @since 3.8.0
  19 **/
  20
  21 /**
  22 Fast, simple string-based micro-templating engine similar to ERB or Underscore
  23 templates.
  24
  25 @class Template.Micro
  26 @static
  27 @since 3.8.0
  28 **/
  29
  30 // This code was heavily inspired by Underscore.js's _.template() method
  31 // (written by Jeremy Ashkenas), which was in turn inspired by John Resig's
  32 // micro-templating implementation.
  33
  34 var Micro = Y.namespace('Template.Micro');
  35
  36 /**
  37 Default options for `Y.Template.Micro`.
  38
  39 @property {Object} options
  40
  41     @param {RegExp} [options.code] Regex that matches code blocks like
  42         `<% ... %>`.
  43     @param {RegExp} [options.escapedOutput] Regex that matches escaped output
  44         tags like `<%= ... %>`.
  45     @param {RegExp} [options.rawOutput] Regex that matches raw output tags like
  46         `<%== ... %>`.
  47     @param {RegExp} [options.stringEscape] Regex that matches characters that
  48         need to be escaped inside single-quoted JavaScript string literals.
  49     @param {Object} [options.stringReplace] Hash that maps characters matched by
  50         `stringEscape` to the strings they should be replaced with. If you add
  51         a character to the `stringEscape` regex, you need to add it here too or
  52         it will be replaced with an empty string.
  53
  54 @static
  55 @since 3.8.0
  56 **/
  57 Micro.options = {
  58     code         : /<%([\s\S]+?)%>/g,
  59     escapedOutput: /<%=([\s\S]+?)%>/g,
  60     rawOutput    : /<%==([\s\S]+?)%>/g,
  61     stringEscape : /\\|'|\r|\n|\t|\u2028|\u2029/g,
  62
  63     stringReplace: {
  64         '\\'    : '\\\\',
  65         "'"     : "\\'",
  66         '\r'    : '\\r',
  67         '\n'    : '\\n',
  68         '\t'    : '\\t',
  69         '\u2028': '\\u2028',
  70         '\u2029': '\\u2029'
  71     }
  72 };
  73
  74 /**
  75 Compiles a template string into a JavaScript function. Pass a data object to the
  76 function to render the template using the given data and get back a rendered
  77 string.
  78
  79 Within a template, use `<%= ... %>` to output the value of an expression (where
  80 `...` is the JavaScript expression or data variable to evaluate). The output
  81 will be HTML-escaped by default. To output a raw value without escaping, use
  82 `<%== ... %>`, but be careful not to do this with untrusted user input.
  83
  84 To execute arbitrary JavaScript code within the template without rendering its
  85 output, use `<% ... %>`, where `...` is the code to be executed. This allows the
  86 use of if/else blocks, loops, function calls, etc., although it's recommended
  87 that you avoid embedding anything beyond basic flow control logic in your
  88 templates.
  89
  90 Properties of the data object passed to a template function are made available
  91 on a `data` variable within the scope of the template. So, if you pass in
  92 the object `{message: 'hello!'}`, you can print the value of the `message`
  93 property using `<%= data.message %>`.
  94
  95 @example
  96
  97     YUI().use('template-micro', function (Y) {
  98         var template = '<ul class="<%= data.classNames.list %>">' +
  99                            '<% Y.Array.each(data.items, function (item) { %>' +
 100                                '<li><%= item %></li>' +
 101                            '<% }); %>' +
 102                        '</ul>';
 103
 104         // Compile the template into a function.
 105         var compiled = Y.Template.Micro.compile(template);
 106
 107         // Render the template to HTML, passing in the data to use.
 108         var html = compiled({
 109             classNames: {list: 'demo'},
 110             items     : ['one', 'two', 'three', 'four']
 111         });
 112     });
 113
 114 @method compile
 115 @param {String} text Template text to compile.
 116 @param {Object} [options] Options. If specified, these options will override the
 117     default options defined in `Y.Template.Micro.options`. See the documentation
 118     for that property for details on which options are available.
 119 @return {Function} Compiled template function. Execute this function and pass in
 120     a data object to render the template with the given data.
 121 @static
 122 @since 3.8.0
 123 **/
 124 Micro.compile = function (text, options) {
 125     /*jshint evil:true */
 126
 127     var blocks     = [],
 128         tokenClose = "\uffff",
 129         tokenOpen  = "\ufffe",
 130         source;
 131
 132     options = Y.merge(Micro.options, options);
 133
 134     // Parse the input text into a string of JavaScript code, with placeholders
 135     // for code blocks. Text outside of code blocks will be escaped for safe
 136     // usage within a double-quoted string literal.
 137     //
 138     // $b is a blank string, used to avoid creating lots of string objects.
 139     //
 140     // $v is a function that returns the supplied value if the value is truthy
 141     // or the number 0, or returns an empty string if the value is falsy and not
 142     // 0.
 143     //
 144     // $t is the template string.
 145     source = "var $b='', $v=function (v){return v || v === 0 ? v : $b;}, $t='" +
 146
 147         // U+FFFE and U+FFFF are guaranteed to represent non-characters, so no
 148         // valid UTF-8 string should ever contain them. That means we can freely
 149         // strip them out of the input text (just to be safe) and then use them
 150         // for our own nefarious purposes as token placeholders!
 151         //
 152         // See http://en.wikipedia.org/wiki/Mapping_of_Unicode_characters#Noncharacters
 153         text.replace(/\ufffe|\uffff/g, '')
 154
 155         .replace(options.rawOutput, function (match, code) {
 156             return tokenOpen + (blocks.push("'+\n$v(" + code + ")+\n'") - 1) + tokenClose;
 157         })
 158
 159         .replace(options.escapedOutput, function (match, code) {
 160             return tokenOpen + (blocks.push("'+\n$e($v(" + code + "))+\n'") - 1) + tokenClose;
 161         })
 162
 163         .replace(options.code, function (match, code) {
 164             return tokenOpen + (blocks.push("';\n" + code + "\n$t+='") - 1) + tokenClose;
 165         })
 166
 167         .replace(options.stringEscape, function (match) {
 168             return options.stringReplace[match] || '';
 169         })
 170
 171         // Replace the token placeholders with code.
 172         .replace(/\ufffe(\d+)\uffff/g, function (match, index) {
 173             return blocks[parseInt(index, 10)];
 174         })
 175
 176         // Remove noop string concatenations that have been left behind.
 177         .replace(/\n\$t\+='';\n/g, '\n') +
 178
 179         "';\nreturn $t;";
 180
 181     // If compile() was called from precompile(), return precompiled source.
 182     if (options.precompile) {
 183         return "function (Y, $e, data) {\n" + source + "\n}";
 184     }
 185
 186     // Otherwise, return an executable function.
 187     return this.revive(new Function('Y', '$e', 'data', source));
 188 };
 189
 190 /**
 191 Precompiles the given template text into a string of JavaScript source code that
 192 can be evaluated later in another context (or on another machine) to render the
 193 template.
 194
 195 A common use case is to precompile templates at build time or on the server,
 196 then evaluate the code on the client to render a template. The client only needs
 197 to revive and render the template, avoiding the work of the compilation step.
 198
 199 @method precompile
 200 @param {String} text Template text to precompile.
 201 @param {Object} [options] Options. If specified, these options will override the
 202     default options defined in `Y.Template.Micro.options`. See the documentation
 203     for that property for details on which options are available.
 204 @return {String} Source code for the precompiled template.
 205 @static
 206 @since 3.8.0
 207 **/
 208 Micro.precompile = function (text, options) {
 209     options || (options = {});
 210     options.precompile = true;
 211
 212     return this.compile(text, options);
 213 };
 214
 215 /**
 216 Compiles and renders the given template text in a single step.
 217
 218 This can be useful for single-use templates, but if you plan to render the same
 219 template multiple times, it's much better to use `compile()` to compile it once,
 220 then simply call the compiled function multiple times to avoid recompiling.
 221
 222 @method render
 223 @param {String} text Template text to render.
 224 @param {Object} data Data to pass to the template.
 225 @param {Object} [options] Options. If specified, these options will override the
 226     default options defined in `Y.Template.Micro.options`. See the documentation
 227     for that property for details on which options are available.
 228 @return {String} Rendered result.
 229 @static
 230 @since 3.8.0
 231 **/
 232 Micro.render = function (text, data, options) {
 233     return this.compile(text, options)(data);
 234 };
 235
 236 /**
 237 Revives a precompiled template function into a normal compiled template function
 238 that can be called to render the template. The precompiled function must already
 239 have been evaluated to a function -- you can't pass raw JavaScript code to
 240 `revive()`.
 241
 242 @method revive
 243 @param {Function} precompiled Precompiled template function.
 244 @return {Function} Revived template function, ready to be rendered.
 245 @static
 246 @since 3.8.0
 247 **/
 248 Micro.revive = function (precompiled) {
 249     return function (data) {
 250         data || (data = {});
 251         return precompiled.call(data, Y, Y.Escape.html, data);
 252     };
 253 };
 254
 255
 256 }, '3.13.0', {"requires": ["escape"]});