X-Git-Url: https://jasonwoof.com/gitweb/?p=ckeditor.git;a=blobdiff_plain;f=_source%2Fcore%2Fdom%2Fnode.js;h=293ce2304c3ea388224abfb8831c30c3b4d1bcd6;hp=b05b4a7aa6fb0cd880b4c82b9500c0825da34de6;hb=f0610347140239143439a511ee2bd48cb784f470;hpb=4e70ea24db840898be8cc21c950363a52a2a6aba diff --git a/_source/core/dom/node.js b/_source/core/dom/node.js index b05b4a7..293ce23 100644 --- a/_source/core/dom/node.js +++ b/_source/core/dom/node.js @@ -4,13 +4,13 @@ For licensing, see LICENSE.html or http://ckeditor.com/license */ /** - * @fileOverview Defines the {@link CKEDITOR.dom.node} class, which is the base + * @fileOverview Defines the {@link CKEDITOR.dom.node} class which is the base * class for classes that represent DOM nodes. */ /** * Base class for classes representing DOM nodes. This constructor may return - * and instance of classes that inherits this class, like + * an instance of a class that inherits from this class, like * {@link CKEDITOR.dom.element} or {@link CKEDITOR.dom.text}. * @augments CKEDITOR.dom.domObject * @param {Object} domNode A native DOM node. @@ -86,9 +86,9 @@ CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype, /** @lends CKEDITOR.dom.node.prototype */ { /** - * Makes this node child of another element. - * @param {CKEDITOR.dom.element} element The target element to which append - * this node. + * Makes this node a child of another element. + * @param {CKEDITOR.dom.element} element The target element to which + * this node will be appended. * @returns {CKEDITOR.dom.element} The target element. * @example * var p = new CKEDITOR.dom.element( 'p' ); @@ -142,8 +142,8 @@ CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype, /** * Inserts this element after a node. - * @param {CKEDITOR.dom.node} node The that will preceed this element. - * @returns {CKEDITOR.dom.node} The node preceeding this one after + * @param {CKEDITOR.dom.node} node The node that will precede this element. + * @returns {CKEDITOR.dom.node} The node preceding this one after * insertion. * @example * var em = new CKEDITOR.dom.element( 'em' ); @@ -160,7 +160,7 @@ CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype, /** * Inserts this element before a node. - * @param {CKEDITOR.dom.node} node The that will be after this element. + * @param {CKEDITOR.dom.node} node The node that will succeed this element. * @returns {CKEDITOR.dom.node} The node being inserted. * @example * var em = new CKEDITOR.dom.element( 'em' ); @@ -183,13 +183,14 @@ CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype, /** * Retrieves a uniquely identifiable tree address for this node. - * The tree address returns is an array of integers, with each integer + * The tree address returned is an array of integers, with each integer * indicating a child index of a DOM node, starting from - * document.documentElement. + * document.documentElement. * - * For example, assuming is the second child from ( - * being the first), and we'd like to address the third child under the - * fourth child of body, the tree address returned would be: + * For example, assuming <body> is the second child + * of <html> (<head> being the first), + * and we would like to address the third child under the + * fourth child of <body>, the tree address returned would be: * [1, 3, 2] * * The tree address cannot be used for finding back the DOM tree node once @@ -223,7 +224,7 @@ CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype, * @returns {CKEDITOR.dom.document} The document. * @example * var element = CKEDITOR.document.getById( 'example' ); - * alert( element.getDocument().equals( CKEDITOR.document ) ); // "true" + * alert( element.getDocument().equals( CKEDITOR.document ) ); // "true" */ getDocument : function() { @@ -363,7 +364,7 @@ CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype, * @returns {CKEDITOR.dom.node} The next node or null if not available. * @example * var element = CKEDITOR.dom.element.createFromHtml( '<div><b>Example</b> <i>next</i></div>' ); - * var first = element.getFirst().getNext(); + * var first = element.getFirst().getNext(); * alert( first.getName() ); // "i" */ getNext : function( evaluator ) @@ -383,7 +384,7 @@ CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype, * @returns {CKEDITOR.dom.element} The parent element. * @example * var node = editor.document.getBody().getFirst(); - * var parent = node.getParent(); + * var parent = node.getParent(); * alert( node.getName() ); // "body" */ getParent : function() @@ -487,29 +488,33 @@ CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype, }, /** - * Gets the closest ancestor node of this node, specified by its node name. - * @param {String} name The node name of the ancestor node to search. + * Gets the closest ancestor node of this node, specified by its name. + * @param {String} reference The name of the ancestor node to search or + * an object with the node names to search for. * @param {Boolean} [includeSelf] Whether to include the current - * node in the search. + * node in the search. * @returns {CKEDITOR.dom.node} The located ancestor node or null if not found. + * @since 3.6.1 * @example - * // Suppose we have the following HTML: + * // Suppose we have the following HTML structure: * // <div id="outer"><div id="inner"><p><b>Some text</b></p></div></div> * // If node == <b> * ascendant = node.getAscendant( 'div' ); // ascendant == <div id="inner"> * ascendant = node.getAscendant( 'b' ); // ascendant == null * ascendant = node.getAscendant( 'b', true ); // ascendant == <b> + * ascendant = node.getAscendant( { div: 1, p: 1} ); // Searches for the first 'div' or 'p': ascendant == <div id="inner"> */ - getAscendant : function( name, includeSelf ) + getAscendant : function( reference, includeSelf ) { - var $ = this.$; + var $ = this.$, + name; if ( !includeSelf ) $ = $.parentNode; while ( $ ) { - if ( $.nodeName && $.nodeName.toLowerCase() == name ) + if ( $.nodeName && ( name = $.nodeName.toLowerCase(), ( typeof reference == 'string' ? name == reference : name in reference ) ) ) return new CKEDITOR.dom.node( $ ); $ = $.parentNode; @@ -546,7 +551,7 @@ CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype, * tags. * @example * var element = CKEDITOR.dom.element.getById( 'MyElement' ); - * element.remove(); + * element.remove(); */ remove : function( preserveChildren ) { @@ -649,9 +654,9 @@ CKEDITOR.tools.extend( CKEDITOR.dom.node.prototype, }, /** - * Checks is this node is read-only (should not be changed). It - * additionaly returns the element, if any, which defines the read-only - * state of this node. It may be the node itself or any of its parent + * Checks if this node is read-only (should not be changed). Additionally + * it returns the element that defines the read-only state of this node + * (if present). It may be the node itself or any of its parent * nodes. * @returns {CKEDITOR.dom.element|Boolean} An element containing * read-only attributes or "false" if none is found.