src/core/core/Template.js

   1 /*!
   2  * Ext JS Library 3.0.0
   3  * Copyright(c) 2006-2009 Ext JS, LLC
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**
   8  * @class Ext.Template
   9  * Represents an HTML fragment template. Templates can be precompiled for greater performance.
  10  * For a list of available format functions, see {@link Ext.util.Format}.<br />
  11  * Usage:
  12 <pre><code>
  13 var t = new Ext.Template(
  14     '&lt;div name="{id}"&gt;',
  15         '&lt;span class="{cls}"&gt;{name:trim} {value:ellipsis(10)}&lt;/span&gt;',
  16     '&lt;/div&gt;'
  17 );
  18 t.append('some-element', {id: 'myid', cls: 'myclass', name: 'foo', value: 'bar'});
  19 </code></pre>
  20  * @constructor
  21  * @param {String/Array} html The HTML fragment or an array of fragments to join("") or multiple arguments to join("")
  22  */
  23 Ext.Template = function(html){
  24     var me = this,
  25         a = arguments,
  26         buf = [];
  27
  28     if (Ext.isArray(html)) {
  29         html = html.join("");
  30     } else if (a.length > 1) {
  31             Ext.each(a, function(v) {
  32             if (Ext.isObject(v)) {
  33                 Ext.apply(me, v);
  34             } else {
  35                 buf.push(v);
  36             }
  37         });
  38         html = buf.join('');
  39     }
  40
  41     /**@private*/
  42     me.html = html;
  43     if (me.compiled) {
  44         me.compile();
  45     }
  46 };
  47 Ext.Template.prototype = {
  48     /**
  49      * Returns an HTML fragment of this template with the specified values applied.
  50      * @param {Object/Array} values The template values. Can be an array if your params are numeric (i.e. {0}) or an object (i.e. {foo: 'bar'})
  51      * @return {String} The HTML fragment
  52      */
  53     applyTemplate : function(values){
  54                 var me = this;
  55
  56         return me.compiled ?
  57                         me.compiled(values) :
  58                                 me.html.replace(me.re, function(m, name){
  59                                 return values[name] !== undefined ? values[name] : "";
  60                         });
  61         },
  62
  63     /**
  64      * Sets the HTML used as the template and optionally compiles it.
  65      * @param {String} html
  66      * @param {Boolean} compile (optional) True to compile the template (defaults to undefined)
  67      * @return {Ext.Template} this
  68      */
  69     set : function(html, compile){
  70             var me = this;
  71         me.html = html;
  72         me.compiled = null;
  73         return compile ? me.compile() : me;
  74     },
  75
  76     /**
  77     * The regular expression used to match template variables
  78     * @type RegExp
  79     * @property
  80     */
  81     re : /\{([\w-]+)\}/g,
  82
  83     /**
  84      * Compiles the template into an internal function, eliminating the RegEx overhead.
  85      * @return {Ext.Template} this
  86      */
  87     compile : function(){
  88         var me = this,
  89                 sep = Ext.isGecko ? "+" : ",";
  90
  91         function fn(m, name){
  92                 name = "values['" + name + "']";
  93                 return "'"+ sep + '(' + name + " == undefined ? '' : " + name + ')' + sep + "'";
  94         }
  95
  96         eval("this.compiled = function(values){ return " + (Ext.isGecko ? "'" : "['") +
  97              me.html.replace(/\\/g, '\\\\').replace(/(\r\n|\n)/g, '\\n').replace(/'/g, "\\'").replace(this.re, fn) +
  98              (Ext.isGecko ?  "';};" : "'].join('');};"));
  99         return me;
 100     },
 101
 102     /**
 103      * Applies the supplied values to the template and inserts the new node(s) as the first child of el.
 104      * @param {Mixed} el The context element
 105      * @param {Object/Array} values The template values. Can be an array if your params are numeric (i.e. {0}) or an object (i.e. {foo: 'bar'})
 106      * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
 107      * @return {HTMLElement/Ext.Element} The new node or Element
 108      */
 109     insertFirst: function(el, values, returnElement){
 110         return this.doInsert('afterBegin', el, values, returnElement);
 111     },
 112
 113     /**
 114      * Applies the supplied values to the template and inserts the new node(s) before el.
 115      * @param {Mixed} el The context element
 116      * @param {Object/Array} values The template values. Can be an array if your params are numeric (i.e. {0}) or an object (i.e. {foo: 'bar'})
 117      * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
 118      * @return {HTMLElement/Ext.Element} The new node or Element
 119      */
 120     insertBefore: function(el, values, returnElement){
 121         return this.doInsert('beforeBegin', el, values, returnElement);
 122     },
 123
 124     /**
 125      * Applies the supplied values to the template and inserts the new node(s) after el.
 126      * @param {Mixed} el The context element
 127      * @param {Object/Array} values The template values. Can be an array if your params are numeric (i.e. {0}) or an object (i.e. {foo: 'bar'})
 128      * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
 129      * @return {HTMLElement/Ext.Element} The new node or Element
 130      */
 131     insertAfter : function(el, values, returnElement){
 132         return this.doInsert('afterEnd', el, values, returnElement);
 133     },
 134
 135     /**
 136      * Applies the supplied values to the template and appends the new node(s) to el.
 137      * @param {Mixed} el The context element
 138      * @param {Object/Array} values The template values. Can be an array if your params are numeric (i.e. {0}) or an object (i.e. {foo: 'bar'})
 139      * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
 140      * @return {HTMLElement/Ext.Element} The new node or Element
 141      */
 142     append : function(el, values, returnElement){
 143         return this.doInsert('beforeEnd', el, values, returnElement);
 144     },
 145
 146     doInsert : function(where, el, values, returnEl){
 147         el = Ext.getDom(el);
 148         var newNode = Ext.DomHelper.insertHtml(where, el, this.applyTemplate(values));
 149         return returnEl ? Ext.get(newNode, true) : newNode;
 150     },
 151
 152     /**
 153      * Applies the supplied values to the template and overwrites the content of el with the new node(s).
 154      * @param {Mixed} el The context element
 155      * @param {Object/Array} values The template values. Can be an array if your params are numeric (i.e. {0}) or an object (i.e. {foo: 'bar'})
 156      * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
 157      * @return {HTMLElement/Ext.Element} The new node or Element
 158      */
 159     overwrite : function(el, values, returnElement){
 160         el = Ext.getDom(el);
 161         el.innerHTML = this.applyTemplate(values);
 162         return returnElement ? Ext.get(el.firstChild, true) : el.firstChild;
 163     }
 164 };
 165 /**
 166  * Alias for {@link #applyTemplate}
 167  * Returns an HTML fragment of this template with the specified values applied.
 168  * @param {Object/Array} values The template values. Can be an array if your params are numeric (i.e. {0}) or an object (i.e. {foo: 'bar'})
 169  * @return {String} The HTML fragment
 170  * @member Ext.Template
 171  * @method apply
 172  */
 173 Ext.Template.prototype.apply = Ext.Template.prototype.applyTemplate;
 174
 175 /**
 176  * Creates a template from the passed element's value (<i>display:none</i> textarea, preferred) or innerHTML.
 177  * @param {String/HTMLElement} el A DOM element or its id
 178  * @param {Object} config A configuration object
 179  * @return {Ext.Template} The created template
 180  * @static
 181  */
 182 Ext.Template.from = function(el, config){
 183     el = Ext.getDom(el);
 184     return new Ext.Template(el.value || el.innerHTML, config || '');
 185 };