lib/yuilib/3.13.0/template-base/template-base.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-base', function (Y, NAME) {
   9
  10 /**
  11 Virtual rollup of the `template-base` and `template-micro` modules.
  12
  13 @module template
  14 @main template
  15 @since 3.8.0
  16 **/
  17
  18 /**
  19 Provides a generic API for using template engines such as Handlebars and
  20 `Y.Template.Micro`.
  21
  22 @module template
  23 @submodule template-base
  24 @since 3.8.0
  25 **/
  26
  27 /**
  28 Provides a generic API for using template engines such as Handlebars and
  29 `Y.Template.Micro`.
  30
  31 ### Examples
  32
  33 Using with `Y.Template.Micro` (the default template engine):
  34
  35     YUI().use('template', function (Y) {
  36         var micro = new Y.Template(),
  37             html  = micro.render('<%= data.message %>', {message: 'hello!'});
  38
  39         // ...
  40     });
  41
  42 Using with Handlebars:
  43
  44     YUI().use('template-base', 'handlebars', function (Y) {
  45         var handlebars = new Y.Template(Y.Handlebars),
  46             html       = handlebars.render('{{message}}', {message: 'hello!'});
  47
  48         // ...
  49     });
  50
  51 @class Template
  52 @param {Mixed} [engine=Y.Template.Micro] Template engine to use, such as
  53     `Y.Template.Micro` or `Y.Handlebars`. Defaults to `Y.Template.Micro` if not
  54     specified.
  55 @param {Object} [defaults] Default options to use when instance methods are
  56     invoked.
  57 @constructor
  58 @since 3.8.0
  59 **/
  60
  61 function Template(engine, defaults) {
  62     /**
  63     Default options.
  64
  65     @property {Object} defaults
  66     @since 3.8.1
  67     **/
  68     this.defaults = defaults;
  69
  70     /**
  71     Template engine class.
  72
  73     @property {Mixed} engine
  74     @since 3.8.0
  75     **/
  76     this.engine = engine || Y.Template.Micro;
  77
  78     if (!this.engine) {
  79         Y.error('No template engine loaded.');
  80     }
  81 }
  82
  83 /**
  84 Registry that maps template names to revived template functions.
  85
  86 @property _registry
  87 @type Object
  88 @static
  89 @protected
  90 @since 3.12.0
  91 **/
  92 Template._registry = {};
  93
  94 /**
  95 Registers a pre-compiled template into the central template registry with a
  96 given template string, allowing that template to be called and rendered by
  97 that name using the `Y.Template.render()` static method.
  98
  99 For example, given the following simple Handlebars template, in `foo.hbs`:
 100 @example
 101     <p>{{tagline}}</p>
 102
 103 It can be precompiled using the Handlebars CLI, and added into a YUI module
 104 in the following way. Alternatively, `locator` can be used to automate this
 105 process for you:
 106 @example
 107     YUI.add('templates-foo', function (Y) {
 108
 109         var engine = new Y.Template(Y.Handlebars),
 110             precompiled;
 111
 112         precompiled = // Long precompiled template function here //
 113
 114         Y.Template.register('foo', engine.revive(precompiled));
 115
 116     }, '0.0.1', {requires: ['template-base', 'handlebars-base']});
 117
 118 See the `Y.Template#render` method to see how a registered template is used.
 119
 120 @method register
 121 @param {String} templateName The template name.
 122 @param {Function} template The function that returns the rendered string. The
 123     function should take the following parameters. If a pre-compiled template
 124     does not accept these parameters, it is up to the developer to normalize it.
 125   @param {Object} [template.data] Data object to provide when rendering the
 126     template.
 127   @param {Object} [template.options] Options to pass along to the template
 128     engine. See template engine docs for options supported by each engine.
 129 @return {Function} revivedTemplate This is the same function as in `template`,
 130     and is done to maintain compatibility with the `Y.Template#revive()` method.
 131 @static
 132 @since 3.12.0
 133 **/
 134 Template.register = function (templateName, template) {
 135     Template._registry[templateName] = template;
 136     return template;
 137 };
 138
 139 /**
 140 Returns the registered template function, given the template name. If an
 141 unregistered template is accessed, this will return `undefined`.
 142
 143 @method get
 144 @param {String} templateName The template name.
 145 @return {Function} revivedTemplate The revived template function, or `undefined`
 146     if it has not been registered.
 147 @static
 148 @since 3.12.0
 149 **/
 150
 151 Template.get = function (templateName) {
 152     return Template._registry[templateName];
 153 }
 154
 155 /**
 156 Renders a template into a string, given the registered template name and data
 157 to be interpolated. The template name must have been registered previously with
 158 `register()`.
 159
 160 Once the template has been registered and built into a YUI module, it can be
 161 listed as a dependency for any other YUI module. Continuing from the above
 162 example, the registered template can be used in the following way:
 163
 164 @example
 165     YUI.add('bar', function (Y) {
 166
 167         var html = Y.Template.render('foo', {
 168             tagline: '"bar" is now template language agnostic'
 169         });
 170
 171     }, '0.0.1', {requires: ['template-base', 'templates-foo']});
 172
 173 The template can now be used without having to know which specific rendering
 174 engine generated it.
 175
 176 @method render
 177 @param {String} templateName The abstracted name to reference the template.
 178 @param {Object} [data] The data to be interpolated into the template.
 179 @param {Object} [options] Any additional options to be passed into the template.
 180 @return {String} output The rendered result.
 181 @static
 182 @since 3.12.0
 183 **/
 184 Template.render = function (templateName, data, options) {
 185     var template = Template._registry[templateName],
 186         result   = '';
 187
 188     if (template) {
 189         result = template(data, options);
 190     } else {
 191         Y.error('Unregistered template: "' + templateName + '"');
 192     }
 193
 194     return result;
 195 };
 196
 197 Template.prototype = {
 198     /**
 199     Compiles a template with the current template engine and returns a compiled
 200     template function.
 201
 202     @method compile
 203     @param {String} text Template text to compile.
 204     @param {Object} [options] Options to pass along to the template engine. See
 205         template engine docs for options supported by each engine.
 206     @return {Function} Compiled template function.
 207     @since 3.8.0
 208     **/
 209     compile: function (text, options) {
 210         options = options ? Y.merge(this.defaults, options) : this.defaults;
 211         return this.engine.compile(text, options);
 212     },
 213
 214     /**
 215     Precompiles a template with the current template engine and returns a string
 216     containing JavaScript source code for the precompiled template.
 217
 218     @method precompile
 219     @param {String} text Template text to compile.
 220     @param {Object} [options] Options to pass along to the template engine. See
 221         template engine docs for options supported by each engine.
 222     @return {String} Source code for the precompiled template.
 223     @since 3.8.0
 224     **/
 225     precompile: function (text, options) {
 226         options = options ? Y.merge(this.defaults, options) : this.defaults;
 227         return this.engine.precompile(text, options);
 228     },
 229
 230     /**
 231     Compiles and renders a template with the current template engine in a single
 232     step, and returns the rendered result.
 233
 234     @method render
 235     @param {String} text Template text to render.
 236     @param {Object} data Data object to provide when rendering the template.
 237     @param {Object} [options] Options to pass along to the template engine. See
 238         template engine docs for options supported by each engine.
 239     @return {String} Rendered result.
 240     @since 3.8.0
 241     **/
 242     render: function (text, data, options) {
 243         options = options ? Y.merge(this.defaults, options) : this.defaults;
 244
 245         if (this.engine.render) {
 246             return this.engine.render(text, data, options);
 247         }
 248
 249         return this.engine.compile(text, options)(data, options);
 250     },
 251
 252     /**
 253     Revives a precompiled template function into an executable template function
 254     using the current template engine. The precompiled code must already have
 255     been evaluated; this method won't evaluate it for you.
 256
 257     @method revive
 258     @param {Function} precompiled Precompiled template function.
 259     @param {Object} [options] Options to pass along to the template engine. See
 260         template engine docs for options supported by each engine.
 261     @return {Function} Compiled template function.
 262     @since 3.8.0
 263     **/
 264     revive: function (precompiled, options) {
 265         options = options ? Y.merge(this.defaults, options) : this.defaults;
 266
 267         return this.engine.revive ? this.engine.revive(precompiled, options) :
 268                 precompiled;
 269     }
 270 };
 271
 272 // Copy existing namespaced properties from Y.Template to the Template function
 273 // if Y.Template already exists, then make the function the new Y.Template.
 274 // This ensures that other modules can safely add stuff to the Y.Template
 275 // namespace even if they're loaded before this one.
 276 Y.Template = Y.Template ? Y.mix(Template, Y.Template) : Template;
 277
 278
 279 }, '3.13.0', {"requires": ["yui-base"]});