*/\r
\r
/**\r
- * @fileOverview Defines the {@link CKEDITOR.dom.node} class, which is the base\r
+ * @fileOverview Defines the {@link CKEDITOR.dom.node} class which is the base\r
* class for classes that represent DOM nodes.\r
*/\r
\r
/**\r
* Base class for classes representing DOM nodes. This constructor may return\r
- * and instance of classes that inherits this class, like\r
+ * an instance of a class that inherits from this class, like\r
* {@link CKEDITOR.dom.element} or {@link CKEDITOR.dom.text}.\r
* @augments CKEDITOR.dom.domObject\r
* @param {Object} domNode A native DOM node.\r
/** @lends CKEDITOR.dom.node.prototype */\r
{\r
/**\r
- * Makes this node child of another element.\r
- * @param {CKEDITOR.dom.element} element The target element to which append\r
- * this node.\r
+ * Makes this node a child of another element.\r
+ * @param {CKEDITOR.dom.element} element The target element to which\r
+ * this node will be appended.\r
* @returns {CKEDITOR.dom.element} The target element.\r
* @example\r
* var p = new CKEDITOR.dom.element( 'p' );\r
\r
/**\r
* Inserts this element after a node.\r
- * @param {CKEDITOR.dom.node} node The that will preceed this element.\r
- * @returns {CKEDITOR.dom.node} The node preceeding this one after\r
+ * @param {CKEDITOR.dom.node} node The node that will precede this element.\r
+ * @returns {CKEDITOR.dom.node} The node preceding this one after\r
* insertion.\r
* @example\r
* var em = new CKEDITOR.dom.element( 'em' );\r
\r
/**\r
* Inserts this element before a node.\r
- * @param {CKEDITOR.dom.node} node The that will be after this element.\r
+ * @param {CKEDITOR.dom.node} node The node that will succeed this element.\r
* @returns {CKEDITOR.dom.node} The node being inserted.\r
* @example\r
* var em = new CKEDITOR.dom.element( 'em' );\r
\r
/**\r
* Retrieves a uniquely identifiable tree address for this node.\r
- * The tree address returns is an array of integers, with each integer\r
+ * The tree address returned is an array of integers, with each integer\r
* indicating a child index of a DOM node, starting from\r
- * document.documentElement.\r
+ * <code>document.documentElement</code>.\r
*\r
- * For example, assuming <body> is the second child from <html> (<head>\r
- * being the first), and we'd like to address the third child under the\r
- * fourth child of body, the tree address returned would be:\r
+ * For example, assuming <code><body></code> is the second child\r
+ * of <code><html></code> (<code><head></code> being the first),\r
+ * and we would like to address the third child under the\r
+ * fourth child of <code><body></code>, the tree address returned would be:\r
* [1, 3, 2]\r
*\r
* The tree address cannot be used for finding back the DOM tree node once\r
* @returns {CKEDITOR.dom.document} The document.\r
* @example\r
* var element = CKEDITOR.document.getById( 'example' );\r
- * alert( <b>element.getDocument().equals( CKEDITOR.document )</b> ); // "true"\r
+ * alert( <strong>element.getDocument().equals( CKEDITOR.document )</strong> ); // "true"\r
*/\r
getDocument : function()\r
{\r
* @returns {CKEDITOR.dom.node} The next node or null if not available.\r
* @example\r
* var element = CKEDITOR.dom.element.createFromHtml( '<div><b>Example</b> <i>next</i></div>' );\r
- * var first = <b>element.getFirst().getNext()</b>;\r
+ * var first = <strong>element.getFirst().getNext()</strong>;\r
* alert( first.getName() ); // "i"\r
*/\r
getNext : function( evaluator )\r
* @returns {CKEDITOR.dom.element} The parent element.\r
* @example\r
* var node = editor.document.getBody().getFirst();\r
- * var parent = node.<b>getParent()</b>;\r
+ * var parent = node.<strong>getParent()</strong>;\r
* alert( node.getName() ); // "body"\r
*/\r
getParent : function()\r
},\r
\r
/**\r
- * Gets the closest ancestor node of this node, specified by its node name.\r
- * @param {String} name The node name of the ancestor node to search.\r
+ * Gets the closest ancestor node of this node, specified by its name.\r
+ * @param {String} reference The name of the ancestor node to search or\r
+ * an object with the node names to search for.\r
* @param {Boolean} [includeSelf] Whether to include the current\r
- * node in the search.\r
+ * node in the search.\r
* @returns {CKEDITOR.dom.node} The located ancestor node or null if not found.\r
+ * @since 3.6.1\r
* @example\r
- * // Suppose we have the following HTML:\r
+ * // Suppose we have the following HTML structure:\r
* // <div id="outer"><div id="inner"><p><b>Some text</b></p></div></div>\r
* // If node == <b>\r
* ascendant = node.getAscendant( 'div' ); // ascendant == <div id="inner">\r
* ascendant = node.getAscendant( 'b' ); // ascendant == null\r
* ascendant = node.getAscendant( 'b', true ); // ascendant == <b>\r
+ * ascendant = node.getAscendant( { div: 1, p: 1} ); // Searches for the first 'div' or 'p': ascendant == <div id="inner">\r
*/\r
- getAscendant : function( name, includeSelf )\r
+ getAscendant : function( reference, includeSelf )\r
{\r
- var $ = this.$;\r
+ var $ = this.$,\r
+ name;\r
\r
if ( !includeSelf )\r
$ = $.parentNode;\r
\r
while ( $ )\r
{\r
- if ( $.nodeName && $.nodeName.toLowerCase() == name )\r
+ if ( $.nodeName && ( name = $.nodeName.toLowerCase(), ( typeof reference == 'string' ? name == reference : name in reference ) ) )\r
return new CKEDITOR.dom.node( $ );\r
\r
$ = $.parentNode;\r
* tags.\r
* @example\r
* var element = CKEDITOR.dom.element.getById( 'MyElement' );\r
- * <b>element.remove()</b>;\r
+ * <strong>element.remove()</strong>;\r
*/\r
remove : function( preserveChildren )\r
{\r
},\r
\r
/**\r
- * Checks is this node is read-only (should not be changed). It\r
- * additionaly returns the element, if any, which defines the read-only\r
- * state of this node. It may be the node itself or any of its parent\r
+ * Checks if this node is read-only (should not be changed). Additionally\r
+ * it returns the element that defines the read-only state of this node\r
+ * (if present). It may be the node itself or any of its parent\r
* nodes.\r
* @returns {CKEDITOR.dom.element|Boolean} An element containing\r
* read-only attributes or "false" if none is found.\r
Got questions, comments, patches, etc.? Contact Jason Woofenden