/**
+ * @class Ext.DomHelper
+ * @alternateClassName Ext.core.DomHelper
+ *
* <p>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.</p>
@@ -17,23 +36,28 @@
* for a DOM node, depending on whether DomHelper is using fragments or DOM.</div></li>
* <li><b><tt>html</tt></b> : <div class="sub-desc">The innerHTML for the element</div></li>
* </ul></div></p>
+ * <p><b>NOTE:</b> For other arbitrary attributes, the value will currently <b>not</b> be automatically
+ * HTML-escaped prior to building the element's HTML string. This means that if your attribute value
+ * contains special characters that would not normally be allowed in a double-quoted attribute value,
+ * you <b>must</b> manually HTML-encode it beforehand (see {@link Ext.String#htmlEncode}) or risk
+ * malformed HTML being created. This behavior may change in a future release.</p>
*
* <p><b><u>Insertion methods</u></b></p>
* <p>Commonly used insertion methods:
* <div class="mdetail-params"><ul>
- * <li><b><tt>{@link #append}</tt></b> : <div class="sub-desc"></div></li>
- * <li><b><tt>{@link #insertBefore}</tt></b> : <div class="sub-desc"></div></li>
- * <li><b><tt>{@link #insertAfter}</tt></b> : <div class="sub-desc"></div></li>
- * <li><b><tt>{@link #overwrite}</tt></b> : <div class="sub-desc"></div></li>
- * <li><b><tt>{@link #createTemplate}</tt></b> : <div class="sub-desc"></div></li>
- * <li><b><tt>{@link #insertHtml}</tt></b> : <div class="sub-desc"></div></li>
+ * <li><tt>{@link #append}</tt> : <div class="sub-desc"></div></li>
+ * <li><tt>{@link #insertBefore}</tt> : <div class="sub-desc"></div></li>
+ * <li><tt>{@link #insertAfter}</tt> : <div class="sub-desc"></div></li>
+ * <li><tt>{@link #overwrite}</tt> : <div class="sub-desc"></div></li>
+ * <li><tt>{@link #createTemplate}</tt> : <div class="sub-desc"></div></li>
+ * <li><tt>{@link #insertHtml}</tt> : <div class="sub-desc"></div></li>
* </ul></div></p>
*
* <p><b><u>Example</u></b></p>
* <p>This is an example, where an unordered list with 3 children items is appended to an existing
* element with id <tt>'my-div'</tt>:<br>
<pre><code>
-var dh = Ext.core.DomHelper; // create shorthand alias
+var dh = Ext.DomHelper; // create shorthand alias
// specification object
var spec = {
id: 'my-ul',
@@ -77,7 +101,7 @@ for(var i = 0; i < 5, i++){
* <p>An example using a template:<pre><code>
var html = '<a id="{0}" href="{1}" class="nav">{2}</a>';
-var tpl = new Ext.core.DomHelper.createTemplate(html);
+var tpl = new Ext.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"]);
* </code></pre></p>
@@ -85,7 +109,7 @@ tpl.append('blog-roll', ['link2', 'http://www.dustindiaz.com/', "Dustin&
* <p>The same example using named parameters:<pre><code>
var html = '<a id="{id}" href="{url}" class="nav">{text}</a>';
-var tpl = new Ext.core.DomHelper.createTemplate(html);
+var tpl = new Ext.DomHelper.createTemplate(html);
tpl.append('blog-roll', {
id: 'link1',
url: 'http://www.edspencer.net/',
@@ -109,7 +133,7 @@ tpl.append('blog-roll', {
* <pre><code>
var html = '<a id="{id}" href="{url}" class="nav">{text}</a>';
-var tpl = new Ext.core.DomHelper.createTemplate(html);
+var tpl = new Ext.DomHelper.createTemplate(html);
tpl.compile();
//... use template like normal
@@ -122,12 +146,12 @@ tpl.compile();
* then the string is used as innerHTML. If {@link #useDom} is <tt>true</tt>, a string specification
* results in the creation of a text node. Usage:</p>
* <pre><code>
-Ext.core.DomHelper.useDom = true; // force it to use DOM; reduces performance
+Ext.DomHelper.useDom = true; // force it to use DOM; reduces performance
* </code></pre>
* @singleton
*/
Ext.ns('Ext.core');
-Ext.core.DomHelper = function(){
+Ext.core.DomHelper = Ext.DomHelper = function(){
var tempTableEl = null,
emptyTags = /^(?:br|frame|hr|img|input|link|meta|range|spacer|wbr|area|param|col)$/i,
tableRe = /^table|tbody|tr|td$/i,
@@ -159,11 +183,11 @@ Ext.core.DomHelper = function(){
(sibling == 'firstChild' ? el : el.parentNode).insertBefore(newNode, el[sibling] || el);
}
} else {
- newNode = Ext.core.DomHelper.insertHtml(pos, el, Ext.core.DomHelper.createHtml(o));
+ newNode = Ext.DomHelper.insertHtml(pos, el, Ext.DomHelper.createHtml(o));
}
return returnElement ? Ext.get(newNode, true) : newNode;
}
-
+
function createDom(o, parentNode){
var el,
doc = document,
@@ -196,7 +220,7 @@ Ext.core.DomHelper = function(){
}
}
}
- Ext.core.DomHelper.applyStyles(el, o.style);
+ Ext.DomHelper.applyStyles(el, o.style);
if ((cn = o.children || o.cn)) {
createDom(cn, el);
@@ -281,7 +305,7 @@ Ext.core.DomHelper = function(){
return el;
}
- /**
+ /**
* @ignore
* Nasty code for IE's broken table implementation
*/
@@ -314,17 +338,17 @@ Ext.core.DomHelper = function(){
el.insertBefore(node, before);
return node;
}
-
- /**
+
+ /**
* @ignore
* Fix for IE9 createContextualFragment missing method
- */
+ */
function createContextualFragment(html){
var div = document.createElement("div"),
fragment = document.createDocumentFragment(),
i = 0,
length, childNodes;
-
+
div.innerHTML = html;
childNodes = div.childNodes;
length = childNodes.length;
@@ -335,9 +359,9 @@ Ext.core.DomHelper = function(){
return fragment;
}
-
+
pub = {
- /**
+ /**
* Returns the markup for the passed Element(s) config.
* @param {Object} o The DOM object spec (and children)
* @return {String}
@@ -346,7 +370,7 @@ Ext.core.DomHelper = function(){
return createHtml(o);
},
- /**
+ /**
* Applies a style specification to an element.
* @param {String/HTMLElement} el The element to apply styles to
* @param {String/Object/Function} styles A style specification string e.g. 'width:100px', or object in the form {width:'100px'}, or
@@ -359,7 +383,7 @@ Ext.core.DomHelper = function(){
styles = styles.call();
}
if (typeof styles == "string") {
- styles = Ext.core.Element.parseStyles(styles);
+ styles = Ext.Element.parseStyles(styles);
}
if (typeof styles == "object") {
el.setStyle(styles);
@@ -367,9 +391,19 @@ Ext.core.DomHelper = function(){
}
},
- /**
+ /**
* Inserts an HTML fragment into the DOM.
* @param {String} where 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:
+ *
+ * - beforeBegin: `<HERE><div>Contents</div>`
+ * - afterBegin: `<div><HERE>Contents</div>`
+ * - beforeEnd: `<div>Contents<HERE></div>`
+ * - afterEnd: `<div>Contents</div><HERE>`
+ *
* @param {HTMLElement/TextNode} el The context element
* @param {String} html The HTML fragment
* @return {HTMLElement} The new node
@@ -387,13 +421,13 @@ Ext.core.DomHelper = function(){
// add these here because they are used in both branches of the condition.
hash[beforebegin] = ['BeforeBegin', 'previousSibling'];
hash[afterend] = ['AfterEnd', 'nextSibling'];
-
+
// if IE and context element is an HTMLElement
if (el.insertAdjacentHTML) {
if(tableRe.test(el.tagName) && (rs = insertIntoTable(el.tagName.toLowerCase(), where, el, html))){
return rs;
}
-
+
// add these two to the hash.
hash[afterbegin] = ['AfterBegin', 'firstChild'];
hash[beforeend] = ['BeforeEnd', 'lastChild'];
@@ -405,7 +439,7 @@ Ext.core.DomHelper = function(){
} else {
// we cannot insert anything inside a textnode so...
if (Ext.isTextNode(el)) {
- where = where === 'afterbegin' ? 'beforebegin' : where;
+ where = where === 'afterbegin' ? 'beforebegin' : where;
where = where === 'beforeend' ? 'afterend' : where;
}
range = Ext.supports.CreateContextualFragment ? el.ownerDocument.createRange() : undefined;
@@ -428,7 +462,7 @@ Ext.core.DomHelper = function(){
} else {
frag = createContextualFragment(html);
}
-
+
if(where == afterbegin){
el.insertBefore(frag, el.firstChild);
}else{
@@ -442,7 +476,7 @@ Ext.core.DomHelper = function(){
}
//<debug>
Ext.Error.raise({
- sourceClass: 'Ext.core.DomHelper',
+ sourceClass: 'Ext.DomHelper',
sourceMethod: 'insertHtml',
htmlToInsert: html,
targetElement: el,
@@ -451,56 +485,56 @@ Ext.core.DomHelper = function(){
//</debug>
},
- /**
+ /**
* Creates new DOM element(s) and inserts them before el.
- * @param {Mixed} el The context element
+ * @param {String/HTMLElement/Ext.Element} el The context element
* @param {Object/String} o The DOM object spec (and children) or raw HTML blob
- * @param {Boolean} returnElement (optional) true to return a Ext.core.Element
- * @return {HTMLElement/Ext.core.Element} The new node
+ * @param {Boolean} returnElement (optional) true to return a Ext.Element
+ * @return {HTMLElement/Ext.Element} The new node
*/
insertBefore : function(el, o, returnElement){
return doInsert(el, o, returnElement, beforebegin);
},
- /**
+ /**
* Creates new DOM element(s) and inserts them after el.
- * @param {Mixed} el The context element
+ * @param {String/HTMLElement/Ext.Element} el The context element
* @param {Object} o The DOM object spec (and children)
- * @param {Boolean} returnElement (optional) true to return a Ext.core.Element
- * @return {HTMLElement/Ext.core.Element} The new node
+ * @param {Boolean} returnElement (optional) true to return a Ext.Element
+ * @return {HTMLElement/Ext.Element} The new node
*/
insertAfter : function(el, o, returnElement){
return doInsert(el, o, returnElement, afterend, 'nextSibling');
},
- /**
+ /**
* Creates new DOM element(s) and inserts them as the first child of el.
- * @param {Mixed} el The context element
+ * @param {String/HTMLElement/Ext.Element} el The context element
* @param {Object/String} o The DOM object spec (and children) or raw HTML blob
- * @param {Boolean} returnElement (optional) true to return a Ext.core.Element
- * @return {HTMLElement/Ext.core.Element} The new node
+ * @param {Boolean} returnElement (optional) true to return a Ext.Element
+ * @return {HTMLElement/Ext.Element} The new node
*/
insertFirst : function(el, o, returnElement){
return doInsert(el, o, returnElement, afterbegin, 'firstChild');
},
- /**
+ /**
* Creates new DOM element(s) and appends them to el.
- * @param {Mixed} el The context element
+ * @param {String/HTMLElement/Ext.Element} el The context element
* @param {Object/String} o The DOM object spec (and children) or raw HTML blob
- * @param {Boolean} returnElement (optional) true to return a Ext.core.Element
- * @return {HTMLElement/Ext.core.Element} The new node
+ * @param {Boolean} returnElement (optional) true to return a Ext.Element
+ * @return {HTMLElement/Ext.Element} The new node
*/
append : function(el, o, returnElement){
return doInsert(el, o, returnElement, beforeend, '', true);
},
- /**
+ /**
* Creates new DOM element(s) and overwrites the contents of el with them.
- * @param {Mixed} el The context element
+ * @param {String/HTMLElement/Ext.Element} el The context element
* @param {Object/String} o The DOM object spec (and children) or raw HTML blob
- * @param {Boolean} returnElement (optional) true to return a Ext.core.Element
- * @return {HTMLElement/Ext.core.Element} The new node
+ * @param {Boolean} returnElement (optional) true to return a Ext.Element
+ * @return {HTMLElement/Ext.Element} The new node
*/
overwrite : function(el, o, returnElement){
el = Ext.getDom(el);
@@ -509,27 +543,30 @@ Ext.core.DomHelper = function(){
},
createHtml : createHtml,
-
- /**
+
+ /**
* Creates new DOM element(s) without inserting them to the document.
* @param {Object/String} o The DOM object spec (and children) or raw HTML blob
* @return {HTMLElement} The new uninserted node
+ * @method
*/
createDom: createDom,
-
- /** True to force the use of DOM instead of html fragments @type Boolean */
+
+ /** True to force the use of DOM instead of html fragments @type Boolean */
useDom : false,
-
- /**
+
+ /**
* Creates a new Ext.Template from the DOM object spec.
* @param {Object} o The DOM object spec (and children)
* @return {Ext.Template} The new template
*/
createTemplate : function(o){
- var html = Ext.core.DomHelper.createHtml(o);
+ var html = Ext.DomHelper.createHtml(o);
return Ext.create('Ext.Template', html);
}
};
return pub;
}();
-