1 /* 2 * CKEditor - The text editor for Internet - http://ckeditor.com 3 * Copyright (C) 2003-2008 Frederico Caldeira Knabben 4 * 5 * == BEGIN LICENSE == 6 * 7 * Licensed under the terms of any of the following licenses at your 8 * choice: 9 * 10 * - GNU General Public License Version 2 or later (the "GPL") 11 * http://www.gnu.org/licenses/gpl.html 12 * 13 * - GNU Lesser General Public License Version 2.1 or later (the "LGPL") 14 * http://www.gnu.org/licenses/lgpl.html 15 * 16 * - Mozilla Public License Version 1.1 or later (the "MPL") 17 * http://www.mozilla.org/MPL/MPL-1.1.html 18 * 19 * == END LICENSE == 20 */ 21 22 /** 23 * @fileOverview Defines the {@link CKEDITOR.dom.element} class, which 24 * represents a DOM element. 25 */ 26 27 /** 28 * Represents a DOM element. 29 * @constructor 30 * @augments CKEDITOR.dom.node 31 * @param {Object|String} element A native DOM element or the element name for 32 * new elements. 33 * @example 34 * // Create a new <span> element. 35 * var element = new CKEDITOR.dom.element( 'span' ); 36 * @example 37 * // Create an element based on a native DOM element. 38 * var element = new CKEDITOR.dom.element( document.getElementById( 'myId' ) ); 39 */ 40 CKEDITOR.dom.element = function( element ) 41 { 42 if ( typeof element == 'string' ) 43 element = document.createElement( element ); 44 45 /** 46 * The native DOM element represented by this class instance. 47 * @type Object 48 * @example 49 * var element = new CKEDITOR.dom.element( 'span' ); 50 * alert( element.$.nodeType ); // "1" 51 */ 52 this.$ = element; 53 }; 54 55 CKEDITOR.dom.element.prototype = new CKEDITOR.dom.node(); 56 57 /** 58 * Creates an instance of the {@link CKEDITOR.dom.element} class representing an 59 * element with the specific id. 60 * @param {String} id The element id. 61 * @returns {CKEDITOR.dom.element} The element instance, or null if not found. 62 * @example 63 * var element = <b>CKEDITOR.dom.element.getById( 'myElement' )</b>; 64 * alert( element.getId() ); // "myElement" 65 */ 66 CKEDITOR.dom.element.getById = function( id ) 67 { 68 var $ = document.getElementById( id ); 69 return $ ? new CKEDITOR.dom.element( $ ) : null; 70 }; 71 72 /** 73 * Creates an instance of the {@link CKEDITOR.dom.element} class representing the 74 * <head> element. 75 * @returns {CKEDITOR.dom.element} The element instance. 76 * @example 77 * var element = <b>CKEDITOR.dom.element.getHead()</b>; 78 * alert( element.getName() ); // "head" 79 */ 80 CKEDITOR.dom.element.getHead = function() 81 { 82 var head = document.getElementsByTagName( 'head' )[0]; 83 return new CKEDITOR.dom.element( head ); 84 }; 85 86 /** 87 * Creates an instance of the {@link CKEDITOR.dom.element} class based on the 88 * HTML representation of an element. 89 * @param {String} html The element HTML. It should define only one element in 90 * the "root" level. The "root" element can have child nodes, but not 91 * siblings. 92 * @returns {CKEDITOR.dom.element} The element instance. 93 * @example 94 * var element = <b>CKEDITOR.dom.element.createFromHtml( '<strong class="anyclass">My element</strong>' )</b>; 95 * alert( element.getName() ); // "strong" 96 */ 97 CKEDITOR.dom.element.createFromHtml = function( html ) 98 { 99 var temp = document.createElement( 'div' ); 100 temp.innerHTML = html; 101 return new CKEDITOR.dom.element( temp.firstChild ); 102 }; 103 104 CKEDITOR.tools.extend( CKEDITOR.dom.element.prototype, 105 /** @lends CKEDITOR.dom.element.prototype */ 106 { 107 /** 108 * Append a node as a child of this element. 109 * @param {CKEDITOR.dom.node|String} node The node or element name to be 110 * appended. 111 * @returns {CKEDITOR.dom.node} The appended node. 112 * @example 113 * var p = new CKEDITOR.dom.element( 'p' ); 114 * 115 * var strong = new CKEDITOR.dom.element( 'strong' ); 116 * <b>p.append( strong );</b> 117 * 118 * var em = <b>p.append( 'em' );</b> 119 * 120 * // result: "<p><strong></strong><em></em></p>" 121 */ 122 append : function( node ) 123 { 124 if ( typeof node == 'string' ) 125 node = new CKEDITOR.dom.element( node ); 126 127 this.$.appendChild( node.$ ); 128 return node; 129 }, 130 131 /** 132 * Append text to this element. 133 * @param {String} text The text to be appended. 134 * @returns {CKEDITOR.dom.node} The appended node. 135 * @example 136 * var p = new CKEDITOR.dom.element( 'p' ); 137 * p.appendText( 'This is' ); 138 * p.appendText( ' some text' ); 139 * 140 * // result: "<p>This is some text</p>" 141 */ 142 appendText : function( text ) 143 { 144 if ( this.$.text != undefined ) 145 this.$.text += text; 146 else 147 this.$.appendChild( document.createTextNode( text ) ); 148 }, 149 150 /** 151 * Sets the inner HTML of this element. 152 * @param {String} html The HTML to be set for this element. 153 * @returns {String} The inserted HTML. 154 * @example 155 * var p = new CKEDITOR.dom.element( 'p' ); 156 * <b>p.setHtml( '<b>Inner</b> HTML' );</b> 157 * 158 * // result: "<p><b>Inner</b> HTML</p>" 159 */ 160 setHtml : function( html ) 161 { 162 return ( this.$.innerHTML = html ); 163 }, 164 165 /** 166 * Gets the value of the "id" attribute of this element. 167 * @returns {String} The element id, or null if not available. 168 * @example 169 * var element = CKEDITOR.dom.element.createFromHtml( '<p id="myId"></p>' ); 170 * alert( <b>element.getId()</b> ); // "myId" 171 */ 172 getId : function() 173 { 174 return this.$.id || null; 175 }, 176 177 /** 178 * Gets the value of the "name" attribute of this element. 179 * @returns {String} The element name, or null if not available. 180 * @example 181 * var element = CKEDITOR.dom.element.createFromHtml( '<input name="myName"></input>' ); 182 * alert( <b>element.getNameAtt()</b> ); // "myName" 183 */ 184 getNameAtt : function() 185 { 186 return this.$.name || null; 187 }, 188 189 /** 190 * Gets the element name (tag name). The returned name is guaranteed to 191 * be always full lowercased. 192 * @returns {String} The element name. 193 * @example 194 * var element = new CKEDITOR.dom.element( 'span' ); 195 * alert( <b>element.getName()</b> ); // "span" 196 */ 197 getName : function() 198 { 199 // Cache the lowercased name inside a closure. 200 var nodeName = this.$.nodeName.toLowerCase(); 201 202 return ( 203 /** @ignore */ 204 this.getName = function() 205 { 206 return nodeName; 207 })(); 208 }, 209 210 /** 211 * Hides this element (display:none). 212 * @type {undefined} 213 * @example 214 * var element = CKEDITOR.dom.element.getById( 'myElement' ); 215 * <b>element.hide()</b>; 216 */ 217 hide : function() 218 { 219 this.setStyle( 'display', 'none' ); 220 }, 221 222 /** 223 * Shows this element (display it). 224 * @type {undefined} 225 * @example 226 * var element = CKEDITOR.dom.element.getById( 'myElement' ); 227 * <b>element.show()</b>; 228 */ 229 show : function() 230 { 231 this.setStyle( 'display', '' ); 232 }, 233 234 /** 235 * Sets the value of an element attribute. 236 * @param {String} name The name of the attribute. 237 * @param {String} value The value to be set to the attribute. 238 * @type {undefined} 239 * @example 240 * var element = CKEDITOR.dom.element.getById( 'myElement' ); 241 * <b>element.setAttribute( 'class', 'myClass' )</b>; 242 * <b>element.setAttribute( 'title', 'This is an example' )</b>; 243 */ 244 setAttribute : function( name, value ) 245 { 246 this.$.setAttribute( name, value ); 247 }, 248 249 /** 250 * Sets the value of several element attributes. 251 * @param {Object} attributesPairs An object containing the names and 252 * values of the attributes. 253 * @type {undefined} 254 * @example 255 * var element = CKEDITOR.dom.element.getById( 'myElement' ); 256 * <b>element.setAttributes({ 257 * 'class' : 'myClass', 258 * 'title' : 'This is an example' })</b>; 259 */ 260 setAttributes : function( attributesPairs ) 261 { 262 for ( var name in attributesPairs ) 263 this.setAttribute( name, attributesPairs[ name ] ); 264 }, 265 266 /** 267 * Sets the value of an element style. 268 * @param {String} name The name of the style. The the object DOM 269 * naming notation must be used. 270 * @param {String} value The value to be set to the style. 271 * @type {undefined} 272 * @example 273 * var element = CKEDITOR.dom.element.getById( 'myElement' ); 274 * <b>element.setStyle( 'backgroundColor', '#ff0000' )</b>; 275 * <b>element.setStyle( 'marginTop', '10px' )</b>; 276 */ 277 setStyle : function( name, value ) 278 { 279 this.$.style[ name ] = value; 280 } 281 }); 282