8
0
Piotrek Koszuliński 6 лет назад
Родитель
Сommit
5fd67cf719

+ 8 - 6
packages/ckeditor5-engine/src/model/documentfragment.js

@@ -116,14 +116,16 @@ export default class DocumentFragment {
 	}
 
 	/**
-	 * Method verifies if the checked object belongs to a given a type. Type's name might be prefixed with a `model:` string,
-	 * for example `model:documentFragment`. Type is a string which usually equal to a name of the class written in camelCase convention.
-	 * If the object is a class instance, which has a parent class with `is()` method, then type verification returns `true`
-	 * for any type match for an entire child-parent chain.
+	 * Checks whether this object is of the given type.
 	 *
-	 * Acceptable type for this class is `documentFragment` and its prefixed version.
+	 *		docFrag.is( 'documentFragment' ); // -> true
+	 *		docFrag.is( 'model:documentFragment' ); // -> true
 	 *
-	 * See also: {@link module:engine/model/node~Node#is `Node#is()`}.
+	 *		docFrag.is( 'view:documentFragment' ); // -> false
+	 *		docFrag.is( 'element' ); // -> false
+	 *		docFrag.is( 'node' ); // -> false
+	 *
+	 * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
 	 *
 	 * @param {String} type
 	 * @returns {Boolean}

+ 9 - 16
packages/ckeditor5-engine/src/model/documentselection.js

@@ -367,25 +367,18 @@ export default class DocumentSelection {
 	}
 
 	/**
-	 * Method verifies if the checked object belongs to a given a type. Type's name might be prefixed with a `model:` string,
-	 * for example `model:selection`. Type is a string which usually equal to a name of the class written in camelCase convention.
-	 * If the object is a class instance, which has a parent class with `is()` method, then type verification returns `true`
-	 * for any type match for an entire child-parent chain.
+	 * Checks whether this object is of the given type.
 	 *
-	 *		const selection = new DocumentSelection( ... );
+	 *		selection.is( 'selection' ); // -> true
+	 *		selection.is( 'documentSelection' ); // -> true
+	 *		selection.is( 'model:selection' ); // -> true
+	 *		selection.is( 'model:documentSelection' ); // -> true
 	 *
-	 *		selection.is( 'selection' ); // true
-	 *		selection.is( 'model:selection' ); // true
-	 *		selection.is( 'documentSelection' ); // true
-	 *		selection.is( 'model:documentSelection' ); // true
-	 *		selection.is( 'view:selection' ); // false
-	 *		selection.is( 'node' ); // false
-	 *		selection.is( 'model:node' ); // false
-	 *		selection.is( 'element' ); // false
+	 *		selection.is( 'view:selection' ); // -> false
+	 *		selection.is( 'element' ); // -> false
+	 *		selection.is( 'node' ); // -> false
 	 *
-	 * Acceptable type for this class is `selection` and its prefixed version.
-	 *
-	 * See also: {@link module:engine/model/node~Node#is `Node#is()`}.
+	 * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
 	 *
 	 * @param {String} type
 	 * @returns {Boolean}

+ 13 - 20
packages/ckeditor5-engine/src/model/element.js

@@ -89,31 +89,24 @@ export default class Element extends Node {
 	}
 
 	/**
-	 * Method verifies if the checked object belongs to a given a type. Type's name might be prefixed with a `model:` string,
-	 * for example `model:element`. Type is a string which usually equal to a name of the class written in camelCase convention.
-	 * If the object is a class instance, which has a parent class with `is()` method, then type verification returns `true`
-	 * for any type match for an entire child-parent chain.
+	 * Checks whether this object is of the given.
 	 *
-	 * There is also possibility to check element's {@link #name} rather than just type. Name might be provided as second attribute
-	 * or might replace the type.
+	 *		element.is( 'element' ); // -> true
+	 *		element.is( 'node' ); // -> true
+	 *		element.is( 'model:element' ); // -> true
+	 *		element.is( 'model:documentSelection' ); // -> true
 	 *
-	 *		obj.name; // 'listItem'
-	 *		obj instanceof Element; // true
+	 *		element.is( 'view:element' ); // -> false
+	 *		element.is( 'documentSelection' ); // -> false
 	 *
-	 *		obj.is( 'element' ); // true
-	 *		obj.is( 'model:element' ); // true
-	 *		obj.is( 'listItem' ); // true
-	 *		obj.is( 'model:listItem' ); // true
-	 *		obj.is( 'element', 'listItem' ); // true
-	 *		obj.is( 'model:element', 'listItem' ); // true
-	 *		obj.is( 'text' ); // false
-	 *		obj.is( 'model:text' ); // false
-	 *		obj.is( 'view:element' ); // false
-	 *		obj.is( 'element', 'image' ); // false
+	 * Assuming that the object being checked is an element, you can also check its
+	 * {@link module:engine/model/element~Element#name name}:
 	 *
-	 * Acceptable type for this class is `element` and its prefixed version, element's name or combination of both arguments.
+	 *		element.is( 'image' ); // -> true if this is an <image> element
+	 *		element.is( 'element', 'image' ); // -> same as above
+	 *		text.is( 'image' ); -> false
 	 *
-	 * See also: {@link module:engine/model/node~Node#is `Node#is()`}.
+	 * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
 	 *
 	 * @param {String} type Type to check when `name` parameter is present.
 	 * Otherwise, it acts like the `name` parameter.

+ 47 - 31
packages/ckeditor5-engine/src/model/node.js

@@ -396,6 +396,53 @@ export default class Node {
 		return json;
 	}
 
+	/**
+	 * Checks whether this object is of the given type.
+	 *
+	 * This method is useful when processing model objects that are of unknown type. For example, a function
+	 * may return a {@link module:engine/model/documentfragment~DocumentFragment} or a {@link module:engine/model/node~Node}
+	 * that can be either a text node or an element. This method can be used to check what kind of object is returned.
+	 *
+	 *		someObject.is( 'element' ); // -> true if this is an element
+	 *		someObject.is( 'node' ); // -> true if this is a node (a text node or an element)
+	 *		someObject.is( 'documentFragment' ); // -> true if this is a document fragment
+	 *
+	 * Since this method is also available on a range of view objects, you can prefix the type of the object with
+	 * `model:` or `view:` to check, for example, if this is the model's or view's element:
+	 *
+	 *		modelElement.is( 'model:element' ); // -> true
+	 *		modelElement.is( 'view:element' ); // -> false
+	 *
+	 * By using this method it is also possible to check a name of an element:
+	 *
+	 *		imageElement.is( 'image' ); // -> true
+	 *		imageElement.is( 'element', 'image' ); // -> same as above
+	 *		imageElement.is( 'model:element', 'image' ); // -> same as above, but more precise
+	 *
+	 * The list of model objects which implement the `is()` method:
+	 *
+	 * * {@link module:engine/model/node~Node#is `Node#is()`}
+	 * * {@link module:engine/model/text~Text#is `Text#is()`}
+	 * * {@link module:engine/model/element~Element#is `Element#is()`}
+	 * * {@link module:engine/model/rootelement~RootElement#is `RootElement#is()`}
+	 * * {@link module:engine/model/position~Position#is `Position#is()`}
+	 * * {@link module:engine/model/liveposition~LivePosition#is `LivePosition#is()`}
+	 * * {@link module:engine/model/range~Range#is `Range#is()`}
+	 * * {@link module:engine/model/liverange~LiveRange#is `LiveRange#is()`}
+	 * * {@link module:engine/model/documentfragment~DocumentFragment#is `DocumentFragment#is()`}
+	 * * {@link module:engine/model/selection~Selection#is `Selection#is()`}
+	 * * {@link module:engine/model/documentselection~DocumentSelection#is `DocumentSelection#is()`}
+	 * * {@link module:engine/model/markercollection~Marker#is `Marker#is()`}
+	 * * {@link module:engine/model/textproxy~TextProxy#is `TextProxy#is()`}
+	 *
+	 * @method #is
+	 * @param {String} type
+	 * @returns {Boolean}
+	 */
+	is( type ) {
+		return type == 'node' || type == 'model:node';
+	}
+
 	/**
 	 * Creates a copy of this node, that is a node with exactly same attributes, and returns it.
 	 *
@@ -460,37 +507,6 @@ export default class Node {
 	_clearAttributes() {
 		this._attrs.clear();
 	}
-
-	/**
-	 * Checks whether given model tree object is of given type.
-	 *
-	 * This method is useful when processing model tree objects that are of unknown type. For example, a function
-	 * may return {@link module:engine/model/documentfragment~DocumentFragment} or {@link module:engine/model/node~Node}
-	 * that can be either text node or element. This method can be used to check what kind of object is returned.
-	 * All checked types might be prefixed with `model:` to narrow search exclusively to model's objects.
-	 * That should prevent of situation where `view:node` accidentally might be considered as `model:node`.
-	 * Types are defined as name of the class written in [camelCase](https://en.wikipedia.org/wiki/Camel_case) notation.
-	 * E.g. class `LiveRange` will get type `liveRange`.
-	 *
-	 * There is more classes in model which follows similar naming convention. Check corresponding elements documentation for more details.
-	 *
-	 *		obj.is( 'node' ); // true for any node, false for document fragment and text fragment
-	 *		obj.is( 'documentFragment' ); // true for document fragment, false for any node
-	 *		obj.is( 'element' ); // true for any element, false for text node or document fragment
-	 *		obj.is( 'element', 'paragraph' ); // true only for element which name is 'paragraph'
-	 *		obj.is( 'paragraph' ); // shortcut for obj.is( 'element', 'paragraph' )
-	 *		obj.is( 'text' ); // true for text node, false for element and document fragment
-	 *		obj.is( 'textProxy' ); // true for text proxy object
-	 *
-	 * Acceptable types for this class is `node` and its prefixed version.
-	 *
-	 * @method #is
-	 * @param {String} type
-	 * @returns {Boolean}
-	 */
-	is( type ) {
-		return type == 'node' || type == 'model:node';
-	}
 }
 
 /**