JasonWoof Got questions, comments, patches, etc.? Contact Jason Woofenden
vanilla ckeditor-3.2
[ckeditor.git] / _source / core / dom / node.js
1 /*\r
2 Copyright (c) 2003-2010, CKSource - Frederico Knabben. All rights reserved.\r
3 For licensing, see LICENSE.html or http://ckeditor.com/license\r
4 */\r
5 \r
6 /**\r
7  * @fileOverview Defines the {@link CKEDITOR.dom.node} class, which is the base\r
8  *              class for classes that represent DOM nodes.\r
9  */\r
10 \r
11 /**\r
12  * Base class for classes representing DOM nodes. This constructor may return\r
13  * and instance of classes that inherits 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
17  * @constructor\r
18  * @see CKEDITOR.dom.element\r
19  * @see CKEDITOR.dom.text\r
20  * @example\r
21  */\r
22 CKEDITOR.dom.node = function( domNode )\r
23 {\r
24         if ( domNode )\r
25         {\r
26                 switch ( domNode.nodeType )\r
27                 {\r
28                         // Safari don't consider document as element node type. (#3389)\r
29                         case CKEDITOR.NODE_DOCUMENT :\r
30                                 return new CKEDITOR.dom.document( domNode );\r
31 \r
32                         case CKEDITOR.NODE_ELEMENT :\r
33                                 return new CKEDITOR.dom.element( domNode );\r
34 \r
35                         case CKEDITOR.NODE_TEXT :\r
36                                 return new CKEDITOR.dom.text( domNode );\r
37                 }\r
38 \r
39                 // Call the base constructor.\r
40                 CKEDITOR.dom.domObject.call( this, domNode );\r
41         }\r
42 \r
43         return this;\r
44 };\r
45 \r
46 CKEDITOR.dom.node.prototype = new CKEDITOR.dom.domObject();\r
47 \r
48 /**\r
49  * Element node type.\r
50  * @constant\r
51  * @example\r
52  */\r
53 CKEDITOR.NODE_ELEMENT = 1;\r
54 \r
55 /**\r
56  * Document node type.\r
57  * @constant\r
58  * @example\r
59  */\r
60 CKEDITOR.NODE_DOCUMENT = 9;\r
61 \r
62 /**\r
63  * Text node type.\r
64  * @constant\r
65  * @example\r
66  */\r
67 CKEDITOR.NODE_TEXT = 3;\r
68 \r
69 /**\r
70  * Comment node type.\r
71  * @constant\r
72  * @example\r
73  */\r
74 CKEDITOR.NODE_COMMENT = 8;\r
75 \r
76 CKEDITOR.NODE_DOCUMENT_FRAGMENT = 11;\r
77 \r
78 CKEDITOR.POSITION_IDENTICAL = 0;\r
79 CKEDITOR.POSITION_DISCONNECTED = 1;\r
80 CKEDITOR.POSITION_FOLLOWING = 2;\r
81 CKEDITOR.POSITION_PRECEDING = 4;\r
82 CKEDITOR.POSITION_IS_CONTAINED = 8;\r
83 CKEDITOR.POSITION_CONTAINS = 16;\r
84 \r
85 CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype,\r
86         /** @lends CKEDITOR.dom.node.prototype */\r
87         {\r
88                 /**\r
89                  * Makes this node child of another element.\r
90                  * @param {CKEDITOR.dom.element} element The target element to which append\r
91                  *              this node.\r
92                  * @returns {CKEDITOR.dom.element} The target element.\r
93                  * @example\r
94                  * var p = new CKEDITOR.dom.element( 'p' );\r
95                  * var strong = new CKEDITOR.dom.element( 'strong' );\r
96                  * strong.appendTo( p );\r
97                  *\r
98                  * // result: "<p><strong></strong></p>"\r
99                  */\r
100                 appendTo : function( element, toStart )\r
101                 {\r
102                         element.append( this, toStart );\r
103                         return element;\r
104                 },\r
105 \r
106                 clone : function( includeChildren, cloneId )\r
107                 {\r
108                         var $clone = this.$.cloneNode( includeChildren );\r
109 \r
110                         if ( !cloneId )\r
111                         {\r
112                                 var removeIds = function( node )\r
113                                 {\r
114                                         if ( node.nodeType != CKEDITOR.NODE_ELEMENT )\r
115                                                 return;\r
116 \r
117                                         node.removeAttribute( 'id', false ) ;\r
118                                         node.removeAttribute( '_cke_expando', false ) ;\r
119 \r
120                                         var childs = node.childNodes;\r
121                                         for ( var i=0 ; i < childs.length ; i++ )\r
122                                                 removeIds( childs[ i ] );\r
123                                 };\r
124 \r
125                                 // The "id" attribute should never be cloned to avoid duplication.\r
126                                 removeIds( $clone );\r
127                         }\r
128 \r
129                         return new CKEDITOR.dom.node( $clone );\r
130                 },\r
131 \r
132                 hasPrevious : function()\r
133                 {\r
134                         return !!this.$.previousSibling;\r
135                 },\r
136 \r
137                 hasNext : function()\r
138                 {\r
139                         return !!this.$.nextSibling;\r
140                 },\r
141 \r
142                 /**\r
143                  * Inserts this element after a node.\r
144                  * @param {CKEDITOR.dom.node} node The that will preceed this element.\r
145                  * @returns {CKEDITOR.dom.node} The node preceeding this one after\r
146                  *              insertion.\r
147                  * @example\r
148                  * var em = new CKEDITOR.dom.element( 'em' );\r
149                  * var strong = new CKEDITOR.dom.element( 'strong' );\r
150                  * strong.insertAfter( em );\r
151                  *\r
152                  * // result: "&lt;em&gt;&lt;/em&gt;&lt;strong&gt;&lt;/strong&gt;"\r
153                  */\r
154                 insertAfter : function( node )\r
155                 {\r
156                         node.$.parentNode.insertBefore( this.$, node.$.nextSibling );\r
157                         return node;\r
158                 },\r
159 \r
160                 /**\r
161                  * Inserts this element before a node.\r
162                  * @param {CKEDITOR.dom.node} node The that will be after this element.\r
163                  * @returns {CKEDITOR.dom.node} The node being inserted.\r
164                  * @example\r
165                  * var em = new CKEDITOR.dom.element( 'em' );\r
166                  * var strong = new CKEDITOR.dom.element( 'strong' );\r
167                  * strong.insertBefore( em );\r
168                  *\r
169                  * // result: "&lt;strong&gt;&lt;/strong&gt;&lt;em&gt;&lt;/em&gt;"\r
170                  */\r
171                 insertBefore : function( node )\r
172                 {\r
173                         node.$.parentNode.insertBefore( this.$, node.$ );\r
174                         return node;\r
175                 },\r
176 \r
177                 insertBeforeMe : function( node )\r
178                 {\r
179                         this.$.parentNode.insertBefore( node.$, this.$ );\r
180                         return node;\r
181                 },\r
182 \r
183                 /**\r
184                  * Retrieves a uniquely identifiable tree address for this node.\r
185                  * The tree address returns is an array of integers, with each integer\r
186                  * indicating a child index of a DOM node, starting from\r
187                  * document.documentElement.\r
188                  *\r
189                  * For example, assuming <body> is the second child from <html> (<head>\r
190                  * being the first), and we'd like to address the third child under the\r
191                  * fourth child of body, the tree address returned would be:\r
192                  * [1, 3, 2]\r
193                  *\r
194                  * The tree address cannot be used for finding back the DOM tree node once\r
195                  * the DOM tree structure has been modified.\r
196                  */\r
197                 getAddress : function( normalized )\r
198                 {\r
199                         var address = [];\r
200                         var $documentElement = this.getDocument().$.documentElement;\r
201                         var node = this.$;\r
202 \r
203                         while ( node && node != $documentElement )\r
204                         {\r
205                                 var parentNode = node.parentNode;\r
206                                 var currentIndex = -1;\r
207 \r
208                                 if ( parentNode )\r
209                                 {\r
210                                         for ( var i = 0 ; i < parentNode.childNodes.length ; i++ )\r
211                                         {\r
212                                                 var candidate = parentNode.childNodes[i];\r
213 \r
214                                                 if ( normalized &&\r
215                                                                 candidate.nodeType == 3 &&\r
216                                                                 candidate.previousSibling &&\r
217                                                                 candidate.previousSibling.nodeType == 3 )\r
218                                                 {\r
219                                                         continue;\r
220                                                 }\r
221 \r
222                                                 currentIndex++;\r
223 \r
224                                                 if ( candidate == node )\r
225                                                         break;\r
226                                         }\r
227 \r
228                                         address.unshift( currentIndex );\r
229                                 }\r
230 \r
231                                 node = parentNode;\r
232                         }\r
233 \r
234                         return address;\r
235                 },\r
236 \r
237                 /**\r
238                  * Gets the document containing this element.\r
239                  * @returns {CKEDITOR.dom.document} The document.\r
240                  * @example\r
241                  * var element = CKEDITOR.document.getById( 'example' );\r
242                  * alert( <b>element.getDocument().equals( CKEDITOR.document )</b> );  // "true"\r
243                  */\r
244                 getDocument : function()\r
245                 {\r
246                         var document = new CKEDITOR.dom.document( this.$.ownerDocument || this.$.parentNode.ownerDocument );\r
247 \r
248                         return (\r
249                         this.getDocument = function()\r
250                                 {\r
251                                         return document;\r
252                                 })();\r
253                 },\r
254 \r
255                 getIndex : function()\r
256                 {\r
257                         var $ = this.$;\r
258 \r
259                         var currentNode = $.parentNode && $.parentNode.firstChild;\r
260                         var currentIndex = -1;\r
261 \r
262                         while ( currentNode )\r
263                         {\r
264                                 currentIndex++;\r
265 \r
266                                 if ( currentNode == $ )\r
267                                         return currentIndex;\r
268 \r
269                                 currentNode = currentNode.nextSibling;\r
270                         }\r
271 \r
272                         return -1;\r
273                 },\r
274 \r
275                 getNextSourceNode : function( startFromSibling, nodeType, guard )\r
276                 {\r
277                         // If "guard" is a node, transform it in a function.\r
278                         if ( guard && !guard.call )\r
279                         {\r
280                                 var guardNode = guard;\r
281                                 guard = function( node )\r
282                                 {\r
283                                         return !node.equals( guardNode );\r
284                                 };\r
285                         }\r
286 \r
287                         var node = ( !startFromSibling && this.getFirst && this.getFirst() ),\r
288                                 parent;\r
289 \r
290                         // Guarding when we're skipping the current element( no children or 'startFromSibling' ).\r
291                         // send the 'moving out' signal even we don't actually dive into.\r
292                         if ( !node )\r
293                         {\r
294                                 if ( this.type == CKEDITOR.NODE_ELEMENT && guard && guard( this, true ) === false )\r
295                                         return null;\r
296                                 node = this.getNext();\r
297                         }\r
298 \r
299                         while ( !node && ( parent = ( parent || this ).getParent() ) )\r
300                         {\r
301                                 // The guard check sends the "true" paramenter to indicate that\r
302                                 // we are moving "out" of the element.\r
303                                 if ( guard && guard( parent, true ) === false )\r
304                                         return null;\r
305 \r
306                                 node = parent.getNext();\r
307                         }\r
308 \r
309                         if ( !node )\r
310                                 return null;\r
311 \r
312                         if ( guard && guard( node ) === false )\r
313                                 return null;\r
314 \r
315                         if ( nodeType && nodeType != node.type )\r
316                                 return node.getNextSourceNode( false, nodeType, guard );\r
317 \r
318                         return node;\r
319                 },\r
320 \r
321                 getPreviousSourceNode : function( startFromSibling, nodeType, guard )\r
322                 {\r
323                         if ( guard && !guard.call )\r
324                         {\r
325                                 var guardNode = guard;\r
326                                 guard = function( node )\r
327                                 {\r
328                                         return !node.equals( guardNode );\r
329                                 };\r
330                         }\r
331 \r
332                         var node = ( !startFromSibling && this.getLast && this.getLast() ),\r
333                                 parent;\r
334 \r
335                         // Guarding when we're skipping the current element( no children or 'startFromSibling' ).\r
336                         // send the 'moving out' signal even we don't actually dive into.\r
337                         if ( !node )\r
338                         {\r
339                                 if ( this.type == CKEDITOR.NODE_ELEMENT && guard && guard( this, true ) === false )\r
340                                         return null;\r
341                                 node = this.getPrevious();\r
342                         }\r
343 \r
344                         while ( !node && ( parent = ( parent || this ).getParent() ) )\r
345                         {\r
346                                 // The guard check sends the "true" paramenter to indicate that\r
347                                 // we are moving "out" of the element.\r
348                                 if ( guard && guard( parent, true ) === false )\r
349                                         return null;\r
350 \r
351                                 node = parent.getPrevious();\r
352                         }\r
353 \r
354                         if ( !node )\r
355                                 return null;\r
356 \r
357                         if ( guard && guard( node ) === false )\r
358                                 return null;\r
359 \r
360                         if ( nodeType && node.type != nodeType )\r
361                                 return node.getPreviousSourceNode( false, nodeType, guard );\r
362 \r
363                         return node;\r
364                 },\r
365 \r
366                 getPrevious : function( evaluator )\r
367                 {\r
368                         var previous = this.$, retval;\r
369                         do\r
370                         {\r
371                                 previous = previous.previousSibling;\r
372                                 retval = previous && new CKEDITOR.dom.node( previous );\r
373                         }\r
374                         while ( retval && evaluator && !evaluator( retval ) )\r
375                         return retval;\r
376                 },\r
377 \r
378                 /**\r
379                  * Gets the node that follows this element in its parent's child list.\r
380                  * @param {Function} evaluator Filtering the result node.\r
381                  * @returns {CKEDITOR.dom.node} The next node or null if not available.\r
382                  * @example\r
383                  * var element = CKEDITOR.dom.element.createFromHtml( '&lt;div&gt;&lt;b&gt;Example&lt;/b&gt; &lt;i&gt;next&lt;/i&gt;&lt;/div&gt;' );\r
384                  * var first = <b>element.getFirst().getNext()</b>;\r
385                  * alert( first.getName() );  // "i"\r
386                  */\r
387                 getNext : function( evaluator )\r
388                 {\r
389                         var next = this.$, retval;\r
390                         do\r
391                         {\r
392                                 next = next.nextSibling;\r
393                                 retval = next && new CKEDITOR.dom.node( next );\r
394                         }\r
395                         while ( retval && evaluator && !evaluator( retval ) )\r
396                         return retval;\r
397                 },\r
398 \r
399                 /**\r
400                  * Gets the parent element for this node.\r
401                  * @returns {CKEDITOR.dom.element} The parent element.\r
402                  * @example\r
403                  * var node = editor.document.getBody().getFirst();\r
404                  * var parent = node.<b>getParent()</b>;\r
405                  * alert( node.getName() );  // "body"\r
406                  */\r
407                 getParent : function()\r
408                 {\r
409                         var parent = this.$.parentNode;\r
410                         return ( parent && parent.nodeType == 1 ) ? new CKEDITOR.dom.node( parent ) : null;\r
411                 },\r
412 \r
413                 getParents : function( closerFirst )\r
414                 {\r
415                         var node = this;\r
416                         var parents = [];\r
417 \r
418                         do\r
419                         {\r
420                                 parents[  closerFirst ? 'push' : 'unshift' ]( node );\r
421                         }\r
422                         while ( ( node = node.getParent() ) )\r
423 \r
424                         return parents;\r
425                 },\r
426 \r
427                 getCommonAncestor : function( node )\r
428                 {\r
429                         if ( node.equals( this ) )\r
430                                 return this;\r
431 \r
432                         if ( node.contains && node.contains( this ) )\r
433                                 return node;\r
434 \r
435                         var start = this.contains ? this : this.getParent();\r
436 \r
437                         do\r
438                         {\r
439                                 if ( start.contains( node ) )\r
440                                         return start;\r
441                         }\r
442                         while ( ( start = start.getParent() ) );\r
443 \r
444                         return null;\r
445                 },\r
446 \r
447                 getPosition : function( otherNode )\r
448                 {\r
449                         var $ = this.$;\r
450                         var $other = otherNode.$;\r
451 \r
452                         if ( $.compareDocumentPosition )\r
453                                 return $.compareDocumentPosition( $other );\r
454 \r
455                         // IE and Safari have no support for compareDocumentPosition.\r
456 \r
457                         if ( $ == $other )\r
458                                 return CKEDITOR.POSITION_IDENTICAL;\r
459 \r
460                         // Only element nodes support contains and sourceIndex.\r
461                         if ( this.type == CKEDITOR.NODE_ELEMENT && otherNode.type == CKEDITOR.NODE_ELEMENT )\r
462                         {\r
463                                 if ( $.contains )\r
464                                 {\r
465                                         if ( $.contains( $other ) )\r
466                                                 return CKEDITOR.POSITION_CONTAINS + CKEDITOR.POSITION_PRECEDING;\r
467 \r
468                                         if ( $other.contains( $ ) )\r
469                                                 return CKEDITOR.POSITION_IS_CONTAINED + CKEDITOR.POSITION_FOLLOWING;\r
470                                 }\r
471 \r
472                                 if ( 'sourceIndex' in $ )\r
473                                 {\r
474                                         return ( $.sourceIndex < 0 || $other.sourceIndex < 0 ) ? CKEDITOR.POSITION_DISCONNECTED :\r
475                                                 ( $.sourceIndex < $other.sourceIndex ) ? CKEDITOR.POSITION_PRECEDING :\r
476                                                 CKEDITOR.POSITION_FOLLOWING;\r
477                                 }\r
478                         }\r
479 \r
480                         // For nodes that don't support compareDocumentPosition, contains\r
481                         // or sourceIndex, their "address" is compared.\r
482 \r
483                         var addressOfThis = this.getAddress(),\r
484                                 addressOfOther = otherNode.getAddress(),\r
485                                 minLevel = Math.min( addressOfThis.length, addressOfOther.length );\r
486 \r
487                                 // Determinate preceed/follow relationship.\r
488                                 for ( var i = 0 ; i <= minLevel - 1 ; i++ )\r
489                                 {\r
490                                         if ( addressOfThis[ i ] != addressOfOther[ i ] )\r
491                                         {\r
492                                                 if ( i < minLevel )\r
493                                                 {\r
494                                                         return addressOfThis[ i ] < addressOfOther[ i ] ?\r
495                                                             CKEDITOR.POSITION_PRECEDING : CKEDITOR.POSITION_FOLLOWING;\r
496                                                 }\r
497                                                 break;\r
498                                         }\r
499                                 }\r
500 \r
501                                 // Determinate contains/contained relationship.\r
502                                 return ( addressOfThis.length < addressOfOther.length ) ?\r
503                                                         CKEDITOR.POSITION_CONTAINS + CKEDITOR.POSITION_PRECEDING :\r
504                                                         CKEDITOR.POSITION_IS_CONTAINED + CKEDITOR.POSITION_FOLLOWING;\r
505                 },\r
506 \r
507                 /**\r
508                  * Gets the closes ancestor node of a specified node name.\r
509                  * @param {String} name Node name of ancestor node.\r
510                  * @param {Boolean} includeSelf (Optional) Whether to include the current\r
511                  * node in the calculation or not.\r
512                  * @returns {CKEDITOR.dom.node} Ancestor node.\r
513                  */\r
514                 getAscendant : function( name, includeSelf )\r
515                 {\r
516                         var $ = this.$;\r
517 \r
518                         if ( !includeSelf )\r
519                                 $ = $.parentNode;\r
520 \r
521                         while ( $ )\r
522                         {\r
523                                 if ( $.nodeName && $.nodeName.toLowerCase() == name )\r
524                                         return new CKEDITOR.dom.node( $ );\r
525 \r
526                                 $ = $.parentNode;\r
527                         }\r
528                         return null;\r
529                 },\r
530 \r
531                 hasAscendant : function( name, includeSelf )\r
532                 {\r
533                         var $ = this.$;\r
534 \r
535                         if ( !includeSelf )\r
536                                 $ = $.parentNode;\r
537 \r
538                         while ( $ )\r
539                         {\r
540                                 if ( $.nodeName && $.nodeName.toLowerCase() == name )\r
541                                         return true;\r
542 \r
543                                 $ = $.parentNode;\r
544                         }\r
545                         return false;\r
546                 },\r
547 \r
548                 move : function( target, toStart )\r
549                 {\r
550                         target.append( this.remove(), toStart );\r
551                 },\r
552 \r
553                 /**\r
554                  * Removes this node from the document DOM.\r
555                  * @param {Boolean} [preserveChildren] Indicates that the children\r
556                  *              elements must remain in the document, removing only the outer\r
557                  *              tags.\r
558                  * @example\r
559                  * var element = CKEDITOR.dom.element.getById( 'MyElement' );\r
560                  * <b>element.remove()</b>;\r
561                  */\r
562                 remove : function( preserveChildren )\r
563                 {\r
564                         var $ = this.$;\r
565                         var parent = $.parentNode;\r
566 \r
567                         if ( parent )\r
568                         {\r
569                                 if ( preserveChildren )\r
570                                 {\r
571                                         // Move all children before the node.\r
572                                         for ( var child ; ( child = $.firstChild ) ; )\r
573                                         {\r
574                                                 parent.insertBefore( $.removeChild( child ), $ );\r
575                                         }\r
576                                 }\r
577 \r
578                                 parent.removeChild( $ );\r
579                         }\r
580 \r
581                         return this;\r
582                 },\r
583 \r
584                 replace : function( nodeToReplace )\r
585                 {\r
586                         this.insertBefore( nodeToReplace );\r
587                         nodeToReplace.remove();\r
588                 },\r
589 \r
590                 trim : function()\r
591                 {\r
592                         this.ltrim();\r
593                         this.rtrim();\r
594                 },\r
595 \r
596                 ltrim : function()\r
597                 {\r
598                         var child;\r
599                         while ( this.getFirst && ( child = this.getFirst() ) )\r
600                         {\r
601                                 if ( child.type == CKEDITOR.NODE_TEXT )\r
602                                 {\r
603                                         var trimmed = CKEDITOR.tools.ltrim( child.getText() ),\r
604                                                 originalLength = child.getLength();\r
605 \r
606                                         if ( !trimmed )\r
607                                         {\r
608                                                 child.remove();\r
609                                                 continue;\r
610                                         }\r
611                                         else if ( trimmed.length < originalLength )\r
612                                         {\r
613                                                 child.split( originalLength - trimmed.length );\r
614 \r
615                                                 // IE BUG: child.remove() may raise JavaScript errors here. (#81)\r
616                                                 this.$.removeChild( this.$.firstChild );\r
617                                         }\r
618                                 }\r
619                                 break;\r
620                         }\r
621                 },\r
622 \r
623                 rtrim : function()\r
624                 {\r
625                         var child;\r
626                         while ( this.getLast && ( child = this.getLast() ) )\r
627                         {\r
628                                 if ( child.type == CKEDITOR.NODE_TEXT )\r
629                                 {\r
630                                         var trimmed = CKEDITOR.tools.rtrim( child.getText() ),\r
631                                                 originalLength = child.getLength();\r
632 \r
633                                         if ( !trimmed )\r
634                                         {\r
635                                                 child.remove();\r
636                                                 continue;\r
637                                         }\r
638                                         else if ( trimmed.length < originalLength )\r
639                                         {\r
640                                                 child.split( trimmed.length );\r
641 \r
642                                                 // IE BUG: child.getNext().remove() may raise JavaScript errors here.\r
643                                                 // (#81)\r
644                                                 this.$.lastChild.parentNode.removeChild( this.$.lastChild );\r
645                                         }\r
646                                 }\r
647                                 break;\r
648                         }\r
649 \r
650                         if ( !CKEDITOR.env.ie && !CKEDITOR.env.opera )\r
651                         {\r
652                                 child = this.$.lastChild;\r
653 \r
654                                 if ( child && child.type == 1 && child.nodeName.toLowerCase() == 'br' )\r
655                                 {\r
656                                         // Use "eChildNode.parentNode" instead of "node" to avoid IE bug (#324).\r
657                                         child.parentNode.removeChild( child ) ;\r
658                                 }\r
659                         }\r
660                 }\r
661         }\r
662 );\r