docs/source/XTemplate.html

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