/**
- * @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("<div>Hello {0}.</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([
- '<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'});
- </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(
- '<div name="{id}">',
- '<span class="{cls}">{name} {value}</span>',
- '</div>',
- // 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: {
- /**
- * Creates a template from the passed element's value (<i>display:none</i> textarea, preferred) or innerHTML.
+ inheritableStatics: {
+ /**
+ * 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);
@@ -88,6 +84,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,
@@ -124,17 +127,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) {
@@ -170,7 +192,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) {
@@ -183,6 +205,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
@@ -218,10 +241,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);
@@ -229,10 +253,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);
@@ -240,25 +265,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);
@@ -266,16 +291,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);
@@ -285,14 +311,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
+ * @method apply
* @member Ext.Template
- * @method apply
+ * Alias for {@link #applyTemplate}.
+ * @alias Ext.Template#applyTemplate
*/
this.createAlias('apply', 'applyTemplate');
});