X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6746dc89c47ed01b165cc1152533605f97eb8e8d..HEAD:/src/XTemplate.js diff --git a/src/XTemplate.js b/src/XTemplate.js index c0c16cba..9ec15949 100644 --- a/src/XTemplate.js +++ b/src/XTemplate.js @@ -13,284 +13,236 @@ If you are unsure which license is appropriate for your use, please contact the */ /** - * @class Ext.XTemplate - * @extends Ext.Template - *
A template class that supports advanced functionality like:
XTemplate provides the templating mechanism built into:
This is the data object used for reference in each code example:
- *
-var data = {
-name: 'Tommy Maintz',
-title: 'Lead Developer',
-company: 'Sencha Inc.',
-email: 'tommy@sencha.com',
-address: '5 Cups Drive',
-city: 'Palo Alto',
-state: 'CA',
-zip: '44102',
-drinks: ['Coffee', 'Soda', 'Water'],
-kids: [{
- name: 'Joshua',
- age:3
- },{
- name: 'Matthew',
- age:2
- },{
- name: 'Solomon',
- age:0
-}]
-};
-
- * The tpl tag and the for operator are used - * to process the provided data object: - *
-<tpl for=".">...</tpl> // loop through array at root node
-<tpl for="foo">...</tpl> // loop through array at foo node
-<tpl for="foo.bar">...</tpl> // loop through array at foo.bar node
-
+ * A template class that supports advanced functionality like:
+ *
+ * - Autofilling arrays using templates and sub-templates
+ * - Conditional processing with basic comparison operators
+ * - Basic math function support
+ * - Execute arbitrary inline code with special built-in template variables
+ * - Custom member functions
+ * - Many special tags and built-in operators that aren't defined as part of the API, but are supported in the templates that can be created
+ *
+ * XTemplate provides the templating mechanism built into:
+ *
+ * - {@link Ext.view.View}
+ *
+ * The {@link Ext.Template} describes the acceptable parameters to pass to the constructor. The following examples
+ * demonstrate all of the supported features.
+ *
+ * # Sample Data
+ *
+ * This is the data object used for reference in each code example:
+ *
+ * var data = {
+ * name: 'Tommy Maintz',
+ * title: 'Lead Developer',
+ * company: 'Sencha Inc.',
+ * email: 'tommy@sencha.com',
+ * address: '5 Cups Drive',
+ * city: 'Palo Alto',
+ * state: 'CA',
+ * zip: '44102',
+ * drinks: ['Coffee', 'Soda', 'Water'],
+ * kids: [
+ * {
+ * name: 'Joshua',
+ * age:3
+ * },
+ * {
+ * name: 'Matthew',
+ * age:2
+ * },
+ * {
+ * name: 'Solomon',
+ * age:0
+ * }
+ * ]
+ * };
+ *
+ * # Auto filling of arrays
+ *
+ * The **tpl** tag and the **for** operator are used to process the provided data object:
+ *
+ * - If the value specified in for is an array, it will auto-fill, repeating the template block inside the tpl
+ * tag for each item in the array.
+ * - If for="." is specified, the data object provided is examined.
+ * - While processing an array, the special variable {#} will provide the current array index + 1 (starts at 1, not 0).
+ *
+ * Examples:
+ *
+ *
-var tpl = new Ext.XTemplate(
- '<p>Kids: ',
- '<tpl for=".">', // process the data.kids node
- '<p>{#}. {name}</p>', // use current array index to autonumber
- '</tpl></p>'
-);
-tpl.overwrite(panel.body, data.kids); // pass the kids property of the data object
-
- * An example illustrating how the for property can be leveraged - * to access specified members of the provided data object to populate the template:
- *
-var tpl = new Ext.XTemplate(
- '<p>Name: {name}</p>',
- '<p>Title: {title}</p>',
- '<p>Company: {company}</p>',
- '<p>Kids: ',
- '<tpl for="kids">', // interrogate the kids property within the data
- '<p>{name}</p>',
- '</tpl></p>'
-);
-tpl.overwrite(panel.body, data); // pass the root node of the data object
-
- * Flat arrays that contain values (and not objects) can be auto-rendered - * using the special {.} variable inside a loop. This variable - * will represent the value of the array at the current index:
- *
-var tpl = new Ext.XTemplate(
- '<p>{name}\'s favorite beverages:</p>',
- '<tpl for="drinks">',
- '<div> - {.}</div>',
- '</tpl>'
-);
-tpl.overwrite(panel.body, data);
-
- * When processing a sub-template, for example while looping through a child array, - * you can access the parent object's members via the parent object:
- *
-var tpl = new Ext.XTemplate(
- '<p>Name: {name}</p>',
- '<p>Kids: ',
- '<tpl for="kids">',
- '<tpl if="age > 1">',
- '<p>{name}</p>',
- '<p>Dad: {parent.name}</p>',
- '</tpl>',
- '</tpl></p>'
-);
-tpl.overwrite(panel.body, data);
-
- * The tpl tag and the if operator are used - * to provide conditional checks for deciding whether or not to render specific - * parts of the template. Notes:
-<tpl if="age > 1 && age < 10">Child</tpl>
-<tpl if="age >= 10 && age < 18">Teenager</tpl>
-<tpl if="this.isGirl(name)">...</tpl>
-<tpl if="id==\'download\'">...</tpl>
-<tpl if="needsIcon"><img src="{icon}" class="{iconCls}"/></tpl>
-// no good:
-<tpl if="name == "Tommy"">Hello</tpl>
-// encode " if it is part of the condition, e.g.
-<tpl if="name == "Tommy"">Hello</tpl>
- *
+ *
+ * var tpl = new Ext.XTemplate(
+ * 'Kids: ',
+ * ' {#}. {name}
Name: {name}
', + * 'Title: {title}
', + * 'Company: {company}
', + * 'Kids: ',
+ * ' {name}
{name}\'s favorite beverages:
', + * 'Name: {name}
', + * 'Kids: ',
+ * ' {name} Dad: {parent.name}
-var tpl = new Ext.XTemplate(
- '<p>Name: {name}</p>',
- '<p>Kids: ',
- '<tpl for="kids">',
- '<tpl if="age > 1">',
- '<p>{name}</p>',
- '</tpl>',
- '</tpl></p>'
-);
-tpl.overwrite(panel.body, data);
-
- * The following basic math operators may be applied directly on numeric - * data values:
- * + - * / - *+ * + * var tpl = new Ext.XTemplate( + * '
Name: {name}
', + * 'Kids: ',
+ * ' {name}
-var tpl = new Ext.XTemplate(
- '<p>Name: {name}</p>',
- '<p>Kids: ',
- '<tpl for="kids">',
- '<tpl if="age > 1">', // <-- Note that the > is encoded
- '<p>{#}: {name}</p>', // <-- Auto-number each item
- '<p>In 5 Years: {age+5}</p>', // <-- Basic math
- '<p>Dad: {parent.name}</p>',
- '</tpl>',
- '</tpl></p>'
-);
-tpl.overwrite(panel.body, data);
-
- * Anything between {[ ... ]}
is considered code to be executed
- * in the scope of the template. There are some special variables available in that code:
- *
-var tpl = new Ext.XTemplate(
- '<p>Name: {name}</p>',
- '<p>Company: {[values.company.toUpperCase() + ", " + values.title]}</p>',
- '<p>Kids: ',
- '<tpl for="kids">',
- '<div class="{[xindex % 2 === 0 ? "even" : "odd"]}">',
- '{name}',
- '</div>',
- '</tpl></p>'
- );
-tpl.overwrite(panel.body, data);
-
- * One or more member functions can be specified in a configuration - * object passed into the XTemplate constructor for more complex processing:
- *
-var tpl = new Ext.XTemplate(
- '<p>Name: {name}</p>',
- '<p>Kids: ',
- '<tpl for="kids">',
- '<tpl if="this.isGirl(name)">',
- '<p>Girl: {name} - {age}</p>',
- '</tpl>',
- // use opposite if statement to simulate 'else' processing:
- '<tpl if="this.isGirl(name) == false">',
- '<p>Boy: {name} - {age}</p>',
- '</tpl>',
- '<tpl if="this.isBaby(age)">',
- '<p>{name} is a baby!</p>',
- '</tpl>',
- '</tpl></p>',
- {
- // XTemplate configuration:
- compiled: true,
- // member functions:
- isGirl: function(name){
- return name == 'Sara Grace';
- },
- isBaby: function(age){
- return age < 1;
- }
- }
-);
-tpl.overwrite(panel.body, data);
-
- * Name: {name}
', + * 'Kids: ',
+ * ' {#}: {name} In 5 Years: {age+5} Dad: {parent.name}
Name: {name}
', + * 'Company: {[values.company.toUpperCase() + ", " + values.title]}
', + * 'Kids: ',
+ * '
Name: {name}
', + * 'Kids: ',
+ * ' Girl: {name} - {age} Boy: {name} - {age} {name} is a baby!