X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6746dc89c47ed01b165cc1152533605f97eb8e8d..HEAD:/src/Template.js

diff --git a/src/Template.js b/src/Template.js
index c3714047..77f1b0b0 100644
--- a/src/Template.js
+++ b/src/Template.js
@@ -13,69 +13,65 @@ If you are unsure which license is appropriate for your use, please contact the
 
 */
 /**
- * @class Ext.Template
- * <p>Represents an HTML fragment template. Templates may be {@link #compile precompiled}
- * for greater performance.</p>
- * An instance of this class may be created by passing to the constructor either
- * a single argument, or multiple arguments:
- * <div class="mdetail-params"><ul>
- * <li><b>single argument</b> : String/Array
- * <div class="sub-desc">
- * The single argument may be either a String or an Array:<ul>
- * <li><tt>String</tt> : </li><pre><code>
-var t = new Ext.Template("&lt;div>Hello {0}.&lt;/div>");
-t.{@link #append}('some-element', ['foo']);
-   </code></pre>
- * <li><tt>Array</tt> : </li>
- * An Array will be combined with <code>join('')</code>.
-<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.{@link #compile}();
-t.{@link #append}('some-element', {id: 'myid', cls: 'myclass', name: 'foo', value: 'bar'});
-   </code></pre>
- * </ul></div></li>
- * <li><b>multiple arguments</b> : String, Object, Array, ...
- * <div class="sub-desc">
- * Multiple arguments will be combined with <code>join('')</code>.
- * <pre><code>
-var t = new Ext.Template(
-    '&lt;div name="{id}"&gt;',
-        '&lt;span class="{cls}"&gt;{name} {value}&lt;/span&gt;',
-    '&lt;/div&gt;',
-    // a configuration object:
-    {
-        compiled: true,      // {@link #compile} immediately
-    }
-);
-   </code></pre>
- * <p><b>Notes</b>:</p>
- * <div class="mdetail-params"><ul>
- * <li>For a list of available format functions, see {@link Ext.util.Format}.</li>
- * <li><code>disableFormats</code> reduces <code>{@link #apply}</code> time
- * when no formatting is required.</li>
- * </ul></div>
- * </div></li>
- * </ul></div>
- * @param {Mixed} config
+ * Represents an HTML fragment template. Templates may be {@link #compile precompiled} for greater performance.
+ *
+ * An instance of this class may be created by passing to the constructor either a single argument, or multiple
+ * arguments:
+ *
+ * # Single argument: String/Array
+ *
+ * The single argument may be either a String or an Array:
+ *
+ * - String:
+ *
+ *       var t = new Ext.Template("<div>Hello {0}.</div>");
+ *       t.{@link #append}('some-element', ['foo']);
+ *
+ * - Array:
+ *
+ *   An Array will be combined with `join('')`.
+ *
+ *       var t = new Ext.Template([
+ *           '<div name="{id}">',
+ *               '<span class="{cls}">{name:trim} {value:ellipsis(10)}</span>',
+ *           '</div>',
+ *       ]);
+ *       t.{@link #compile}();
+ *       t.{@link #append}('some-element', {id: 'myid', cls: 'myclass', name: 'foo', value: 'bar'});
+ *
+ * # Multiple arguments: String, Object, Array, ...
+ *
+ * Multiple arguments will be combined with `join('')`.
+ *
+ *     var t = new Ext.Template(
+ *         '<div name="{id}">',
+ *             '<span class="{cls}">{name} {value}</span>',
+ *         '</div>',
+ *         // a configuration object:
+ *         {
+ *             compiled: true,      // {@link #compile} immediately
+ *         }
+ *     );
+ *
+ * # Notes
+ *
+ * - For a list of available format functions, see {@link Ext.util.Format}.
+ * - `disableFormats` reduces `{@link #apply}` time when no formatting is required.
  */
-
 Ext.define('Ext.Template', {
 
     /* Begin Definitions */
 
-    requires: ['Ext.core.DomHelper', 'Ext.util.Format'],
+    requires: ['Ext.DomHelper', 'Ext.util.Format'],
 
-    statics: {
+    inheritableStatics: {
         /**
-         * Creates a template from the passed element's value (<i>display:none</i> textarea, preferred) or innerHTML.
+         * Creates a template from the passed element's value (_display:none_ textarea, preferred) or innerHTML.
          * @param {String/HTMLElement} el A DOM element or its id
-         * @param {Object} config A configuration object
+         * @param {Object} config (optional) Config object
          * @return {Ext.Template} The created template
          * @static
+         * @inheritable
          */
         from: function(el, config) {
             el = Ext.getDom(el);
@@ -85,6 +81,13 @@ Ext.define('Ext.Template', {
 
     /* End Definitions */
 
+    /**
+     * Creates new template.
+     * 
+     * @param {String...} html List of strings to be concatenated into template.
+     * Alternatively an array of strings can be given, but then no config object may be passed.
+     * @param {Object} config (optional) Config object
+     */
     constructor: function(html) {
         var me = this,
             args = arguments,
@@ -121,17 +124,36 @@ Ext.define('Ext.Template', {
             me.compile();
         }
     },
+
     isTemplate: true,
+
+    /**
+     * @cfg {Boolean} compiled
+     * True to immediately compile the template. Defaults to false.
+     */
+
     /**
-     * @cfg {Boolean} disableFormats true to disable format functions in the template. If the template doesn't contain format functions, setting
-     * disableFormats to true will reduce apply time (defaults to false)
+     * @cfg {Boolean} disableFormats
+     * True to disable format functions in the template. If the template doesn't contain
+     * format functions, setting disableFormats to true will reduce apply time. Defaults to false.
      */
     disableFormats: false,
 
     re: /\{([\w\-]+)(?:\:([\w\.]*)(?:\((.*?)?\))?)?\}/g,
+
     /**
      * 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'})
+     *
+     * @param {Object/Array} values The template values. Can be an array if your params are numeric:
+     *
+     *     var tpl = new Ext.Template('Name: {0}, Age: {1}');
+     *     tpl.applyTemplate(['John', 25]);
+     *
+     * or an object:
+     *
+     *     var tpl = new Ext.Template('Name: {name}, Age: {age}');
+     *     tpl.applyTemplate({name: 'John', age: 25});
+     *
      * @return {String} The HTML fragment
      */
     applyTemplate: function(values) {
@@ -167,7 +189,7 @@ Ext.define('Ext.Template', {
     /**
      * 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)
+     * @param {Boolean} compile (optional) True to compile the template.
      * @return {Ext.Template} this
      */
     set: function(html, compile) {
@@ -180,6 +202,7 @@ Ext.define('Ext.Template', {
     compileARe: /\\/g,
     compileBRe: /(\r\n|\n)/g,
     compileCRe: /'/g,
+
     /**
      * Compiles the template into an internal function, eliminating the RegEx overhead.
      * @return {Ext.Template} this
@@ -215,10 +238,11 @@ Ext.define('Ext.Template', {
 
     /**
      * 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.core.Element (defaults to undefined)
-     * @return {HTMLElement/Ext.core.Element} The new node or Element
+     *
+     * @param {String/HTMLElement/Ext.Element} el The context element
+     * @param {Object/Array} values The template values. See {@link #applyTemplate} for details.
+     * @param {Boolean} returnElement (optional) true to return a Ext.Element.
+     * @return {HTMLElement/Ext.Element} The new node or Element
      */
     insertFirst: function(el, values, returnElement) {
         return this.doInsert('afterBegin', el, values, returnElement);
@@ -226,10 +250,11 @@ Ext.define('Ext.Template', {
 
     /**
      * 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.core.Element (defaults to undefined)
-     * @return {HTMLElement/Ext.core.Element} The new node or Element
+     *
+     * @param {String/HTMLElement/Ext.Element} el The context element
+     * @param {Object/Array} values The template values. See {@link #applyTemplate} for details.
+     * @param {Boolean} returnElement (optional) true to return a Ext.Element.
+     * @return {HTMLElement/Ext.Element} The new node or Element
      */
     insertBefore: function(el, values, returnElement) {
         return this.doInsert('beforeBegin', el, values, returnElement);
@@ -237,25 +262,25 @@ Ext.define('Ext.Template', {
 
     /**
      * 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.core.Element (defaults to undefined)
-     * @return {HTMLElement/Ext.core.Element} The new node or Element
+     *
+     * @param {String/HTMLElement/Ext.Element} el The context element
+     * @param {Object/Array} values The template values. See {@link #applyTemplate} for details.
+     * @param {Boolean} returnElement (optional) true to return a Ext.Element.
+     * @return {HTMLElement/Ext.Element} The new node or Element
      */
     insertAfter: function(el, values, returnElement) {
         return this.doInsert('afterEnd', el, values, returnElement);
     },
 
     /**
-     * Applies the supplied <code>values</code> to the template and appends
-     * the new node(s) to the specified <code>el</code>.
-     * <p>For example usage {@link #Template see the constructor}.</p>
-     * @param {Mixed} el The context element
-     * @param {Object/Array} values
-     * The template values. Can be an array if the params are numeric (i.e. <code>{0}</code>)
-     * or an object (i.e. <code>{foo: 'bar'}</code>).
-     * @param {Boolean} returnElement (optional) true to return an Ext.core.Element (defaults to undefined)
-     * @return {HTMLElement/Ext.core.Element} The new node or Element
+     * Applies the supplied `values` to the template and appends the new node(s) to the specified `el`.
+     *
+     * For example usage see {@link Ext.Template Ext.Template class docs}.
+     *
+     * @param {String/HTMLElement/Ext.Element} el The context element
+     * @param {Object/Array} values The template values. See {@link #applyTemplate} for details.
+     * @param {Boolean} returnElement (optional) true to return an Ext.Element.
+     * @return {HTMLElement/Ext.Element} The new node or Element
      */
     append: function(el, values, returnElement) {
         return this.doInsert('beforeEnd', el, values, returnElement);
@@ -263,16 +288,17 @@ Ext.define('Ext.Template', {
 
     doInsert: function(where, el, values, returnEl) {
         el = Ext.getDom(el);
-        var newNode = Ext.core.DomHelper.insertHtml(where, el, this.applyTemplate(values));
+        var newNode = Ext.DomHelper.insertHtml(where, el, this.applyTemplate(values));
         return returnEl ? Ext.get(newNode, true) : newNode;
     },
 
     /**
      * 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.core.Element (defaults to undefined)
-     * @return {HTMLElement/Ext.core.Element} The new node or Element
+     *
+     * @param {String/HTMLElement/Ext.Element} el The context element
+     * @param {Object/Array} values The template values. See {@link #applyTemplate} for details.
+     * @param {Boolean} returnElement (optional) true to return a Ext.Element.
+     * @return {HTMLElement/Ext.Element} The new node or Element
      */
     overwrite: function(el, values, returnElement) {
         el = Ext.getDom(el);
@@ -282,14 +308,10 @@ Ext.define('Ext.Template', {
 }, function() {
 
     /**
-     * Alias for {@link #applyTemplate}
-     * Returns an HTML fragment of this template with the specified <code>values</code> applied.
-     * @param {Object/Array} values
-     * The template values. Can be an array if the params are numeric (i.e. <code>{0}</code>)
-     * or an object (i.e. <code>{foo: 'bar'}</code>).
-     * @return {String} The HTML fragment
-     * @member Ext.Template
      * @method apply
+     * @member Ext.Template
+     * Alias for {@link #applyTemplate}.
+     * @alias Ext.Template#applyTemplate
      */
     this.createAlias('apply', 'applyTemplate');
 });