src/XTemplate.js

   1 /**
   2  * @class Ext.XTemplate
   3  * @extends Ext.Template
   4  * <p>A template class that supports advanced functionality like:<div class="mdetail-params"><ul>
   5  * <li>Autofilling arrays using templates and sub-templates</li>
   6  * <li>Conditional processing with basic comparison operators</li>
   7  * <li>Basic math function support</li>
   8  * <li>Execute arbitrary inline code with special built-in template variables</li>
   9  * <li>Custom member functions</li>
  10  * <li>Many special tags and built-in operators that aren't defined as part of
  11  * the API, but are supported in the templates that can be created</li>
  12  * </ul></div></p>
  13  * <p>XTemplate provides the templating mechanism built into:<div class="mdetail-params"><ul>
  14  * <li>{@link Ext.view.View}</li>
  15  * </ul></div></p>
  16  *
  17  * The {@link Ext.Template} describes
  18  * the acceptable parameters to pass to the constructor. The following
  19  * examples demonstrate all of the supported features.</p>
  20  *
  21  * <div class="mdetail-params"><ul>
  22  *
  23  * <li><b><u>Sample Data</u></b>
  24  * <div class="sub-desc">
  25  * <p>This is the data object used for reference in each code example:</p>
  26  * <pre><code>
  27 var data = {
  28 name: 'Tommy Maintz',
  29 title: 'Lead Developer',
  30 company: 'Sencha Inc.',
  31 email: 'tommy@sencha.com',
  32 address: '5 Cups Drive',
  33 city: 'Palo Alto',
  34 state: 'CA',
  35 zip: '44102',
  36 drinks: ['Coffee', 'Soda', 'Water'],
  37 kids: [{
  38         name: 'Joshua',
  39         age:3
  40     },{
  41         name: 'Matthew',
  42         age:2
  43     },{
  44         name: 'Solomon',
  45         age:0
  46 }]
  47 };
  48  </code></pre>
  49  * </div>
  50  * </li>
  51  *
  52  *
  53  * <li><b><u>Auto filling of arrays</u></b>
  54  * <div class="sub-desc">
  55  * <p>The <b><tt>tpl</tt></b> tag and the <b><tt>for</tt></b> operator are used
  56  * to process the provided data object:
  57  * <ul>
  58  * <li>If the value specified in <tt>for</tt> is an array, it will auto-fill,
  59  * repeating the template block inside the <tt>tpl</tt> tag for each item in the
  60  * array.</li>
  61  * <li>If <tt>for="."</tt> is specified, the data object provided is examined.</li>
  62  * <li>While processing an array, the special variable <tt>{#}</tt>
  63  * will provide the current array index + 1 (starts at 1, not 0).</li>
  64  * </ul>
  65  * </p>
  66  * <pre><code>
  67 &lt;tpl <b>for</b>=".">...&lt;/tpl>       // loop through array at root node
  68 &lt;tpl <b>for</b>="foo">...&lt;/tpl>     // loop through array at foo node
  69 &lt;tpl <b>for</b>="foo.bar">...&lt;/tpl> // loop through array at foo.bar node
  70  </code></pre>
  71  * Using the sample data above:
  72  * <pre><code>
  73 var tpl = new Ext.XTemplate(
  74     '&lt;p>Kids: ',
  75     '&lt;tpl <b>for</b>=".">',       // process the data.kids node
  76         '&lt;p>{#}. {name}&lt;/p>',  // use current array index to autonumber
  77     '&lt;/tpl>&lt;/p>'
  78 );
  79 tpl.overwrite(panel.body, data.kids); // pass the kids property of the data object
  80  </code></pre>
  81  * <p>An example illustrating how the <b><tt>for</tt></b> property can be leveraged
  82  * to access specified members of the provided data object to populate the template:</p>
  83  * <pre><code>
  84 var tpl = new Ext.XTemplate(
  85     '&lt;p>Name: {name}&lt;/p>',
  86     '&lt;p>Title: {title}&lt;/p>',
  87     '&lt;p>Company: {company}&lt;/p>',
  88     '&lt;p>Kids: ',
  89     '&lt;tpl <b>for="kids"</b>>',     // interrogate the kids property within the data
  90         '&lt;p>{name}&lt;/p>',
  91     '&lt;/tpl>&lt;/p>'
  92 );
  93 tpl.overwrite(panel.body, data);  // pass the root node of the data object
  94  </code></pre>
  95  * <p>Flat arrays that contain values (and not objects) can be auto-rendered
  96  * using the special <b><tt>{.}</tt></b> variable inside a loop.  This variable
  97  * will represent the value of the array at the current index:</p>
  98  * <pre><code>
  99 var tpl = new Ext.XTemplate(
 100     '&lt;p>{name}\&#39;s favorite beverages:&lt;/p>',
 101     '&lt;tpl for="drinks">',
 102         '&lt;div> - {.}&lt;/div>',
 103     '&lt;/tpl>'
 104 );
 105 tpl.overwrite(panel.body, data);
 106  </code></pre>
 107  * <p>When processing a sub-template, for example while looping through a child array,
 108  * you can access the parent object's members via the <b><tt>parent</tt></b> object:</p>
 109  * <pre><code>
 110 var tpl = new Ext.XTemplate(
 111     '&lt;p>Name: {name}&lt;/p>',
 112     '&lt;p>Kids: ',
 113     '&lt;tpl for="kids">',
 114         '&lt;tpl if="age &amp;gt; 1">',
 115             '&lt;p>{name}&lt;/p>',
 116             '&lt;p>Dad: {<b>parent</b>.name}&lt;/p>',
 117         '&lt;/tpl>',
 118     '&lt;/tpl>&lt;/p>'
 119 );
 120 tpl.overwrite(panel.body, data);
 121  </code></pre>
 122  * </div>
 123  * </li>
 124  *
 125  *
 126  * <li><b><u>Conditional processing with basic comparison operators</u></b>
 127  * <div class="sub-desc">
 128  * <p>The <b><tt>tpl</tt></b> tag and the <b><tt>if</tt></b> operator are used
 129  * to provide conditional checks for deciding whether or not to render specific
 130  * parts of the template. Notes:<div class="sub-desc"><ul>
 131  * <li>Double quotes must be encoded if used within the conditional</li>
 132  * <li>There is no <tt>else</tt> operator &mdash; if needed, two opposite
 133  * <tt>if</tt> statements should be used.</li>
 134  * </ul></div>
 135  * <pre><code>
 136 &lt;tpl if="age &gt; 1 &amp;&amp; age &lt; 10">Child&lt;/tpl>
 137 &lt;tpl if="age >= 10 && age < 18">Teenager&lt;/tpl>
 138 &lt;tpl <b>if</b>="this.isGirl(name)">...&lt;/tpl>
 139 &lt;tpl <b>if</b>="id==\'download\'">...&lt;/tpl>
 140 &lt;tpl <b>if</b>="needsIcon">&lt;img src="{icon}" class="{iconCls}"/>&lt;/tpl>
 141 // no good:
 142 &lt;tpl if="name == "Tommy"">Hello&lt;/tpl>
 143 // encode &#34; if it is part of the condition, e.g.
 144 &lt;tpl if="name == &#38;quot;Tommy&#38;quot;">Hello&lt;/tpl>
 145  * </code></pre>
 146  * Using the sample data above:
 147  * <pre><code>
 148 var tpl = new Ext.XTemplate(
 149     '&lt;p>Name: {name}&lt;/p>',
 150     '&lt;p>Kids: ',
 151     '&lt;tpl for="kids">',
 152         '&lt;tpl if="age &amp;gt; 1">',
 153             '&lt;p>{name}&lt;/p>',
 154         '&lt;/tpl>',
 155     '&lt;/tpl>&lt;/p>'
 156 );
 157 tpl.overwrite(panel.body, data);
 158  </code></pre>
 159  * </div>
 160  * </li>
 161  *
 162  *
 163  * <li><b><u>Basic math support</u></b>
 164  * <div class="sub-desc">
 165  * <p>The following basic math operators may be applied directly on numeric
 166  * data values:</p><pre>
 167  * + - * /
 168  * </pre>
 169  * For example:
 170  * <pre><code>
 171 var tpl = new Ext.XTemplate(
 172     '&lt;p>Name: {name}&lt;/p>',
 173     '&lt;p>Kids: ',
 174     '&lt;tpl for="kids">',
 175         '&lt;tpl if="age &amp;gt; 1">',  // <-- Note that the &gt; is encoded
 176             '&lt;p>{#}: {name}&lt;/p>',  // <-- Auto-number each item
 177             '&lt;p>In 5 Years: {age+5}&lt;/p>',  // <-- Basic math
 178             '&lt;p>Dad: {parent.name}&lt;/p>',
 179         '&lt;/tpl>',
 180     '&lt;/tpl>&lt;/p>'
 181 );
 182 tpl.overwrite(panel.body, data);
 183  </code></pre>
 184  * </div>
 185  * </li>
 186  *
 187  *
 188  * <li><b><u>Execute arbitrary inline code with special built-in template variables</u></b>
 189  * <div class="sub-desc">
 190  * <p>Anything between <code>{[ ... ]}</code> is considered code to be executed
 191  * in the scope of the template. There are some special variables available in that code:
 192  * <ul>
 193  * <li><b><tt>values</tt></b>: The values in the current scope. If you are using
 194  * scope changing sub-templates, you can change what <tt>values</tt> is.</li>
 195  * <li><b><tt>parent</tt></b>: The scope (values) of the ancestor template.</li>
 196  * <li><b><tt>xindex</tt></b>: If you are in a looping template, the index of the
 197  * loop you are in (1-based).</li>
 198  * <li><b><tt>xcount</tt></b>: If you are in a looping template, the total length
 199  * of the array you are looping.</li>
 200  * </ul>
 201  * This example demonstrates basic row striping using an inline code block and the
 202  * <tt>xindex</tt> variable:</p>
 203  * <pre><code>
 204 var tpl = new Ext.XTemplate(
 205     '&lt;p>Name: {name}&lt;/p>',
 206     '&lt;p>Company: {[values.company.toUpperCase() + ", " + values.title]}&lt;/p>',
 207     '&lt;p>Kids: ',
 208     '&lt;tpl for="kids">',
 209         '&lt;div class="{[xindex % 2 === 0 ? "even" : "odd"]}">',
 210         '{name}',
 211         '&lt;/div>',
 212     '&lt;/tpl>&lt;/p>'
 213  );
 214 tpl.overwrite(panel.body, data);
 215  </code></pre>
 216  * </div>
 217  * </li>
 218  *
 219  * <li><b><u>Template member functions</u></b>
 220  * <div class="sub-desc">
 221  * <p>One or more member functions can be specified in a configuration
 222  * object passed into the XTemplate constructor for more complex processing:</p>
 223  * <pre><code>
 224 var tpl = new Ext.XTemplate(
 225     '&lt;p>Name: {name}&lt;/p>',
 226     '&lt;p>Kids: ',
 227     '&lt;tpl for="kids">',
 228         '&lt;tpl if="this.isGirl(name)">',
 229             '&lt;p>Girl: {name} - {age}&lt;/p>',
 230         '&lt;/tpl>',
 231          // use opposite if statement to simulate 'else' processing:
 232         '&lt;tpl if="this.isGirl(name) == false">',
 233             '&lt;p>Boy: {name} - {age}&lt;/p>',
 234         '&lt;/tpl>',
 235         '&lt;tpl if="this.isBaby(age)">',
 236             '&lt;p>{name} is a baby!&lt;/p>',
 237         '&lt;/tpl>',
 238     '&lt;/tpl>&lt;/p>',
 239     {
 240         // XTemplate configuration:
 241         compiled: true,
 242         // member functions:
 243         isGirl: function(name){
 244            return name == 'Sara Grace';
 245         },
 246         isBaby: function(age){
 247            return age < 1;
 248         }
 249     }
 250 );
 251 tpl.overwrite(panel.body, data);
 252  </code></pre>
 253  * </div>
 254  * </li>
 255  *
 256  * </ul></div>
 257  *
 258  * @param {Mixed} config
 259  */
 260
 261 Ext.define('Ext.XTemplate', {
 262
 263     /* Begin Definitions */
 264
 265     extend: 'Ext.Template',
 266
 267     statics: {
 268         /**
 269          * Creates a template from the passed element's value (<i>display:none</i> textarea, preferred) or innerHTML.
 270          * @param {String/HTMLElement} el A DOM element or its id
 271          * @return {Ext.Template} The created template
 272          * @static
 273          */
 274         from: function(el, config) {
 275             el = Ext.getDom(el);
 276             return new this(el.value || el.innerHTML, config || {});
 277         }
 278     },
 279
 280     /* End Definitions */
 281
 282     argsRe: /<tpl\b[^>]*>((?:(?=([^<]+))\2|<(?!tpl\b[^>]*>))*?)<\/tpl>/,
 283     nameRe: /^<tpl\b[^>]*?for="(.*?)"/,
 284     ifRe: /^<tpl\b[^>]*?if="(.*?)"/,
 285     execRe: /^<tpl\b[^>]*?exec="(.*?)"/,
 286     constructor: function() {
 287         this.callParent(arguments);
 288
 289         var me = this,
 290             html = me.html,
 291             argsRe = me.argsRe,
 292             nameRe = me.nameRe,
 293             ifRe = me.ifRe,
 294             execRe = me.execRe,
 295             id = 0,
 296             tpls = [],
 297             VALUES = 'values',
 298             PARENT = 'parent',
 299             XINDEX = 'xindex',
 300             XCOUNT = 'xcount',
 301             RETURN = 'return ',
 302             WITHVALUES = 'with(values){ ',
 303             m, matchName, matchIf, matchExec, exp, fn, exec, name, i;
 304
 305         html = ['<tpl>', html, '</tpl>'].join('');
 306
 307         while ((m = html.match(argsRe))) {
 308             exp = null;
 309             fn = null;
 310             exec = null;
 311             matchName = m[0].match(nameRe);
 312             matchIf = m[0].match(ifRe);
 313             matchExec = m[0].match(execRe);
 314
 315             exp = matchIf ? matchIf[1] : null;
 316             if (exp) {
 317                 fn = Ext.functionFactory(VALUES, PARENT, XINDEX, XCOUNT, WITHVALUES + 'try{' + RETURN + Ext.String.htmlDecode(exp) + ';}catch(e){return;}}');
 318             }
 319
 320             exp = matchExec ? matchExec[1] : null;
 321             if (exp) {
 322                 exec = Ext.functionFactory(VALUES, PARENT, XINDEX, XCOUNT, WITHVALUES + Ext.String.htmlDecode(exp) + ';}');
 323             }
 324
 325             name = matchName ? matchName[1] : null;
 326             if (name) {
 327                 if (name === '.') {
 328                     name = VALUES;
 329                 } else if (name === '..') {
 330                     name = PARENT;
 331                 }
 332                 name = Ext.functionFactory(VALUES, PARENT, 'try{' + WITHVALUES + RETURN + name + ';}}catch(e){return;}');
 333             }
 334
 335             tpls.push({
 336                 id: id,
 337                 target: name,
 338                 exec: exec,
 339                 test: fn,
 340                 body: m[1] || ''
 341             });
 342
 343             html = html.replace(m[0], '{xtpl' + id + '}');
 344             id = id + 1;
 345         }
 346
 347         for (i = tpls.length - 1; i >= 0; --i) {
 348             me.compileTpl(tpls[i]);
 349         }
 350         me.master = tpls[tpls.length - 1];
 351         me.tpls = tpls;
 352     },
 353
 354     // @private
 355     applySubTemplate: function(id, values, parent, xindex, xcount) {
 356         var me = this, t = me.tpls[id];
 357         return t.compiled.call(me, values, parent, xindex, xcount);
 358     },
 359     /**
 360      * @cfg {RegExp} codeRe The regular expression used to match code variables (default: matches <tt>{[expression]}</tt>).
 361      */
 362     codeRe: /\{\[((?:\\\]|.|\n)*?)\]\}/g,
 363
 364     re: /\{([\w-\.\#]+)(?:\:([\w\.]*)(?:\((.*?)?\))?)?(\s?[\+\-\*\/]\s?[\d\.\+\-\*\/\(\)]+)?\}/g,
 365
 366     // @private
 367     compileTpl: function(tpl) {
 368         var fm = Ext.util.Format,
 369             me = this,
 370             useFormat = me.disableFormats !== true,
 371             body, bodyReturn, evaluatedFn;
 372
 373         function fn(m, name, format, args, math) {
 374             var v;
 375             // name is what is inside the {}
 376             // Name begins with xtpl, use a Sub Template
 377             if (name.substr(0, 4) == 'xtpl') {
 378                 return "',this.applySubTemplate(" + name.substr(4) + ", values, parent, xindex, xcount),'";
 379             }
 380             // name = "." - Just use the values object.
 381             if (name == '.') {
 382                 // filter to not include arrays/objects/nulls
 383                 v = 'Ext.Array.indexOf(["string", "number", "boolean"], typeof values) > -1 || Ext.isDate(values) ? values : ""';
 384             }
 385
 386             // name = "#" - Use the xindex
 387             else if (name == '#') {
 388                 v = 'xindex';
 389             }
 390             else if (name.substr(0, 7) == "parent.") {
 391                 v = name;
 392             }
 393             // name has a . in it - Use object literal notation, starting from values
 394             else if (name.indexOf('.') != -1) {
 395                 v = "values." + name;
 396             }
 397
 398             // name is a property of values
 399             else {
 400                 v = "values['" + name + "']";
 401             }
 402             if (math) {
 403                 v = '(' + v + math + ')';
 404             }
 405             if (format && useFormat) {
 406                 args = args ? ',' + args : "";
 407                 if (format.substr(0, 5) != "this.") {
 408                     format = "fm." + format + '(';
 409                 }
 410                 else {
 411                     format = 'this.' + format.substr(5) + '(';
 412                 }
 413             }
 414             else {
 415                 args = '';
 416                 format = "(" + v + " === undefined ? '' : ";
 417             }
 418             return "'," + format + v + args + "),'";
 419         }
 420
 421         function codeFn(m, code) {
 422             // Single quotes get escaped when the template is compiled, however we want to undo this when running code.
 423             return "',(" + code.replace(me.compileARe, "'") + "),'";
 424         }
 425
 426         bodyReturn = tpl.body.replace(me.compileBRe, '\\n').replace(me.compileCRe, "\\'").replace(me.re, fn).replace(me.codeRe, codeFn);
 427         body = "evaluatedFn = function(values, parent, xindex, xcount){return ['" + bodyReturn + "'].join('');};";
 428         eval(body);
 429
 430         tpl.compiled = function(values, parent, xindex, xcount) {
 431             var vs,
 432                 length,
 433                 buffer,
 434                 i;
 435
 436             if (tpl.test && !tpl.test.call(me, values, parent, xindex, xcount)) {
 437                 return '';
 438             }
 439
 440             vs = tpl.target ? tpl.target.call(me, values, parent) : values;
 441             if (!vs) {
 442                return '';
 443             }
 444
 445             parent = tpl.target ? values : parent;
 446             if (tpl.target && Ext.isArray(vs)) {
 447                 buffer = [];
 448                 length = vs.length;
 449                 if (tpl.exec) {
 450                     for (i = 0; i < length; i++) {
 451                         buffer[buffer.length] = evaluatedFn.call(me, vs[i], parent, i + 1, length);
 452                         tpl.exec.call(me, vs[i], parent, i + 1, length);
 453                     }
 454                 } else {
 455                     for (i = 0; i < length; i++) {
 456                         buffer[buffer.length] = evaluatedFn.call(me, vs[i], parent, i + 1, length);
 457                     }
 458                 }
 459                 return buffer.join('');
 460             }
 461
 462             if (tpl.exec) {
 463                 tpl.exec.call(me, vs, parent, xindex, xcount);
 464             }
 465             return evaluatedFn.call(me, vs, parent, xindex, xcount);
 466         };
 467
 468         return this;
 469     },
 470
 471     /**
 472      * Returns an HTML fragment of this template with the specified values applied.
 473      * @param {Object} values The template values. Can be an array if your params are numeric (i.e. {0}) or an object (i.e. {foo: 'bar'})
 474      * @return {String} The HTML fragment
 475      */
 476     applyTemplate: function(values) {
 477         return this.master.compiled.call(this, values, {}, 1, 1);
 478     },
 479
 480     /**
 481      * Compile the template to a function for optimized performance.  Recommended if the template will be used frequently.
 482      * @return {Function} The compiled function
 483      */
 484     compile: function() {
 485         return this;
 486     }
 487 }, function() {
 488     /**
 489      * Alias for {@link #applyTemplate}
 490      * Returns an HTML fragment of this template with the specified values applied.
 491      * @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'})
 492      * @return {String} The HTML fragment
 493      * @member Ext.XTemplate
 494      * @method apply
 495      */
 496     this.createAlias('apply', 'applyTemplate');
 497 });