# DataController class Controller for the data pipeline. The data pipeline controls how data is retrieved from the document and set inside it. Hence, the controller features two methods which allow to [get](#function-get) and [set](#function-set) data of the [model](#member-model) using the given: * [data processor](module_engine_dataprocessor_dataprocessor-DataProcessor.md), * downcast converters, * upcast converters. An instance of the data controller is always available in the [`editor.data`](module_core_editor_editor-Editor.md#member-data) property: ```typescript editor.data.get( { rootName: 'customRoot' } ); // -> '

Hello!

' ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L70) ## Properties ### `downcastDispatcher: DowncastDispatcher` _(readonly)_ Downcast dispatcher used by the [get method](#function-get). Downcast converters should be attached to it. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L86) ### `htmlProcessor: HtmlDataProcessor` _(readonly)_ Data processor used specifically for HTML conversion. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L106) ### `mapper: Mapper` _(readonly)_ Mapper used for the conversion. It has no permanent bindings, because these are created while getting data and are cleared directly after the data are converted. However, the mapper is defined as a class property, because it needs to be passed to the `DowncastDispatcher` as a conversion API. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L81) ### `model: Model` _(readonly)_ Data model. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L74) ### `processor: DataProcessor` Data processor used during the conversion. Same instance as [`htmlProcessor`](#member-htmlProcessor) by default. Can be replaced at run time to handle different format, e.g. XML or Markdown. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L112) ### `stylesProcessor: StylesProcessor` _(readonly)_ Styles processor used during the conversion. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L101) ### `upcastDispatcher: UpcastDispatcher` _(readonly)_ Upcast dispatcher used by the [set method](#function-set). Upcast converters should be attached to it. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L91) ### `viewDocument: ViewDocument` _(readonly)_ The view document used by the data controller. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L96) ### `_viewWriter: ViewDowncastWriter` _(private)_ The view downcast writer just for data conversion purposes, i.e. to modify the [`viewDocument`](#member-viewDocument). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L118) ## Methods ### `constructor( model, stylesProcessor )` Creates a data controller instance. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L126) #### Parameters * `model: Model` Data model. * `stylesProcessor: StylesProcessor` The styles processor instance. ### `addStyleProcessorRules( callback ) → void` Adds the style processor normalization rules. You can implement your own rules as well as use one of the available processor rules: * background: [`addBackgroundStylesRules`](module_engine_view_styles_background.md#function-addBackgroundStylesRules) * border: [`addBorderStylesRules`](module_engine_view_styles_border.md#function-addBorderStylesRules) * margin: [`addMarginStylesRules`](module_engine_view_styles_margin.md#function-addMarginStylesRules) * padding: [`addPaddingStylesRules`](module_engine_view_styles_padding.md#function-addPaddingStylesRules) [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L525) #### Parameters * `callback: ( stylesProcessor: StylesProcessor ) => void` #### Returns * `void` ### `delegate( events ) → EmitterMixinDelegateChain` _(inherited)_ Delegates selected events to another [`Emitter`](module_utils_emittermixin-Emitter.md). For instance: ```typescript emitterA.delegate( 'eventX' ).to( emitterB ); emitterA.delegate( 'eventX', 'eventY' ).to( emitterC ); ``` then `eventX` is delegated (fired by) `emitterB` and `emitterC` along with `data`: ```typescript emitterA.fire( 'eventX', data ); ``` and `eventY` is delegated (fired by) `emitterC` along with `data`: ```typescript emitterA.fire( 'eventY', data ); ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L539) #### Parameters * `events: Array` Event names that will be delegated to another emitter. #### Returns * `EmitterMixinDelegateChain` ### `destroy() → void` Removes all event listeners set by the DataController. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L552) #### Returns * `void` ### `fire( eventOrInfo, args ) → GetEventInfo[ 'return' ]` _(inherited)_ Fires an event, executing all callbacks registered for it. The first parameter passed to callbacks is an [`EventInfo`](module_utils_eventinfo-EventInfo.md) object, followed by the optional `args` provided in the `fire()` method call. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L512) #### Type parameters * `TEvent: extends BaseEvent` The type describing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md). #### Parameters * `eventOrInfo: GetNameOrEventInfo` The name of the event or `EventInfo` object if event is delegated. * `args: TEvent[ 'args' ]` Additional arguments to be passed to the callbacks. #### Returns * `GetEventInfo[ 'return' ]` By default the method returns `undefined`. However, the return value can be changed by listeners through modification of the [`evt.return`](module_utils_eventinfo-EventInfo.md#member-return)'s property (the event info is the first param of every callback). ### `get( options = { options.rootName?, options.trim?, options.[key: string] } ) → string` Returns the model's data converted by downcast dispatchers attached to [`downcastDispatcher`](#member-downcastDispatcher) and formatted by the [data processor](#member-processor). A warning is logged when you try to retrieve data for a detached root, as most probably this is a mistake. A detached root should be treated like it is removed, and you should not save its data. Note, that the detached root data is always an empty string. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L193) #### Parameters * `options: object` Additional configuration for the retrieved data. `DataController` provides two optional properties: `rootName` and `trim`. Other properties of this object are specified by various editor features. Properties * `options.rootName?: string` Root name. Default 'main'. * `options.trim?: 'none' | 'empty'` Whether returned data should be trimmed. This option is set to `empty` by default, which means whenever editor content is considered empty, an empty string will be returned. To turn off trimming completely use `'none'`. In such cases the exact content will be returned (for example a `

 

` for an empty editor). * `options.[key: string]: unknown` Defaults to `{}` #### Returns * `string` Output data. #### Fires * [get](#event-get) ### `init( data ) → Promise` Sets the initial input data parsed by the [data processor](#member-processor) and converted by the [view-to-model converters](#member-upcastDispatcher). Initial data can be only set to a document whose [`version`](module_engine_model_document-ModelDocument.md#member-version) is equal 0. **Note** This method is [decorated](module_utils_observablemixin-Observable.md#function-decorate) which is used by e.g. collaborative editing plugin that syncs remote data on init. When data is passed as a string, it is initialized on the default `main` root: ```typescript dataController.init( '

Foo

' ); // Initializes data on the `main` root only, as no other is specified. ``` To initialize data on a different root or multiple roots at once, an object containing `rootName` - `data` pairs should be passed: ```typescript dataController.init( { main: '

Foo

', title: '

Bar

' } ); // Initializes data on both the `main` and `title` roots. ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L328) #### Parameters * `data: string | Record` Input data as a string or an object containing the `rootName` - `data` pairs to initialize data on multiple roots at once. #### Returns * `Promise` Promise that is resolved after the data is set on the editor. #### Fires * [init](#event-init) ### `listenTo( emitter, event, callback, options? ) → void` _(inherited)_ Registers a callback function to be executed when an event is fired in a specific (emitter) object. Events can be grouped in namespaces using `:`. When namespaced event is fired, it additionally fires all callbacks for that namespace. ```typescript // myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ). myEmitter.on( 'myGroup', genericCallback ); myEmitter.on( 'myGroup:myEvent', specificCallback ); // genericCallback is fired. myEmitter.fire( 'myGroup' ); // both genericCallback and specificCallback are fired. myEmitter.fire( 'myGroup:myEvent' ); // genericCallback is fired even though there are no callbacks for "foo". myEmitter.fire( 'myGroup:foo' ); ``` An event callback can [stop the event](module_utils_eventinfo-EventInfo.md#member-stop) and set the [return value](module_utils_eventinfo-EventInfo.md#member-return) of the [`fire`](#function-fire) method. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L475) #### Type parameters * `TEvent: extends BaseEvent` The type describing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md). #### Parameters * `emitter: Emitter` The object that fires the event. * `event: TEvent[ 'name' ]` The name of the event. * `callback: GetCallback` The function to be called on event. * `options?: GetCallbackOptions` Additional options. #### Returns * `void` ### `off( event, callback ) → void` _(inherited)_ Stops executing the callback on the given event. Shorthand for [`this.stopListening( this, event, callback )`](#function-stopListening:BASE_STOP). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L444) #### Parameters * `event: string` The name of the event. * `callback: Function` The function to stop being called. #### Returns * `void` ### `on( event, callback, options? ) → void` _(inherited)_ Registers a callback function to be executed when an event is fired. Shorthand for [`this.listenTo( this, event, callback, options )`](#function-listenTo:BASE_EMITTER) (it makes the emitter listen on itself). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L416) #### Type parameters * `TEvent: extends BaseEvent` The type descibing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md). #### Parameters * `event: TEvent[ 'name' ]` The name of the event. * `callback: GetCallback` The function to be called on event. * `options?: GetCallbackOptions` Additional options. #### Returns * `void` ### `once( event, callback, options? ) → void` _(inherited)_ Registers a callback function to be executed on the next time the event is fired only. This is similar to calling [`on`](#function-on) followed by [`off`](#function-off) in the callback. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L431) #### Type parameters * `TEvent: extends BaseEvent` The type descibing the event. See [`BaseEvent`](module_utils_emittermixin-BaseEvent.md). #### Parameters * `event: TEvent[ 'name' ]` The name of the event. * `callback: GetCallback` The function to be called on event. * `options?: GetCallbackOptions` Additional options. #### Returns * `void` ### `parse( data, context ) → ModelDocumentFragment` Returns the data parsed by the [data processor](#member-processor) and then converted by upcast converters attached to the [`upcastDispatcher`](#member-upcastDispatcher). **Note:** The default `context` value is `'$root'`, which only matches the generic root. When the editor uses a custom root [`modelElement`](module_core_editor_editorconfig-RootConfig.md#member-modelElement), pass the target [root element](module_engine_model_rootelement-ModelRootElement.md) (or its configured model element name) explicitly, otherwise the conversion result may be wrong. See the [Custom root elements](../framework/deep-dive/schema.md#custom-root-elements) section of the [Schema deep-dive](../framework/deep-dive/schema.md) guide for more details. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L477) #### Parameters * `data: string` Data to parse. * `context: ModelSchemaContextDefinition` Base context in which the view will be converted to the model. See: [`convert`](module_engine_conversion_upcastdispatcher-UpcastDispatcher.md#function-convert). Defaults to `'$root'` #### Returns * `ModelDocumentFragment` Parsed data. #### Related: * [DataController#set](#function-set) ### `registerRawContentMatcher( pattern ) → void` Registers a [`MatcherPattern`](module_engine_view_matcher-MatcherPattern.md) on an [htmlProcessor](#member-htmlProcessor) and a [processor](#member-processor) for view elements whose content should be treated as raw data and not processed during the conversion from DOM to view elements. The raw data can be later accessed by the [view element custom property](module_engine_view_element-ViewElement.md#function-getCustomProperty) `"$rawContent"`. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L540) #### Parameters * `pattern: MatcherPattern` Pattern matching all view elements whose content should be treated as a raw data. #### Returns * `void` ### `set( data, options = { options.batchType?, options.[key: string] } ) → void` Sets the input data parsed by the [data processor](#member-processor) and converted by the [view-to-model converters](#member-upcastDispatcher). This method can be used any time to replace existing editor data with the new one without clearing the [document history](module_engine_model_document-ModelDocument.md#member-history). This method also creates a batch with all the changes applied. If all you need is to parse data, use the [`parse`](#function-parse) method. When data is passed as a string it is set on the default `main` root: ```typescript dataController.set( '

Foo

' ); // Sets data on the `main` root, as no other is specified. ``` To set data on a different root or multiple roots at once, an object containing `rootName` - `data` pairs should be passed: ```typescript dataController.set( { main: '

Foo

', title: '

Bar

' } ); // Sets data on the `main` and `title` roots as specified. ``` To set the data with a preserved undo stack and add the change to the undo stack, set `{ isUndoable: true }` as a `batchType` option. ```typescript dataController.set( '

Foo

', { batchType: { isUndoable: true } } ); ``` [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L413) #### Parameters * `data: string | Record` Input data as a string or an object containing the `rootName` - `data` pairs to set data on multiple roots at once. * `options: object` Options for setting data. Properties * `options.batchType?: BatchType` The batch type that will be used to create a batch for the changes applied by this method. By default, the batch will be set as [not undoable](module_engine_model_batch-Batch.md#member-isUndoable) and the undo stack will be cleared after the new data is applied (all undo steps will be removed). If the batch type `isUndoable` flag is be set to `true`, the undo stack will be preserved instead and not cleared when new data is applied. * `options.[key: string]: unknown` Defaults to `{}` #### Returns * `void` #### Fires * [set](#event-set) ### `stopDelegating( event?, emitter? ) → void` _(inherited)_ Stops delegating events. It can be used at different levels: * To stop delegating all events. * To stop delegating a specific event to all emitters. * To stop delegating a specific event to a specific emitter. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L552) #### Parameters * `event?: string` The name of the event to stop delegating. If omitted, stops it all delegations. * `emitter?: Emitter` (requires `event`) The object to stop delegating a particular event to. If omitted, stops delegation of `event` to all emitters. #### Returns * `void` ### `stopListening( emitter?, event?, callback? ) → void` _(inherited)_ Stops listening for events. It can be used at different levels: * To stop listening to a specific callback. * To stop listening to a specific event. * To stop listening to all events fired by a specific object. * To stop listening to all events fired by all objects. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-utils/src/emittermixin.ts#L497) #### Parameters * `emitter?: Emitter` The object to stop listening to. If omitted, stops it for all objects. * `event?: string` (Requires the `emitter`) The name of the event to stop listening to. If omitted, stops it for all events from `emitter`. * `callback?: Function` (Requires the `event`) The function to be removed from the call list for the given `event`. #### Returns * `void` ### `stringify( modelElementOrFragment, options ) → string` Returns the content of the given [model's element](module_engine_model_element-ModelElement.md) or [model document fragment](module_engine_model_documentfragment-ModelDocumentFragment.md) converted by the downcast converters attached to the [`downcastDispatcher`](#member-downcastDispatcher) and formatted by the [data processor](#member-processor). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L250) #### Parameters * `modelElementOrFragment: ModelElement | ModelDocumentFragment` The element whose content will be stringified. * `options: Record` Additional configuration passed to the conversion process. Defaults to `{}` #### Returns * `string` Output data. ### `toModel( viewElementOrFragment, context ) → ModelDocumentFragment` Returns the result of the given [view element](module_engine_view_element-ViewElement.md) or [view document fragment](module_engine_view_documentfragment-ViewDocumentFragment.md) converted by the [view-to-model converters](#member-upcastDispatcher), wrapped by [`ModelDocumentFragment`](module_engine_model_documentfragment-ModelDocumentFragment.md). When marker elements were converted during the conversion process, it will be set as a document fragment's [static markers map](module_engine_model_documentfragment-ModelDocumentFragment.md#member-markers). **Note:** The default `context` value is `'$root'`, which only matches the generic root. When the editor uses a custom root [`modelElement`](module_core_editor_editorconfig-RootConfig.md#member-modelElement), pass the target [root element](module_engine_model_rootelement-ModelRootElement.md) (or its configured model element name) explicitly, otherwise the conversion result may be wrong. See the [Custom root elements](../framework/deep-dive/schema.md#custom-root-elements) section of the [Schema deep-dive](../framework/deep-dive/schema.md) guide for more details. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L506) #### Parameters * `viewElementOrFragment: ViewElement | ViewDocumentFragment` The element or document fragment whose content will be converted. * `context: ModelSchemaContextDefinition` Base context in which the view will be converted to the model. See: [`convert`](module_engine_conversion_upcastdispatcher-UpcastDispatcher.md#function-convert). Defaults to `'$root'` #### Returns * `ModelDocumentFragment` Output document fragment. #### Fires * [toModel](#event-toModel) ### `toView( modelElementOrFragment, options ) → ViewDocumentFragment` Returns the content of the given [model element](module_engine_model_element-ModelElement.md) or [model document fragment](module_engine_model_documentfragment-ModelDocumentFragment.md) converted by the downcast converters attached to [`downcastDispatcher`](#member-downcastDispatcher) into a [view document fragment](module_engine_view_documentfragment-ViewDocumentFragment.md). [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L273) #### Parameters * `modelElementOrFragment: ModelElement | ModelDocumentFragment` Element or document fragment whose content will be converted. * `options: Record` Additional configuration that will be available through the [`options`](module_engine_conversion_downcastdispatcher-DowncastConversionApi.md#member-options) during the conversion process. Defaults to `{}` #### Returns * `ViewDocumentFragment` Output view ModelDocumentFragment. #### Fires * [toView](#event-toView) ### `_checkIfRootsExists( rootNames ) → boolean` _(private)_ Checks whether all provided root names are actually existing editor roots. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L562) #### Parameters * `rootNames: Array` Root names to check. #### Returns * `boolean` Whether all provided root names are existing editor roots. ## Events ### `get( eventInfo, )` Event fired after the [get() method](#function-get) has been run. The `get` event is fired by the decorated [`get`](#function-get) method. See [`decorate`](module_utils_observablemixin-Observable.md#function-decorate) for more information and samples. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L621) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `: Parameters` ### `init( eventInfo, )` An event fired after the [`init()` method](#function-init) was run. It can be [listened to](#function-listenTo:BASE_EMITTER) in order to adjust or modify the initialization flow. However, if the `init` event is stopped or prevented, the [`ready` event](#event-ready) should be fired manually. The `init` event is fired by the decorated [`init`](#function-init) method. See [`decorate`](module_utils_observablemixin-Observable.md#function-decorate) for more information and samples. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L593) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `: Parameters` ### `ready( eventInfo )` Event fired once the data initialization has finished. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L578) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. ### `set( eventInfo, )` An event fired after [set() method](#function-set) has been run. The `set` event is fired by the decorated [`set`](#function-set) method. See [`decorate`](module_utils_observablemixin-Observable.md#function-decorate) for more information and samples. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L607) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `: Parameters` ### `toModel( eventInfo, )` Event fired after the [toModel() method](#function-toModel) has been run. The `toModel` event is fired by the decorated [`toModel`](#function-toModel) method. See [`decorate`](module_utils_observablemixin-Observable.md#function-decorate) for more information and samples. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L649) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `: Parameters` ### `toView( eventInfo, )` Event fired after the [toView() method](#function-toView) has been run. The `toView` event is fired by the decorated [`toView`](#function-toView) method. See [`decorate`](module_utils_observablemixin-Observable.md#function-decorate) for more information and samples. [See source](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-engine/src/controller/datacontroller.ts#L635) #### Parameters * `eventInfo: EventInfo` An object containing information about the fired event. * `: Parameters` --- Full index of the CKEditor 5 API reference: [llms.txt](llms.txt)