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