[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 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.17.2', {"requires": ["yui-base"]});