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