Alternate names
Ext.dom.HelperFiles
The DomHelper class provides a layer of abstraction from DOM and transparently supports creating elements via DOM or using HTML fragments. It also has the ability to create HTML fragment templates from your DOM building code.
A specification object is used when creating elements. Attributes of this object are assumed to be element attributes, except for 4 special attributes:
Commonly used insertion methods:
This is an example, where an unordered list with 3 children items is appended to an existing element with id 'my-div':
var dh = Ext.DomHelper; // create shorthand alias
// specification object
var spec = {
id: 'my-ul',
tag: 'ul',
cls: 'my-list',
// append children after creating
children: [ // may also specify 'cn' instead of 'children'
{tag: 'li', id: 'item0', html: 'List Item 0'},
{tag: 'li', id: 'item1', html: 'List Item 1'},
{tag: 'li', id: 'item2', html: 'List Item 2'}
]
};
var list = dh.append(
'my-div', // the context element 'my-div' can either be the id or the actual node
spec // the specification object
);
Element creation specification parameters in this class may also be passed as an Array of specification objects. This can be used to insert multiple sibling nodes into an existing container very efficiently. For example, to add more list items to the example above:
dh.append('my-ul', [
{tag: 'li', id: 'item3', html: 'List Item 3'},
{tag: 'li', id: 'item4', html: 'List Item 4'}
]);
The real power is in the built-in templating. Instead of creating or appending any elements, createTemplate returns a Template object which can be used over and over to insert new elements. Revisiting the example above, we could utilize templating this time:
// create the node
var list = dh.append('my-div', {tag: 'ul', cls: 'my-list'});
// get template
var tpl = dh.createTemplate({tag: 'li', id: 'item{0}', html: 'List Item {0}'});
for(var i = 0; i < 5; i++){
tpl.append(list, i); // use template to append to the actual node
}
An example using a template:
var html = '"{0}" href="{1}" class="nav">{2}';
var tpl = new Ext.DomHelper.createTemplate(html);
tpl.append('blog-roll', ['link1', 'http://www.tommymaintz.com/', "Tommy's Site"]);
tpl.append('blog-roll', ['link2', 'http://www.avins.org/', "Jamie's Site"]);
The same example using named parameters:
var html = '"{id}" href="{url}" class="nav">{text}';
var tpl = new Ext.DomHelper.createTemplate(html);
tpl.append('blog-roll', {
id: 'link1',
url: 'http://www.tommymaintz.com/',
text: "Tommy's Site"
});
tpl.append('blog-roll', {
id: 'link2',
url: 'http://www.avins.org/',
text: "Jamie's Site"
});
Templates are applied using regular expressions. The performance is great, but if you are adding a bunch of DOM elements using the same template, you can increase performance even further by "compiling" the template. The way "compile()" works is the template is parsed and broken up at the different variable points and a dynamic function is created and eval'ed. The generated function performs string concatenation of these parts and the passed variables instead of using regular expressions.
var html = '"{id}" href="{url}" class="nav">{text}';
var tpl = new Ext.DomHelper.createTemplate(html);
tpl.compile();
// ... use template like normal
DomHelper will transparently create HTML fragments when it can. Using HTML fragments instead of DOM can significantly boost performance.
Element creation specification parameters may also be strings. If useDom is false, then the string is used as innerHTML. If useDom is true, a string specification results in the creation of a text node. Usage:
Ext.DomHelper.useDom = true; // force it to use DOM; reduces performance
Creates new DOM element(s) and appends them to el.
The context element
The DOM object spec (and children) or raw HTML blob
true to return a Ext.Element
The new node
Creates a new Ext.Template from the DOM object spec.
The DOM object spec (and children)
The new template
Converts the styles from the given object to text. The styles are CSS style names with their associated value.
The basic form of this method returns a string:
var s = Ext.DomHelper.generateStyles({
backgroundColor: 'red'
});
// s = 'background-color:red;'
Alternatively, this method can append to an output array.
var buf = [];
// ...
Ext.DomHelper.generateStyles({
backgroundColor: 'red'
}, buf);
In this case, the style text is pushed on to the array and the array is returned.
Creates new DOM element(s) and inserts them after el.
The context element
The DOM object spec (and children)
true to return a Ext.Element
The new node
Creates new DOM element(s) and inserts them before el.
The context element
The DOM object spec (and children) or raw HTML blob
true to return a Ext.Element
The new node
Creates new DOM element(s) and inserts them as the first child of el.
The context element
The DOM object spec (and children) or raw HTML blob
true to return a Ext.Element
The new node
Inserts an HTML fragment into the DOM.
Where to insert the html in relation to el - beforeBegin, afterBegin, beforeEnd, afterEnd.
For example take the following HTML: <div>Contents</div>
Using different where
values inserts element to the following places:
<HERE><div>Contents</div>
<div><HERE>Contents</div>
<div>Contents<HERE></div>
<div>Contents</div><HERE>
The context element
The HTML fragment
The new node
Creates new DOM element(s) and overwrites the contents of el with them.
The context element
The DOM object spec (and children) or raw HTML blob
true to return a Ext.Element
The new node