# StylesProcessor

class

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L640)

<a id="properties">

## Properties

<a id="member-_consumables">

### `_consumables: Map<string, Array<string>>` _(private)_

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L644)

<a id="member-_extractors">

### `_extractors: Map<string, StylesExtractor>` _(private)_

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L642)

<a id="member-_normalizers">

### `_normalizers: Map<string, StylesNormalizer>` _(private)_

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L641)

<a id="member-_reducers">

### `_reducers: Map<string, StylesReducer>` _(private)_

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L643)

<a id="methods">

## Methods

<a id="function-constructor">

### `constructor()` _(internal)_

Creates StylesProcessor instance.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L651)

<a id="function-getNormalized">

### `getNormalized( name, styles ) → StyleValue | undefined`

Returns a normalized version of a style property.

```typescript
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`](#function-setExtractor).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L714)

#### Parameters

* `name: string | undefined`

  Name of style property.

* `styles: Styles`

  Object holding normalized styles.

#### Returns

* `StyleValue | undefined`

<a id="function-getReducedForm">

### `getReducedForm( name, styles ) → Array<StylePropertyDescriptor>`

Returns a reduced form of style property form normalized object.

For default margin reducer, the below code:

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

will return:

```typescript
[
	[ '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:

```typescript
[
	[ '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`](#function-setReducer).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L775)

#### Parameters

* `name: string`

  Name of style property.

* `styles: Styles`

#### Returns

* `Array<StylePropertyDescriptor>`

<a id="function-getRelatedStyles">

### `getRelatedStyles( name ) → Array<string>`

Returns related style names.

```typescript
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()`](#function-setStyleRelation).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L832)

#### Parameters

* `name: string`

#### Returns

* `Array<string>`

<a id="function-getStyleNames">

### `getStyleNames( styles ) → Array<string>`

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L797)

#### Parameters

* `styles: Styles`

  Object holding normalized styles.

#### Returns

* `Array<string>`

<a id="function-setExtractor">

### `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:

```typescript
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:

```typescript
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:

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L938)

#### Parameters

* `name: string`

* `callbackOrPath: StylesExtractor`

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

#### Returns

* `void`

<a id="function-setNormalizer">

### `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:

```typescript
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:

```typescript
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:

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L890)

#### Parameters

* `name: string`
* `callback: StylesNormalizer`

#### Returns

* `void`

<a id="function-setReducer">

### `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:

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

or a longhand tuples for defined values:

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

A reducer obtains a normalized style value:

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

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L978)

#### Parameters

* `name: string`
* `callback: StylesReducer`

#### Returns

* `void`

<a id="function-setStyleRelation">

### `setStyleRelation( shorthandName, styleNames ) → void`

Defines a style shorthand relation to other style notations.

```typescript
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](module_engine_conversion_viewconsumable-ViewConsumable.md) 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.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L1003)

#### Parameters

* `shorthandName: string`
* `styleNames: Array<string>`

#### Returns

* `void`

<a id="function-toNormalizedForm">

### `toNormalizedForm( name, propertyValue, styles ) → void`

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

```typescript
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`](#function-setNormalizer).

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L675)

#### Parameters

* `name: string`

  Name of style property.

* `propertyValue: StyleValue`

  Value of style property.

* `styles: Styles`

  Object holding normalized styles.

#### Returns

* `void`

<a id="function-_mapStyleNames">

### `_mapStyleNames( name, styleNames ) → void` _(private)_

Set two-way binding of style names.

[See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/view/stylesmap.ts#L1014)

#### Parameters

* `name: string`
* `styleNames: Array<string>`

#### Returns

* `void`

---

Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)