Class

StylesProcessor (engine/view)

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

class

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

Filtering

Properties

Methods

  • internal

    constructor()

    Creates StylesProcessor instance.

  • getNormalized( name, styles ) → StyleValue

    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'
    

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

    Parameters

    name : undefined | string

    Name of style property.

    styles : Styles

    Object holding normalized styles.

    Returns

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

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

    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 : Styles

    Returns

    Array<PropertyDescriptor>
  • getRelatedStyles( name ) → Array<string>

    Returns related style names.

    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.

    Parameters

    styles : Styles

    Object holding normalized styles.

    Returns

    Array<string>
  • setExtractor( name, callbackOrPath ) → void

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

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

    Parameters

    name : string
    callbackOrPath : Extractor

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

    Returns

    void
  • setNormalizer( name, callback ) → void

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

    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 : Normalizer

    Returns

    void
  • setReducer( name, callback ) → void

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

    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 : Reducer

    Returns

    void
  • setStyleRelation( shorthandName, styleNames ) → void

    Defines a style shorthand relation to other style notations.

    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>

    Returns

    void
  • toNormalizedForm( name, propertyValue, styles ) → void

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

    Note: To define normalizer callbacks use setNormalizer.

    Parameters

    name : string

    Name of style property.

    propertyValue : StyleValue

    Value of style property.

    styles : Styles

    Object holding normalized styles.

    Returns

    void
  • private

    _mapStyleNames( name, styleNames ) → void

    Set two-way binding of style names.

    Parameters

    name : string
    styleNames : Array<string>

    Returns

    void