Upgrade to ExtJS 3.3.0 - Released 10/06/2010
[extjs.git] / docs / source / Template.html
1 <html>
2 <head>
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
4   <title>The source code</title>
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
7 </head>
8 <body  onload="prettyPrint();">
9     <pre class="prettyprint lang-js">/*!
10  * Ext JS Library 3.3.0
11  * Copyright(c) 2006-2010 Ext JS, Inc.
12  * licensing@extjs.com
13  * http://www.extjs.com/license
14  */
15 <div id="cls-Ext.Template"></div>/**
16  * @class Ext.Template
17  * <p>Represents an HTML fragment template. Templates may be {@link #compile precompiled}
18  * for greater performance.</p>
19  * <p>For example usage {@link #Template see the constructor}.</p>
20  *
21  * @constructor
22  * An instance of this class may be created by passing to the constructor either
23  * a single argument, or multiple arguments:
24  * <div class="mdetail-params"><ul>
25  * <li><b>single argument</b> : String/Array
26  * <div class="sub-desc">
27  * The single argument may be either a String or an Array:<ul>
28  * <li><tt>String</tt> : </li><pre><code>
29 var t = new Ext.Template("&lt;div>Hello {0}.&lt;/div>");
30 t.{@link #append}('some-element', ['foo']);
31  * </code></pre>
32  * <li><tt>Array</tt> : </li>
33  * An Array will be combined with <code>join('')</code>.
34 <pre><code>
35 var t = new Ext.Template([
36     '&lt;div name="{id}"&gt;',
37         '&lt;span class="{cls}"&gt;{name:trim} {value:ellipsis(10)}&lt;/span&gt;',
38     '&lt;/div&gt;',
39 ]);
40 t.{@link #compile}();
41 t.{@link #append}('some-element', {id: 'myid', cls: 'myclass', name: 'foo', value: 'bar'});
42 </code></pre>
43  * </ul></div></li>
44  * <li><b>multiple arguments</b> : String, Object, Array, ...
45  * <div class="sub-desc">
46  * Multiple arguments will be combined with <code>join('')</code>.
47  * <pre><code>
48 var t = new Ext.Template(
49     '&lt;div name="{id}"&gt;',
50         '&lt;span class="{cls}"&gt;{name} {value}&lt;/span&gt;',
51     '&lt;/div&gt;',
52     // a configuration object:
53     {
54         compiled: true,      // {@link #compile} immediately
55         disableFormats: true // See Notes below.
56     }
57 );
58  * </code></pre>
59  * <p><b>Notes</b>:</p>
60  * <div class="mdetail-params"><ul>
61  * <li>Formatting and <code>disableFormats</code> are not applicable for Ext Core.</li>
62  * <li>For a list of available format functions, see {@link Ext.util.Format}.</li>
63  * <li><code>disableFormats</code> reduces <code>{@link #apply}</code> time
64  * when no formatting is required.</li>
65  * </ul></div>
66  * </div></li>
67  * </ul></div>
68  * @param {Mixed} config
69  */
70 Ext.Template = function(html){
71     var me = this,
72         a = arguments,
73         buf = [],
74         v;
75
76     if (Ext.isArray(html)) {
77         html = html.join("");
78     } else if (a.length > 1) {
79         for(var i = 0, len = a.length; i < len; i++){
80             v = a[i];
81             if(typeof v == 'object'){
82                 Ext.apply(me, v);
83             } else {
84                 buf.push(v);
85             }
86         };
87         html = buf.join('');
88     }
89
90     /**@private*/
91     me.html = html;
92     <div id="cfg-Ext.Template-compiled"></div>/**
93      * @cfg {Boolean} compiled Specify <tt>true</tt> to compile the template
94      * immediately (see <code>{@link #compile}</code>).
95      * Defaults to <tt>false</tt>.
96      */
97     if (me.compiled) {
98         me.compile();
99     }
100 };
101 Ext.Template.prototype = {
102     <div id="cfg-Ext.Template-re"></div>/**
103      * @cfg {RegExp} re The regular expression used to match template variables.
104      * Defaults to:<pre><code>
105      * re : /\{([\w-]+)\}/g                                     // for Ext Core
106      * re : /\{([\w-]+)(?:\:([\w\.]*)(?:\((.*?)?\))?)?\}/g      // for Ext JS
107      * </code></pre>
108      */
109     re : /\{([\w-]+)\}/g,
110     <div id="prop-Ext.Template-re"></div>/**
111      * See <code>{@link #re}</code>.
112      * @type RegExp
113      * @property re
114      */
115
116     <div id="method-Ext.Template-applyTemplate"></div>/**
117      * Returns an HTML fragment of this template with the specified <code>values</code> applied.
118      * @param {Object/Array} values
119      * The template values. Can be an array if the params are numeric (i.e. <code>{0}</code>)
120      * or an object (i.e. <code>{foo: 'bar'}</code>).
121      * @return {String} The HTML fragment
122      */
123     applyTemplate : function(values){
124         var me = this;
125
126         return me.compiled ?
127                 me.compiled(values) :
128                 me.html.replace(me.re, function(m, name){
129                     return values[name] !== undefined ? values[name] : "";
130                 });
131     },
132
133     <div id="method-Ext.Template-set"></div>/**
134      * Sets the HTML used as the template and optionally compiles it.
135      * @param {String} html
136      * @param {Boolean} compile (optional) True to compile the template (defaults to undefined)
137      * @return {Ext.Template} this
138      */
139     set : function(html, compile){
140         var me = this;
141         me.html = html;
142         me.compiled = null;
143         return compile ? me.compile() : me;
144     },
145
146     <div id="method-Ext.Template-compile"></div>/**
147      * Compiles the template into an internal function, eliminating the RegEx overhead.
148      * @return {Ext.Template} this
149      */
150     compile : function(){
151         var me = this,
152             sep = Ext.isGecko ? "+" : ",";
153
154         function fn(m, name){
155             name = "values['" + name + "']";
156             return "'"+ sep + '(' + name + " == undefined ? '' : " + name + ')' + sep + "'";
157         }
158
159         eval("this.compiled = function(values){ return " + (Ext.isGecko ? "'" : "['") +
160              me.html.replace(/\\/g, '\\\\').replace(/(\r\n|\n)/g, '\\n').replace(/'/g, "\\'").replace(this.re, fn) +
161              (Ext.isGecko ?  "';};" : "'].join('');};"));
162         return me;
163     },
164
165     <div id="method-Ext.Template-insertFirst"></div>/**
166      * Applies the supplied values to the template and inserts the new node(s) as the first child of el.
167      * @param {Mixed} el The context element
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      * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
170      * @return {HTMLElement/Ext.Element} The new node or Element
171      */
172     insertFirst: function(el, values, returnElement){
173         return this.doInsert('afterBegin', el, values, returnElement);
174     },
175
176     <div id="method-Ext.Template-insertBefore"></div>/**
177      * Applies the supplied values to the template and inserts the new node(s) before el.
178      * @param {Mixed} el The context element
179      * @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'})
180      * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
181      * @return {HTMLElement/Ext.Element} The new node or Element
182      */
183     insertBefore: function(el, values, returnElement){
184         return this.doInsert('beforeBegin', el, values, returnElement);
185     },
186
187     <div id="method-Ext.Template-insertAfter"></div>/**
188      * Applies the supplied values to the template and inserts the new node(s) after el.
189      * @param {Mixed} el The context element
190      * @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'})
191      * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
192      * @return {HTMLElement/Ext.Element} The new node or Element
193      */
194     insertAfter : function(el, values, returnElement){
195         return this.doInsert('afterEnd', el, values, returnElement);
196     },
197
198     <div id="method-Ext.Template-append"></div>/**
199      * Applies the supplied <code>values</code> to the template and appends
200      * the new node(s) to the specified <code>el</code>.
201      * <p>For example usage {@link #Template see the constructor}.</p>
202      * @param {Mixed} el The context element
203      * @param {Object/Array} values
204      * The template values. Can be an array if the params are numeric (i.e. <code>{0}</code>)
205      * or an object (i.e. <code>{foo: 'bar'}</code>).
206      * @param {Boolean} returnElement (optional) true to return an Ext.Element (defaults to undefined)
207      * @return {HTMLElement/Ext.Element} The new node or Element
208      */
209     append : function(el, values, returnElement){
210         return this.doInsert('beforeEnd', el, values, returnElement);
211     },
212
213     doInsert : function(where, el, values, returnEl){
214         el = Ext.getDom(el);
215         var newNode = Ext.DomHelper.insertHtml(where, el, this.applyTemplate(values));
216         return returnEl ? Ext.get(newNode, true) : newNode;
217     },
218
219     <div id="method-Ext.Template-overwrite"></div>/**
220      * Applies the supplied values to the template and overwrites the content of el with the new node(s).
221      * @param {Mixed} el The context element
222      * @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'})
223      * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
224      * @return {HTMLElement/Ext.Element} The new node or Element
225      */
226     overwrite : function(el, values, returnElement){
227         el = Ext.getDom(el);
228         el.innerHTML = this.applyTemplate(values);
229         return returnElement ? Ext.get(el.firstChild, true) : el.firstChild;
230     }
231 };
232 <div id="method-Ext.Template-apply"></div>/**
233  * Alias for {@link #applyTemplate}
234  * Returns an HTML fragment of this template with the specified <code>values</code> applied.
235  * @param {Object/Array} values
236  * The template values. Can be an array if the params are numeric (i.e. <code>{0}</code>)
237  * or an object (i.e. <code>{foo: 'bar'}</code>).
238  * @return {String} The HTML fragment
239  * @member Ext.Template
240  * @method apply
241  */
242 Ext.Template.prototype.apply = Ext.Template.prototype.applyTemplate;
243
244 <div id="method-Ext.Template-Template.from"></div>/**
245  * Creates a template from the passed element's value (<i>display:none</i> textarea, preferred) or innerHTML.
246  * @param {String/HTMLElement} el A DOM element or its id
247  * @param {Object} config A configuration object
248  * @return {Ext.Template} The created template
249  * @static
250  */
251 Ext.Template.from = function(el, config){
252     el = Ext.getDom(el);
253     return new Ext.Template(el.value || el.innerHTML, config || '');
254 };
255 </pre>    
256 </body>
257 </html>