MatcherPattern (engine/view)

An entity that is a valid pattern recognized by a matcher. MatcherPattern is used by 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 = {
    attributes: {
        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 = {
    classes: 'foobar'
};

// Match view element class using regular expression.
const pattern = {
    classes: /foo.../
};

// Multiple classes to match.
const pattern = {
    classes: [ 'baz', 'bar', /foo.../ ]
};

// Match view element which has given styles.
const pattern = {
    styles: {
        position: 'absolute',
        color: /^\w*blue$/
    }
};

// Pattern with multiple properties.
const pattern = {
    name: 'span',
    styles: {
        'font-weight': 'bold'
    },
    classes: '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 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 ElementDefinition, that is, every ElementDefinition also can be used as a MatcherPattern.