Class StylesProcessor

Creates StylesProcessor instance.

Returns a normalized version of a style property.

const styles = {
	margin: { top: '1px', right: '1px', bottom: '1px', left: '1px; },
	background: { color: '#f00' }
};

stylesProcessor.getNormalized( 'background' );
// will return: { color: '#f00' }

stylesProcessor.getNormalized( 'margin-top' );
// will return: '1px'
Copy

Note: In some cases extracting single value requires defining an extractor callback #setExtractor.

Returns a reduced form of style property form normalized object.

For default margin reducer, the below code:

stylesProcessor.getReducedForm( 'margin', {
	margin: { top: '1px', right: '1px', bottom: '2px', left: '1px; }
} );
Copy

will return:

[
	[ 'margin', '1px 1px 2px' ]
]
Copy

because it might be represented as a shorthand 'margin' value. However if one of margin long hand values is missing it should return:

[
	[ 'margin-top', '1px' ],
	[ 'margin-right', '1px' ],
	[ 'margin-bottom', '2px' ]
	// the 'left' value is missing - cannot use 'margin' shorthand.
]
Copy

Note: To define reducer callbacks use #setReducer.

Returns related style names.

stylesProcessor.getRelatedStyles( 'margin' );
// will return: [ 'margin-top', 'margin-right', 'margin-bottom', 'margin-left' ];

stylesProcessor.getRelatedStyles( 'margin-top' );
// will return: [ 'margin' ];
Copy

Note: To define new style relations load an existing style processor or use module:engine/view/stylesmap~StylesProcessor#setStyleRelation StylesProcessor.setStyleRelation().

Return all style properties. Also expand shorthand properties (e.g. margin, background) if respective extractor is available.

Adds a extractor callback for a style property.

Most normalized style values are stored as one level objects. It is assumed that 'margin-top' style will be stored as:

const styles = {
	margin: {
		top: 'value'
	}
}
Copy

However, some styles can have conflicting notations and thus it might be harder to extract a style value from shorthand. For instance the 'border-top-style' can be defined using 'border-top:solid', 'border-style:solid none none none' or by 'border:solid' shorthands. The default border styles processors stores styles as:

const styles = {
	border: {
		style: {
			top: 'solid'
		}
	}
}
Copy

as it is better to modify border style independently from other values. On the other part the output of the border might be desired as border-top, border-left, etc notation.

In the above example an extractor should return a side border value that combines style, color and width:

styleProcessor.setExtractor( 'border-top', styles => {
	return {
		color: styles.border.color.top,
		style: styles.border.style.top,
		width: styles.border.width.top
	}
} );
Copy

Adds a normalizer method for a style property.

A normalizer returns describing how the value should be normalized.

For instance 'margin' style is a shorthand for four margin values:

• 'margin-top'
• 'margin-right'
• 'margin-bottom'
• 'margin-left'

and can be written in various ways if some values are equal to others. For instance 'margin: 1px 2em;' is a shorthand for 'margin-top: 1px;margin-right: 2em;margin-bottom: 1px;margin-left: 2em'.

A normalizer should parse various margin notations as a single object:

const styles = {
	margin: {
		top: '1px',
		right: '2em',
		bottom: '1px',
		left: '2em'
	}
};
Copy

Thus a normalizer for 'margin' style should return an object defining style path and value to store:

const returnValue = {
	path: 'margin',
	value: {
		top: '1px',
		right: '2em',
		bottom: '1px',
		left: '2em'
	}
};
Copy

Additionally to fully support all margin notations there should be also defined 4 normalizers for longhand margin notations. Below is an example for 'margin-top' style property normalizer:

stylesProcessor.setNormalizer( 'margin-top', valueString => {
	return {
		path: 'margin.top',
		value: valueString
	}
} );
Copy

Adds a reducer callback for a style property.

Reducer returns a minimal notation for given style name. For longhand properties it is not required to write a reducer as by default the direct value from style path is taken.

For shorthand styles a reducer should return minimal style notation either by returning single name-value tuple or multiple tuples if a shorthand cannot be used. For instance for a margin shorthand a reducer might return:

const marginShortHandTuple = [
	[ 'margin', '1px 1px 2px' ]
];
Copy

or a longhand tuples for defined values:

// Considering margin.bottom and margin.left are undefined.
const marginLonghandsTuples = [
	[ 'margin-top', '1px' ],
	[ 'margin-right', '1px' ]
];
Copy

A reducer obtains a normalized style value:

// Simplified reducer that always outputs 4 values which are always present:
stylesProcessor.setReducer( 'margin', margin => {
	return [
		[ 'margin', `${ margin.top } ${ margin.right } ${ margin.bottom } ${ margin.left }` ]
	]
} );
Copy

Defines a style shorthand relation to other style notations.

stylesProcessor.setStyleRelation( 'margin', [
	'margin-top',
	'margin-right',
	'margin-bottom',
	'margin-left'
] );
Copy

This enables expanding of style names for shorthands. For instance, if defined, module:engine/conversion/viewconsumable~ViewConsumable view consumable items are automatically created for long-hand margin style notation alongside the 'margin' item.

This means that when an element being converted has a style margin, a converter for margin-left will work just fine since the view consumable will contain a consumable margin-left item (thanks to the relation) and element.getStyle( 'margin-left' ) will work as well assuming that the style processor was correctly configured. However, once margin-left is consumed, margin will not be consumable anymore.

Parse style string value to a normalized object and appends it to styles object.

const styles = {};

stylesProcessor.toNormalizedForm( 'margin', '1px', styles );

// styles will consist: { margin: { top: '1px', right: '1px', bottom: '1px', left: '1px; } }
Copy

Note: To define normalizer callbacks use #setNormalizer.