CKEditor Ecosystem Documentation
Search
⚠️ WarningNightly documentation ahead. Switch to the stable editor documentation.
Home/CKEditor 5/API
Class

StylesProcessor (engine/view)

@ckeditor/ckeditor5-engine/src/view/stylesmap

class
See source

Style processor is responsible for writing and reading a normalized styles object.

Filtering

Methods

  • constructor()

    private

    Creates StylesProcessor instance.

    See source

  • getNormalized( name, styles ) → *

    Returns a normalized version of a style property. const styles = { margin: { top: '1px', right: '1px', bottom: '1px', left: '1px; }, background: { color: '#f00' } };

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

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

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

    Parameters

    name : String

    Name of style property.

    styles : Object

    Object holding normalized styles.

    Returns

    *

  • getReducedForm( name, styles ) → Array.<PropertyDescriptor>

    Returns a reduced form of style property form normalized object.

    See source

    For default margin reducer, the below code:

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

    will return:

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

    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.
]

    Note: To define reducer callbacks use setReducer.

    Parameters

    name : String

    Name of style property.

    styles : Object

    Object holding normalized styles.

    Returns

    Array.<PropertyDescriptor>

  • getRelatedStyles( name ) → Array.<String>

    Returns related style names.

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

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

    Note: To define new style relations load an existing style processor or use StylesProcessor.setStyleRelation().

    Parameters

    name : String

    Returns

    Array.<String>

  • getStyleNames( styles ) → Array.<String>

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

    See source

    Parameters

    styles : Object

    Object holding normalized styles.

    Returns

    Array.<String>

  • setExtractor( name, callbackOrPath )

    Adds a extractor callback for a style property.

    See source

    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'
	}
}

    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'
		}
	}
}

    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 a reducer 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
	}
} );

    Parameters

    name : String
    callbackOrPath : function | String

    Callback that return a requested value or path string for single values.

  • setNormalizer( name, callback )

    Adds a normalizer method for a style property.

    See source

    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'
	}
};

    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'
	}
};

    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
	}
} );

    Parameters

    name : String
    callback : function

  • setReducer( name, callback )

    Adds a reducer callback for a style property.

    See source

    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' ]
];

    or a longhand tuples for defined values:

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

    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 }` ]
	]
} );

    Parameters

    name : String
    callback : function

  • setStyleRelation( shorthandName, styleNames )

    Defines a style shorthand relation to other style notations.

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

    This enables expanding of style names for shorthands. For instance, if defined, 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.

    Parameters

    shorthandName : String
    styleNames : Array.<String>

  • toNormalizedForm( name, propertyValue, styles )

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

    See source
    const styles = {};

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

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

    Note: To define normalizer callbacks use setNormalizer.

    Parameters

    name : String

    Name of style property.

    propertyValue : String

    Value of style property.

    styles : Object

    Object holding normalized styles.

  • _mapStyleNames( name, styleNames )

    private

    Set two-way binding of style names.

    See source

    Parameters

    name : String
    styleNames : Array.<String>