2 Copyright (c) 2003-2012, CKSource - Frederico Knabben. All rights reserved.
\r
3 For licensing, see LICENSE.html or http://ckeditor.com/license
\r
7 * @fileOverview Defines the {@link CKEDITOR.dom.node} class which is the base
\r
8 * class for classes that represent DOM nodes.
\r
12 * Base class for classes representing DOM nodes. This constructor may return
\r
13 * an instance of a class that inherits from this class, like
\r
14 * {@link CKEDITOR.dom.element} or {@link CKEDITOR.dom.text}.
\r
15 * @augments CKEDITOR.dom.domObject
\r
16 * @param {Object} domNode A native DOM node.
\r
18 * @see CKEDITOR.dom.element
\r
19 * @see CKEDITOR.dom.text
\r
22 CKEDITOR.dom.node = function( domNode )
\r
26 var type = domNode.nodeType == CKEDITOR.NODE_DOCUMENT ? 'document'
\r
27 : domNode.nodeType == CKEDITOR.NODE_ELEMENT ? 'element'
\r
28 : domNode.nodeType == CKEDITOR.NODE_TEXT ? 'text'
\r
29 : domNode.nodeType == CKEDITOR.NODE_COMMENT ? 'comment'
\r
30 : 'domObject'; // Call the base constructor otherwise.
\r
32 return new CKEDITOR.dom[ type ]( domNode );
\r
38 CKEDITOR.dom.node.prototype = new CKEDITOR.dom.domObject();
\r
41 * Element node type.
\r
45 CKEDITOR.NODE_ELEMENT = 1;
\r
48 * Document node type.
\r
52 CKEDITOR.NODE_DOCUMENT = 9;
\r
59 CKEDITOR.NODE_TEXT = 3;
\r
62 * Comment node type.
\r
66 CKEDITOR.NODE_COMMENT = 8;
\r
68 CKEDITOR.NODE_DOCUMENT_FRAGMENT = 11;
\r
70 CKEDITOR.POSITION_IDENTICAL = 0;
\r
71 CKEDITOR.POSITION_DISCONNECTED = 1;
\r
72 CKEDITOR.POSITION_FOLLOWING = 2;
\r
73 CKEDITOR.POSITION_PRECEDING = 4;
\r
74 CKEDITOR.POSITION_IS_CONTAINED = 8;
\r
75 CKEDITOR.POSITION_CONTAINS = 16;
\r
77 CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype,
\r
78 /** @lends CKEDITOR.dom.node.prototype */
\r
81 * Makes this node a child of another element.
\r
82 * @param {CKEDITOR.dom.element} element The target element to which
\r
83 * this node will be appended.
\r
84 * @returns {CKEDITOR.dom.element} The target element.
\r
86 * var p = new CKEDITOR.dom.element( 'p' );
\r
87 * var strong = new CKEDITOR.dom.element( 'strong' );
\r
88 * strong.appendTo( p );
\r
90 * // result: "<p><strong></strong></p>"
\r
92 appendTo : function( element, toStart )
\r
94 element.append( this, toStart );
\r
98 clone : function( includeChildren, cloneId )
\r
100 var $clone = this.$.cloneNode( includeChildren );
\r
102 var removeIds = function( node )
\r
104 if ( node.nodeType != CKEDITOR.NODE_ELEMENT )
\r
108 node.removeAttribute( 'id', false );
\r
109 node.removeAttribute( 'data-cke-expando', false );
\r
111 if ( includeChildren )
\r
113 var childs = node.childNodes;
\r
114 for ( var i=0; i < childs.length; i++ )
\r
115 removeIds( childs[ i ] );
\r
119 // The "id" attribute should never be cloned to avoid duplication.
\r
120 removeIds( $clone );
\r
122 return new CKEDITOR.dom.node( $clone );
\r
125 hasPrevious : function()
\r
127 return !!this.$.previousSibling;
\r
130 hasNext : function()
\r
132 return !!this.$.nextSibling;
\r
136 * Inserts this element after a node.
\r
137 * @param {CKEDITOR.dom.node} node The node that will precede this element.
\r
138 * @returns {CKEDITOR.dom.node} The node preceding this one after
\r
141 * var em = new CKEDITOR.dom.element( 'em' );
\r
142 * var strong = new CKEDITOR.dom.element( 'strong' );
\r
143 * strong.insertAfter( em );
\r
145 * // result: "<em></em><strong></strong>"
\r
147 insertAfter : function( node )
\r
149 node.$.parentNode.insertBefore( this.$, node.$.nextSibling );
\r
154 * Inserts this element before a node.
\r
155 * @param {CKEDITOR.dom.node} node The node that will succeed this element.
\r
156 * @returns {CKEDITOR.dom.node} The node being inserted.
\r
158 * var em = new CKEDITOR.dom.element( 'em' );
\r
159 * var strong = new CKEDITOR.dom.element( 'strong' );
\r
160 * strong.insertBefore( em );
\r
162 * // result: "<strong></strong><em></em>"
\r
164 insertBefore : function( node )
\r
166 node.$.parentNode.insertBefore( this.$, node.$ );
\r
170 insertBeforeMe : function( node )
\r
172 this.$.parentNode.insertBefore( node.$, this.$ );
\r
177 * Retrieves a uniquely identifiable tree address for this node.
\r
178 * The tree address returned is an array of integers, with each integer
\r
179 * indicating a child index of a DOM node, starting from
\r
180 * <code>document.documentElement</code>.
\r
182 * For example, assuming <code><body></code> is the second child
\r
183 * of <code><html></code> (<code><head></code> being the first),
\r
184 * and we would like to address the third child under the
\r
185 * fourth child of <code><body></code>, the tree address returned would be:
\r
188 * The tree address cannot be used for finding back the DOM tree node once
\r
189 * the DOM tree structure has been modified.
\r
191 getAddress : function( normalized )
\r
194 var $documentElement = this.getDocument().$.documentElement;
\r
197 while ( node && node != $documentElement )
\r
199 var parentNode = node.parentNode;
\r
203 // Get the node index. For performance, call getIndex
\r
204 // directly, instead of creating a new node object.
\r
205 address.unshift( this.getIndex.call( { $ : node }, normalized ) );
\r
215 * Gets the document containing this element.
\r
216 * @returns {CKEDITOR.dom.document} The document.
\r
218 * var element = CKEDITOR.document.getById( 'example' );
\r
219 * alert( <strong>element.getDocument().equals( CKEDITOR.document )</strong> ); // "true"
\r
221 getDocument : function()
\r
223 return new CKEDITOR.dom.document( this.$.ownerDocument || this.$.parentNode.ownerDocument );
\r
226 getIndex : function( normalized )
\r
228 // Attention: getAddress depends on this.$
\r
230 var current = this.$,
\r
233 while ( ( current = current.previousSibling ) )
\r
235 // When normalizing, do not count it if this is an
\r
236 // empty text node or if it's a text node following another one.
\r
237 if ( normalized && current.nodeType == 3 &&
\r
238 ( !current.nodeValue.length ||
\r
239 ( current.previousSibling && current.previousSibling.nodeType == 3 ) ) )
\r
250 getNextSourceNode : function( startFromSibling, nodeType, guard )
\r
252 // If "guard" is a node, transform it in a function.
\r
253 if ( guard && !guard.call )
\r
255 var guardNode = guard;
\r
256 guard = function( node )
\r
258 return !node.equals( guardNode );
\r
262 var node = ( !startFromSibling && this.getFirst && this.getFirst() ),
\r
265 // Guarding when we're skipping the current element( no children or 'startFromSibling' ).
\r
266 // send the 'moving out' signal even we don't actually dive into.
\r
269 if ( this.type == CKEDITOR.NODE_ELEMENT && guard && guard( this, true ) === false )
\r
271 node = this.getNext();
\r
274 while ( !node && ( parent = ( parent || this ).getParent() ) )
\r
276 // The guard check sends the "true" paramenter to indicate that
\r
277 // we are moving "out" of the element.
\r
278 if ( guard && guard( parent, true ) === false )
\r
281 node = parent.getNext();
\r
287 if ( guard && guard( node ) === false )
\r
290 if ( nodeType && nodeType != node.type )
\r
291 return node.getNextSourceNode( false, nodeType, guard );
\r
296 getPreviousSourceNode : function( startFromSibling, nodeType, guard )
\r
298 if ( guard && !guard.call )
\r
300 var guardNode = guard;
\r
301 guard = function( node )
\r
303 return !node.equals( guardNode );
\r
307 var node = ( !startFromSibling && this.getLast && this.getLast() ),
\r
310 // Guarding when we're skipping the current element( no children or 'startFromSibling' ).
\r
311 // send the 'moving out' signal even we don't actually dive into.
\r
314 if ( this.type == CKEDITOR.NODE_ELEMENT && guard && guard( this, true ) === false )
\r
316 node = this.getPrevious();
\r
319 while ( !node && ( parent = ( parent || this ).getParent() ) )
\r
321 // The guard check sends the "true" paramenter to indicate that
\r
322 // we are moving "out" of the element.
\r
323 if ( guard && guard( parent, true ) === false )
\r
326 node = parent.getPrevious();
\r
332 if ( guard && guard( node ) === false )
\r
335 if ( nodeType && node.type != nodeType )
\r
336 return node.getPreviousSourceNode( false, nodeType, guard );
\r
341 getPrevious : function( evaluator )
\r
343 var previous = this.$, retval;
\r
346 previous = previous.previousSibling;
\r
348 // Avoid returning the doc type node.
\r
349 // http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html#ID-412266927
\r
350 retval = previous && previous.nodeType != 10 && new CKEDITOR.dom.node( previous );
\r
352 while ( retval && evaluator && !evaluator( retval ) )
\r
357 * Gets the node that follows this element in its parent's child list.
\r
358 * @param {Function} evaluator Filtering the result node.
\r
359 * @returns {CKEDITOR.dom.node} The next node or null if not available.
\r
361 * var element = CKEDITOR.dom.element.createFromHtml( '<div><b>Example</b> <i>next</i></div>' );
\r
362 * var first = <strong>element.getFirst().getNext()</strong>;
\r
363 * alert( first.getName() ); // "i"
\r
365 getNext : function( evaluator )
\r
367 var next = this.$, retval;
\r
370 next = next.nextSibling;
\r
371 retval = next && new CKEDITOR.dom.node( next );
\r
373 while ( retval && evaluator && !evaluator( retval ) )
\r
378 * Gets the parent element for this node.
\r
379 * @returns {CKEDITOR.dom.element} The parent element.
\r
381 * var node = editor.document.getBody().getFirst();
\r
382 * var parent = node.<strong>getParent()</strong>;
\r
383 * alert( node.getName() ); // "body"
\r
385 getParent : function()
\r
387 var parent = this.$.parentNode;
\r
388 return ( parent && parent.nodeType == 1 ) ? new CKEDITOR.dom.node( parent ) : null;
\r
391 getParents : function( closerFirst )
\r
398 parents[ closerFirst ? 'push' : 'unshift' ]( node );
\r
400 while ( ( node = node.getParent() ) )
\r
405 getCommonAncestor : function( node )
\r
407 if ( node.equals( this ) )
\r
410 if ( node.contains && node.contains( this ) )
\r
413 var start = this.contains ? this : this.getParent();
\r
417 if ( start.contains( node ) )
\r
420 while ( ( start = start.getParent() ) );
\r
425 getPosition : function( otherNode )
\r
428 var $other = otherNode.$;
\r
430 if ( $.compareDocumentPosition )
\r
431 return $.compareDocumentPosition( $other );
\r
433 // IE and Safari have no support for compareDocumentPosition.
\r
436 return CKEDITOR.POSITION_IDENTICAL;
\r
438 // Only element nodes support contains and sourceIndex.
\r
439 if ( this.type == CKEDITOR.NODE_ELEMENT && otherNode.type == CKEDITOR.NODE_ELEMENT )
\r
443 if ( $.contains( $other ) )
\r
444 return CKEDITOR.POSITION_CONTAINS + CKEDITOR.POSITION_PRECEDING;
\r
446 if ( $other.contains( $ ) )
\r
447 return CKEDITOR.POSITION_IS_CONTAINED + CKEDITOR.POSITION_FOLLOWING;
\r
450 if ( 'sourceIndex' in $ )
\r
452 return ( $.sourceIndex < 0 || $other.sourceIndex < 0 ) ? CKEDITOR.POSITION_DISCONNECTED :
\r
453 ( $.sourceIndex < $other.sourceIndex ) ? CKEDITOR.POSITION_PRECEDING :
\r
454 CKEDITOR.POSITION_FOLLOWING;
\r
458 // For nodes that don't support compareDocumentPosition, contains
\r
459 // or sourceIndex, their "address" is compared.
\r
461 var addressOfThis = this.getAddress(),
\r
462 addressOfOther = otherNode.getAddress(),
\r
463 minLevel = Math.min( addressOfThis.length, addressOfOther.length );
\r
465 // Determinate preceed/follow relationship.
\r
466 for ( var i = 0 ; i <= minLevel - 1 ; i++ )
\r
468 if ( addressOfThis[ i ] != addressOfOther[ i ] )
\r
470 if ( i < minLevel )
\r
472 return addressOfThis[ i ] < addressOfOther[ i ] ?
\r
473 CKEDITOR.POSITION_PRECEDING : CKEDITOR.POSITION_FOLLOWING;
\r
479 // Determinate contains/contained relationship.
\r
480 return ( addressOfThis.length < addressOfOther.length ) ?
\r
481 CKEDITOR.POSITION_CONTAINS + CKEDITOR.POSITION_PRECEDING :
\r
482 CKEDITOR.POSITION_IS_CONTAINED + CKEDITOR.POSITION_FOLLOWING;
\r
486 * Gets the closest ancestor node of this node, specified by its name.
\r
487 * @param {String} reference The name of the ancestor node to search or
\r
488 * an object with the node names to search for.
\r
489 * @param {Boolean} [includeSelf] Whether to include the current
\r
490 * node in the search.
\r
491 * @returns {CKEDITOR.dom.node} The located ancestor node or null if not found.
\r
494 * // Suppose we have the following HTML structure:
\r
495 * // <div id="outer"><div id="inner"><p><b>Some text</b></p></div></div>
\r
496 * // If node == <b>
\r
497 * ascendant = node.getAscendant( 'div' ); // ascendant == <div id="inner">
\r
498 * ascendant = node.getAscendant( 'b' ); // ascendant == null
\r
499 * ascendant = node.getAscendant( 'b', true ); // ascendant == <b>
\r
500 * ascendant = node.getAscendant( { div: 1, p: 1} ); // Searches for the first 'div' or 'p': ascendant == <div id="inner">
\r
502 getAscendant : function( reference, includeSelf )
\r
507 if ( !includeSelf )
\r
512 if ( $.nodeName && ( name = $.nodeName.toLowerCase(), ( typeof reference == 'string' ? name == reference : name in reference ) ) )
\r
513 return new CKEDITOR.dom.node( $ );
\r
520 hasAscendant : function( name, includeSelf )
\r
524 if ( !includeSelf )
\r
529 if ( $.nodeName && $.nodeName.toLowerCase() == name )
\r
537 move : function( target, toStart )
\r
539 target.append( this.remove(), toStart );
\r
543 * Removes this node from the document DOM.
\r
544 * @param {Boolean} [preserveChildren] Indicates that the children
\r
545 * elements must remain in the document, removing only the outer
\r
548 * var element = CKEDITOR.dom.element.getById( 'MyElement' );
\r
549 * <strong>element.remove()</strong>;
\r
551 remove : function( preserveChildren )
\r
554 var parent = $.parentNode;
\r
558 if ( preserveChildren )
\r
560 // Move all children before the node.
\r
561 for ( var child ; ( child = $.firstChild ) ; )
\r
563 parent.insertBefore( $.removeChild( child ), $ );
\r
567 parent.removeChild( $ );
\r
573 replace : function( nodeToReplace )
\r
575 this.insertBefore( nodeToReplace );
\r
576 nodeToReplace.remove();
\r
588 while ( this.getFirst && ( child = this.getFirst() ) )
\r
590 if ( child.type == CKEDITOR.NODE_TEXT )
\r
592 var trimmed = CKEDITOR.tools.ltrim( child.getText() ),
\r
593 originalLength = child.getLength();
\r
600 else if ( trimmed.length < originalLength )
\r
602 child.split( originalLength - trimmed.length );
\r
604 // IE BUG: child.remove() may raise JavaScript errors here. (#81)
\r
605 this.$.removeChild( this.$.firstChild );
\r
615 while ( this.getLast && ( child = this.getLast() ) )
\r
617 if ( child.type == CKEDITOR.NODE_TEXT )
\r
619 var trimmed = CKEDITOR.tools.rtrim( child.getText() ),
\r
620 originalLength = child.getLength();
\r
627 else if ( trimmed.length < originalLength )
\r
629 child.split( trimmed.length );
\r
631 // IE BUG: child.getNext().remove() may raise JavaScript errors here.
\r
633 this.$.lastChild.parentNode.removeChild( this.$.lastChild );
\r
639 if ( !CKEDITOR.env.ie && !CKEDITOR.env.opera )
\r
641 child = this.$.lastChild;
\r
643 if ( child && child.type == 1 && child.nodeName.toLowerCase() == 'br' )
\r
645 // Use "eChildNode.parentNode" instead of "node" to avoid IE bug (#324).
\r
646 child.parentNode.removeChild( child ) ;
\r
652 * Checks if this node is read-only (should not be changed).
\r
653 * @returns {Boolean}
\r
656 * // For the following HTML:
\r
657 * // <div contenteditable="false">Some <b>text</b></div>
\r
659 * // If "ele" is the above <div>
\r
660 * ele.isReadOnly(); // true
\r
662 isReadOnly : function()
\r
664 var element = this;
\r
665 if ( this.type != CKEDITOR.NODE_ELEMENT )
\r
666 element = this.getParent();
\r
668 if ( element && typeof element.$.isContentEditable != 'undefined' )
\r
669 return ! ( element.$.isContentEditable || element.data( 'cke-editable' ) );
\r
672 // Degrade for old browsers which don't support "isContentEditable", e.g. FF3
\r
673 var current = element;
\r
676 if ( current.is( 'body' ) || !!current.data( 'cke-editable' ) )
\r
679 if ( current.getAttribute( 'contentEditable' ) == 'false' )
\r
681 else if ( current.getAttribute( 'contentEditable' ) == 'true' )
\r
684 current = current.getParent();
\r