X-Git-Url: https://jasonwoof.com/gitweb/?a=blobdiff_plain;ds=sidebyside;f=_source%2Fcore%2Fdom%2Fnode.js;h=293ce2304c3ea388224abfb8831c30c3b4d1bcd6;hb=refs%2Ftags%2Fv3.6.1;hp=b05b4a7aa6fb0cd880b4c82b9500c0825da34de6;hpb=4e70ea24db840898be8cc21c950363a52a2a6aba;p=ckeditor.git
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
<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.