8
0
Просмотр исходного кода

Changed: Introduced view.MatcherPattern.

Szymon Cofalik 8 лет назад
Родитель
Сommit
9d22960d23
1 измененных файлов с 103 добавлено и 46 удалено
  1. 103 46
      packages/ckeditor5-engine/src/view/matcher.js

+ 103 - 46
packages/ckeditor5-engine/src/view/matcher.js

@@ -27,63 +27,18 @@ export default class Matcher {
 	/**
 	 * Adds pattern or patterns to matcher instance.
 	 *
-	 * Example patterns matching element's name:
-	 *
 	 *		// String.
 	 *		matcher.add( 'div' );
-	 *		matcher.add( { name: 'div' } );
 	 *
 	 *		// Regular expression.
 	 *		matcher.add( /^\w/ );
-	 *		matcher.add( { name: /^\w/ } );
-	 *
-	 * Example pattern matching element's attributes:
-	 *
-	 *		matcher.add( {
-	 *			attribute: {
-	 *				title: 'foobar',	// Attribute title should equal 'foobar'.
-	 *				foo: /^\w+/,		// Attribute foo should match /^\w+/ regexp.
-	 *				bar: true			// Attribute bar should be set (can be empty).
-	 *			}
-	 *		} );
-	 *
-	 * Example patterns matching element's classes:
 	 *
 	 *		// Single class.
 	 *		matcher.add( {
 	 *			class: 'foobar'
 	 *		} );
 	 *
-	 *		// Single class using regular expression.
-	 *		matcher.add( {
-	 *			class: /foo.../
-	 *		} );
-	 *
-	 *		// Multiple classes to match.
-	 *		matcher.add( {
-	 *			class: [ 'baz', 'bar', /foo.../ ]
-	 *		} ):
-	 *
-	 * Example pattern matching element's styles:
-	 *
-	 *		matcher.add( {
-	 *			style: {
-	 *				position: 'absolute',
-	 *				color: /^\w*blue$/
-	 *			}
-	 *		} );
-	 *
-	 * Example function pattern:
-	 *
-	 *		matcher.add( ( element ) => {
-	 *			// Result of this function will be included in `match`
-	 *			// property of the object returned from matcher.match() call.
-	 *			if ( element.name === 'div' && element.childCount > 0 ) {
-	 *				return { name: true };
-	 *			}
-	 *
-	 *			return null;
-	 *		} );
+	 * See {@link ~MatcherPattern} for more examples.
 	 *
 	 * Multiple patterns can be added in one call:
 	 *
@@ -383,3 +338,105 @@ function matchStyles( patterns, element ) {
 
 	return match;
 }
+
+/**
+ * An entity that is a valid pattern recognized by a matcher. `MatcherPattern` is used by {@link ~Matcher} to recognize
+ * if a view element fits in a group of view elements described by the pattern.
+ *
+ * `MatcherPattern` can be given as a `String`, a `RegExp`, an `Object` or a `Function`.
+ *
+ * If `MatcherPattern` is given as a `String` or `RegExp`, it will match any view element that has a matching name:
+ *
+ *		// Match any element with name equal to 'div'.
+ *		const pattern = 'div';
+ *
+ *		// Match any element which name starts on 'p'.
+ *		const pattern = /^p/;
+ *
+ * If `MatcherPattern` is given as an `Object`, all the object's properties will be matched with view element properties.
+ *
+ *		// Match view element's name.
+ *		const pattern = { name: /^p/ };
+ *
+ *		// Match view element which has matching attributes.
+ *		const pattern = {
+ *			attribute: {
+ *				title: 'foobar',	// Attribute title should equal 'foobar'.
+ *				foo: /^\w+/,		// Attribute foo should match /^\w+/ regexp.
+ *				bar: true			// Attribute bar should be set (can be empty).
+ *			}
+ *		};
+ *
+ *		// Match view element which has given class.
+ *		const pattern = {
+ *			class: 'foobar'
+ *		};
+ *
+ *		// Match view element class using regular expression.
+ *		const pattern = {
+ *			class: /foo.../
+ *		};
+ *
+ *		// Multiple classes to match.
+ *		const pattern = {
+ *			class: [ 'baz', 'bar', /foo.../ ]
+ *		}:
+ *
+ *		// Match view element which has given styles.
+ *		const pattern = {
+ *			style: {
+ *				position: 'absolute',
+ *				color: /^\w*blue$/
+ *			}
+ *		};
+ *
+ *		// Pattern with multiple properties.
+ *		const pattern = {
+ *			name: 'span',
+ *			style: {
+ *				'font-weight': 'bold'
+ *			},
+ *			class: 'highlighted'
+ *		};
+ *
+ * If `MatcherPattern` is given as a `Function`, the function takes a view element as a first and only parameter and
+ * the function should decide whether that element matches. If so, it should return what part of the view element has been matched.
+ * Otherwise, the function should return `null`. The returned result will be included in `match` property of the object
+ * returned by {@link ~Matcher#match} call.
+ *
+ *		// Match an empty <div> element.
+ *		const pattern = element => {
+ *			if ( element.name == 'div' && element.childCount > 0 ) {
+ *				// Return which part of the element was matched.
+ *				return { name: true };
+ *			}
+ *
+ *			return null;
+ *		};
+ *
+ *		// Match a <p> element with big font ("heading-like" element).
+ *		const pattern = element => {
+ *			if ( element.name == 'p' ) {
+ *				const fontSize = element.getStyle( 'font-size' );
+ *				const size = fontSize.match( /(\d+)/px );
+ *
+ *				if ( size && Number( size[ 1 ] ) > 26 ) {
+ *					return { name: true, attribute: [ 'font-size' ] };
+ *				}
+ *			}
+ *
+ *			return null;
+ *		};
+ *
+ * `MatcherPattern` is defined in a way that it is a superset of {@link module:engine/view/elementdefinition~ElementDefinition},
+ * that is, every `ElementDefinition` also can be used as a `MatcherPattern`.
+ *
+ * @typedef {String|RegExp|Object|Function} module:engine/view/matcher~MatcherPattern
+ *
+ * @property {String|RegExp} [name] View element name to match.
+ * @property {String|RegExp|Array.<String|RegExp>} [class] View element's class name(s) to match.
+ * @property {Object} [style] Object with key-value pairs representing styles to match.
+ * Each object key represents style name. Value can be given as `String` or `RegExp`.
+ * @property {Object} [attribute] Object with key-value pairs representing attributes to match.
+ * Each object key represents attribute name. Value can be given as `String` or `RegExp`.
+ */