X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/530ef4b6c5b943cfa68b779d11cf7de29aa878bf..7a654f8d43fdb43d78b63d90528bed6e86b608cc:/docs/api/Ext.core.DomHelper.html diff --git a/docs/api/Ext.core.DomHelper.html b/docs/api/Ext.core.DomHelper.html new file mode 100644 index 00000000..cff1ba40 --- /dev/null +++ b/docs/api/Ext.core.DomHelper.html @@ -0,0 +1,253 @@ +Ext.core.DomHelper | Ext JS 4.0 Documentation +
For up to date documentation and features, visit +http://docs.sencha.com/ext-js/4-0

Sencha Documentation

+ + + + + +

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: +

+ + + + +

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

 

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

+

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

+
 

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

 
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

    +
 
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    +
 
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

    +
 
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

    +
 
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

    +
 
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

    +
 
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

    +
 

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    +
 
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

    +
\ No newline at end of file