Upgrade to ExtJS 3.0.0 - Released 07/06/2009
[extjs.git] / docs / source / Template.html
diff --git a/docs/source/Template.html b/docs/source/Template.html
new file mode 100644 (file)
index 0000000..7385b3d
--- /dev/null
@@ -0,0 +1,188 @@
+<html>\r
+<head>\r
+  <title>The source code</title>\r
+    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
+    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
+</head>\r
+<body  onload="prettyPrint();">\r
+    <pre class="prettyprint lang-js"><div id="cls-Ext.Template"></div>/**
+ * @class Ext.Template
+ * Represents an HTML fragment template. Templates can be precompiled for greater performance.
+ * For a list of available format functions, see {@link Ext.util.Format}.<br />
+ * Usage:
+<pre><code>
+var t = new Ext.Template(
+    '&lt;div name="{id}"&gt;',
+        '&lt;span class="{cls}"&gt;{name:trim} {value:ellipsis(10)}&lt;/span&gt;',
+    '&lt;/div&gt;'
+);
+t.append('some-element', {id: 'myid', cls: 'myclass', name: 'foo', value: 'bar'});
+</code></pre>
+ * @constructor
+ * @param {String/Array} html The HTML fragment or an array of fragments to join("") or multiple arguments to join("")
+ */
+Ext.Template = function(html){
+    var me = this,
+       a = arguments,
+       buf = [];
+
+    if (Ext.isArray(html)) {
+        html = html.join("");
+    } else if (a.length > 1) {
+           Ext.each(a, function(v) {
+            if (Ext.isObject(v)) {
+                Ext.apply(me, v);
+            } else {
+                buf.push(v);
+            }
+        });
+        html = buf.join('');
+    }
+
+    /**@private*/
+    me.html = html;
+    if (me.compiled) {
+        me.compile();
+    }
+};
+Ext.Template.prototype = {
+    <div id="method-Ext.Template-applyTemplate"></div>/**
+     * Returns an HTML fragment of this template with the specified values applied.
+     * @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'})
+     * @return {String} The HTML fragment
+     */
+    applyTemplate : function(values){
+               var me = this;
+
+        return me.compiled ?
+                       me.compiled(values) :
+                               me.html.replace(me.re, function(m, name){
+                               return values[name] !== undefined ? values[name] : "";
+                       });
+       },
+
+    <div id="method-Ext.Template-set"></div>/**
+     * Sets the HTML used as the template and optionally compiles it.
+     * @param {String} html
+     * @param {Boolean} compile (optional) True to compile the template (defaults to undefined)
+     * @return {Ext.Template} this
+     */
+    set : function(html, compile){
+           var me = this;
+        me.html = html;
+        me.compiled = null;
+        return compile ? me.compile() : me;
+    },
+
+    <div id="prop-Ext.Template-re"></div>/**
+    * The regular expression used to match template variables
+    * @type RegExp
+    * @property
+    */
+    re : /\{([\w-]+)\}/g,
+
+    <div id="method-Ext.Template-compile"></div>/**
+     * Compiles the template into an internal function, eliminating the RegEx overhead.
+     * @return {Ext.Template} this
+     */
+    compile : function(){
+        var me = this,
+               sep = Ext.isGecko ? "+" : ",";
+
+        function fn(m, name){                        
+               name = "values['" + name + "']";
+               return "'"+ sep + '(' + name + " == undefined ? '' : " + name + ')' + sep + "'";
+        }
+                
+        eval("this.compiled = function(values){ return " + (Ext.isGecko ? "'" : "['") +
+             me.html.replace(/\\/g, '\\\\').replace(/(\r\n|\n)/g, '\\n').replace(/'/g, "\\'").replace(this.re, fn) +
+             (Ext.isGecko ?  "';};" : "'].join('');};"));
+        return me;
+    },
+
+    <div id="method-Ext.Template-insertFirst"></div>/**
+     * Applies the supplied values to the template and inserts the new node(s) as the first child of el.
+     * @param {Mixed} el The context element
+     * @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'})
+     * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
+     * @return {HTMLElement/Ext.Element} The new node or Element
+     */
+    insertFirst: function(el, values, returnElement){
+        return this.doInsert('afterBegin', el, values, returnElement);
+    },
+
+    <div id="method-Ext.Template-insertBefore"></div>/**
+     * Applies the supplied values to the template and inserts the new node(s) before el.
+     * @param {Mixed} el The context element
+     * @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'})
+     * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
+     * @return {HTMLElement/Ext.Element} The new node or Element
+     */
+    insertBefore: function(el, values, returnElement){
+        return this.doInsert('beforeBegin', el, values, returnElement);
+    },
+
+    <div id="method-Ext.Template-insertAfter"></div>/**
+     * Applies the supplied values to the template and inserts the new node(s) after el.
+     * @param {Mixed} el The context element
+     * @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'})
+     * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
+     * @return {HTMLElement/Ext.Element} The new node or Element
+     */
+    insertAfter : function(el, values, returnElement){
+        return this.doInsert('afterEnd', el, values, returnElement);
+    },
+
+    <div id="method-Ext.Template-append"></div>/**
+     * Applies the supplied values to the template and appends the new node(s) to el.
+     * @param {Mixed} el The context element
+     * @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'})
+     * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
+     * @return {HTMLElement/Ext.Element} The new node or Element
+     */
+    append : function(el, values, returnElement){
+        return this.doInsert('beforeEnd', el, values, returnElement);
+    },
+
+    doInsert : function(where, el, values, returnEl){
+        el = Ext.getDom(el);
+        var newNode = Ext.DomHelper.insertHtml(where, el, this.applyTemplate(values));
+        return returnEl ? Ext.get(newNode, true) : newNode;
+    },
+
+    <div id="method-Ext.Template-overwrite"></div>/**
+     * Applies the supplied values to the template and overwrites the content of el with the new node(s).
+     * @param {Mixed} el The context element
+     * @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'})
+     * @param {Boolean} returnElement (optional) true to return a Ext.Element (defaults to undefined)
+     * @return {HTMLElement/Ext.Element} The new node or Element
+     */
+    overwrite : function(el, values, returnElement){
+        el = Ext.getDom(el);
+        el.innerHTML = this.applyTemplate(values);
+        return returnElement ? Ext.get(el.firstChild, true) : el.firstChild;
+    }
+};
+<div id="method-Ext.Template-apply"></div>/**
+ * Alias for {@link #applyTemplate}
+ * Returns an HTML fragment of this template with the specified values applied.
+ * @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'})
+ * @return {String} The HTML fragment
+ * @member Ext.Template
+ * @method apply
+ */
+Ext.Template.prototype.apply = Ext.Template.prototype.applyTemplate;
+
+<div id="method-Ext.Template-Template.from"></div>/**
+ * Creates a template from the passed element's value (<i>display:none</i> textarea, preferred) or innerHTML.
+ * @param {String/HTMLElement} el A DOM element or its id
+ * @param {Object} config A configuration object
+ * @return {Ext.Template} The created template
+ * @static
+ */
+Ext.Template.from = function(el, config){
+    el = Ext.getDom(el);
+    return new Ext.Template(el.value || el.innerHTML, config || '');
+};</pre>    \r
+</body>\r
+</html>
\ No newline at end of file