For up to date documentation and features, visit http://docs.sencha.com/ext-js/4-0

## Sencha Documentation

# Ext.core.DomHelper

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.

DomHelper element specification object

A specification object is used when creating elements. Attributes of this object are assumed to be element attributes, except for 4 special attributes:

- `tag` :
  The tag name of the element
- `children` : or `cn`
  An array of the same kind of element definition objects to be created and appended. These can be nested as deep as you want.
- `cls` :
  The class attribute of the element. This will end up being either the "class" attribute on a HTML fragment or className for a DOM node, depending on whether DomHelper is using fragments or DOM.
- `html` :
  The innerHTML for the element

Insertion methods

Commonly used insertion methods:

- `append` :
- `insertBefore` :
- `insertAfter` :
- `overwrite` :
- `createTemplate` :
- `insertHtml` :

Example

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.core.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'}
    ]);

Templating

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 = '{2}';

    var tpl = new Ext.core.DomHelper.createTemplate(html);
    tpl.append('blog-roll', ['link1', 'http://www.edspencer.net/', "Ed's Site"]);
    tpl.append('blog-roll', ['link2', 'http://www.dustindiaz.com/', "Dustin's Site"]);

The same example using named parameters:

    var html = '{text}';

    var tpl = new Ext.core.DomHelper.createTemplate(html);
    tpl.append('blog-roll', {
        id: 'link1',
        url: 'http://www.edspencer.net/',
        text: "Ed's Site"
    });
    tpl.append('blog-roll', {
        id: 'link2',
        url: 'http://www.dustindiaz.com/',
        text: "Dustin's Site"
    });

Compiling Templates

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 = '{text}';

    var tpl = new Ext.core.DomHelper.createTemplate(html);
    tpl.compile();

    //... use template like normal

Performance Boost

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.core.DomHelper.useDom = true; // force it to use DOM; reduces performance

Defined By

### Properties

Ext.core.DomHelper
view source
createDom : Object

Creates new DOM element(s) without inserting them to the document.

Creates new DOM element(s) without inserting them to the document.

Ext.core.DomHelper
view source
useDom : Boolean

True to force the use of DOM instead of html fragments

True to force the use of DOM instead of html fragments

Defined By

### Methods

Ext.core.DomHelper
view source
append( Mixed el, Object/String o, [Boolean returnElement]) : HTMLElement/Ext.core.Element

Creates new DOM element(s) and appends them to el.

Creates new DOM element(s) and appends them to el.

### Parameters

- el : Mixed

  The context element

- o : Object/String

  The DOM object spec (and children) or raw HTML blob

- returnElement : Boolean

  (optional) true to return a Ext.core.Element

### Returns

- HTMLElement/Ext.core.Element

  The new node

Ext.core.DomHelper
view source
applyStyles( String/HTMLElement el, String/Object/Function styles) : void

Applies a style specification to an element.

Applies a style specification to an element.

### Parameters

- el : String/HTMLElement

  The element to apply styles to

- styles : String/Object/Function

  A style specification string e.g. 'width:100px', or object in the form {width:'100px'}, or a function which returns such a specification.

### Returns

- void

Ext.core.DomHelper
view source
createTemplate( Object o) : Ext.Template

Creates a new Ext.Template from the DOM object spec.

Creates a new Ext.Template from the DOM object spec.

### Parameters

- o : Object

  The DOM object spec (and children)

### Returns

- Ext.Template

  The new template

Ext.core.DomHelper
view source
insertAfter( Mixed el, Object o, [Boolean returnElement]) : HTMLElement/Ext.core.Element

Creates new DOM element(s) and inserts them after el.

Creates new DOM element(s) and inserts them after el.

### Parameters

- el : Mixed

  The context element

- o : Object

  The DOM object spec (and children)

- returnElement : Boolean

  (optional) true to return a Ext.core.Element

### Returns

- HTMLElement/Ext.core.Element

  The new node

Ext.core.DomHelper
view source
insertBefore( Mixed el, Object/String o, [Boolean returnElement]) : HTMLElement/Ext.core.Element

Creates new DOM element(s) and inserts them before el.

Creates new DOM element(s) and inserts them before el.

### Parameters

- el : Mixed

  The context element

- o : Object/String

  The DOM object spec (and children) or raw HTML blob

- returnElement : Boolean

  (optional) true to return a Ext.core.Element

### Returns

- HTMLElement/Ext.core.Element

  The new node

Ext.core.DomHelper
view source
insertFirst( Mixed el, Object/String o, [Boolean returnElement]) : HTMLElement/Ext.core.Element

Creates new DOM element(s) and inserts them as the first child of el.

Creates new DOM element(s) and inserts them as the first child of el.

### Parameters

- el : Mixed

  The context element

- o : Object/String

  The DOM object spec (and children) or raw HTML blob

- returnElement : Boolean

  (optional) true to return a Ext.core.Element

### Returns

- HTMLElement/Ext.core.Element

  The new node

Ext.core.DomHelper
view source
insertHtml( String where, HTMLElement/TextNode el, String html) : HTMLElement

Inserts an HTML fragment into the DOM.

Inserts an HTML fragment into the DOM.

### Parameters

- where : String

  Where to insert the html in relation to el - beforeBegin, afterBegin, beforeEnd, afterEnd.

- el : HTMLElement/TextNode

  The context element

- html : String

  The HTML fragment

### Returns

- HTMLElement

  The new node

Ext.core.DomHelper
view source
markup( Object o) : String

Returns the markup for the passed Element(s) config.

Returns the markup for the passed Element(s) config.

### Parameters

- o : Object

  The DOM object spec (and children)

### Returns

- String

Ext.core.DomHelper
view source
overwrite( Mixed el, Object/String o, [Boolean returnElement]) : HTMLElement/Ext.core.Element

Creates new DOM element(s) and overwrites the contents of el with them.

Creates new DOM element(s) and overwrites the contents of el with them.

### Parameters

- el : Mixed

  The context element

- o : Object/String

  The DOM object spec (and children) or raw HTML blob

- returnElement : Boolean

  (optional) true to return a Ext.core.Element

### Returns

- HTMLElement/Ext.core.Element

  The new node