/** * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved. * For licensing, see LICENSE.md. */ /** * @module engine/controller/datacontroller */ import mix from '@ckeditor/ckeditor5-utils/src/mix'; import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin'; import Mapper from '../conversion/mapper'; import ModelConversionDispatcher from '../conversion/modelconversiondispatcher'; import { insertText } from '../conversion/model-to-view-converters'; import ViewConversionDispatcher from '../conversion/viewconversiondispatcher'; import { convertText, convertToModelFragment } from '../conversion/view-to-model-converters'; import ViewDocumentFragment from '../view/documentfragment'; import ModelRange from '../model/range'; import ModelPosition from '../model/position'; import ModelDocumentFragment from '../model/documentfragment'; import insertContent from './insertcontent'; import deleteContent from './deletecontent'; import modifySelection from './modifyselection'; import getSelectedContent from './getselectedcontent'; /** * 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 {@link ~DataController#get get} * and {@link ~DataController#set set} data of the {@link ~DataController#model model} * using given: * * * {@link module:engine/dataprocessor/dataprocessor~DataProcessor data processor}, * * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher model to view} and * * {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher view to model} converters. * * @mixes module:utils/emittermixin~EmitterMixin */ export default class DataController { /** * Creates data controller instance. * * @param {module:engine/model/document~Document} model Document model. * @param {module:engine/dataprocessor/dataprocessor~DataProcessor} [dataProcessor] Data processor which should used by the controller. */ constructor( model, dataProcessor ) { /** * Document model. * * @readonly * @member {module:engine/model/document~Document} */ this.model = model; /** * Data processor used during the conversion. * * @readonly * @member {module:engine/dataProcessor~DataProcessor} */ this.processor = dataProcessor; /** * Mapper used for the conversion. It has no permanent bindings, because they are created when getting data and * cleared directly after data are converted. However, the mapper is defined as class property, because * it needs to be passed to the `ModelConversionDispatcher` as a conversion API. * * @member {module:engine/conversion/mapper~Mapper} */ this.mapper = new Mapper(); /** * Model to view conversion dispatcher used by the {@link #get get method}. * To attach model to view converter to the data pipeline you need to add lister to this property: * * data.modelToView( 'insert:$element', customInsertConverter ); * * Or use {@link module:engine/conversion/buildmodelconverter~ModelConverterBuilder}: * * buildModelConverter().for( data.modelToView ).fromAttribute( 'bold' ).toElement( 'b' ); * * @readonly * @member {module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher} */ this.modelToView = new ModelConversionDispatcher( this.model, { mapper: this.mapper } ); this.modelToView.on( 'insert:$text', insertText(), { priority: 'lowest' } ); /** * View to model conversion dispatcher used by the {@link #set set method}. * To attach view to model converter to the data pipeline you need to add lister to this property: * * data.viewToModel( 'element', customElementConverter ); * * Or use {@link module:engine/conversion/buildviewconverter~ViewConverterBuilder}: * * buildViewConverter().for( data.viewToModel ).fromElement( 'b' ).toAttribute( 'bold', 'true' ); * * @readonly * @member {module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher} */ this.viewToModel = new ViewConversionDispatcher( { schema: model.schema } ); // Define default converters for text and elements. // // Note that if there is no default converter for the element it will be skipped, for instance `foo` will be // converted to nothing. We add `convertToModelFragment` as a last converter so it converts children of that // element to the document fragment so `foo` will be converted to `foo` if there is no converter for ``. this.viewToModel.on( 'text', convertText(), { priority: 'lowest' } ); this.viewToModel.on( 'element', convertToModelFragment(), { priority: 'lowest' } ); this.viewToModel.on( 'documentFragment', convertToModelFragment(), { priority: 'lowest' } ); this.on( 'insertContent', ( evt, data ) => insertContent( this, data.content, data.selection, data.batch ) ); this.on( 'deleteContent', ( evt, data ) => deleteContent( data.selection, data.batch, data.options ) ); this.on( 'modifySelection', ( evt, data ) => modifySelection( this, data.selection, data.options ) ); this.on( 'getSelectedContent', ( evt, data ) => { data.content = getSelectedContent( data.selection ); } ); } /** * Returns model's data converted by the {@link #modelToView model to view converters} and * formatted by the {@link #processor data processor}. * * @param {String} [rootName='main'] Root name. * @returns {String} Output data. */ get( rootName = 'main' ) { // Get model range. return this.stringify( this.model.getRoot( rootName ) ); } /** * Returns the content of the given {@link module:engine/model/element~Element model's element} or * {@link module:engine/model/documentfragment~DocumentFragment model document fragment} converted by the * {@link #modelToView model to view converters} and formatted by the * {@link #processor data processor}. * * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} modelElementOrFragment * Element which content will be stringified. * @returns {String} Output data. */ stringify( modelElementOrFragment ) { // model -> view const viewDocumentFragment = this.toView( modelElementOrFragment ); // view -> data return this.processor.toData( viewDocumentFragment ); } /** * Returns the content of the given {@link module:engine/model/element~Element model element} or * {@link module:engine/model/documentfragment~DocumentFragment model document fragment} converted by the * {@link #modelToView model to view converters} to a * {@link module:engine/view/documentfragment~DocumentFragment view document fragment}. * * @param {module:engine/model/element~Element|module:engine/model/documentfragment~DocumentFragment} modelElementOrFragment * Element or document fragment which content will be converted. * @returns {module:engine/view/documentfragment~DocumentFragment} Output view DocumentFragment. */ toView( modelElementOrFragment ) { const modelRange = ModelRange.createIn( modelElementOrFragment ); const viewDocumentFragment = new ViewDocumentFragment(); this.mapper.bindElements( modelElementOrFragment, viewDocumentFragment ); this.modelToView.convertInsertion( modelRange ); this.mapper.clearBindings(); return viewDocumentFragment; } /** * Sets input data parsed by the {@link #processor data processor} and * converted by the {@link #viewToModel view to model converters}. * * This method also creates a batch with all the changes applied. If all you need is to parse data use * the {@link #parse} method. * * @param {String} data Input data. * @param {String} [rootName='main'] Root name. */ set( data, rootName = 'main' ) { // Save to model. const modelRoot = this.model.getRoot( rootName ); this.model.enqueueChanges( () => { // Clearing selection is a workaround for ticket #569 (LiveRange loses position after removing data from document). // After fixing it this code should be removed. this.model.selection.removeAllRanges(); this.model.selection.clearAttributes(); // Initial batch should be ignored by features like undo, etc. this.model.batch( 'transparent' ) .remove( ModelRange.createIn( modelRoot ) ) .insert( ModelPosition.createAt( modelRoot, 0 ), this.parse( data ) ); } ); } /** * Returns data parsed by the {@link #processor data processor} and then * converted by the {@link #viewToModel view to model converters}. * * @see #set * @param {String} data Data to parse. * @param {String} [context='$root'] Base context in which the view will be converted to the model. See: * {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#convert}. * @returns {engine/model/documentfragment~DocumentFragment} Model DocumentFragment as a result of view parsing. */ parse( data, context = '$root' ) { // data -> view const viewDocumentFragment = this.processor.toView( data ); // view -> model return this.toModel( viewDocumentFragment, context ); } /** * Returns wrapped by {engine/model/documentfragment~DocumentFragment} result of the given * {@link module:engine/view/element~Element view element} or * {@link module:engine/view/documentfragment~DocumentFragment view document fragment} converted by the * {@link #viewToModel view to model converters}. * * @param {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment} viewElementOrFragment * Element or document fragment which content will be converted. * @param {String} [context='$root'] Base context in which the view will be converted to the model. See: * {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#convert}. * @returns {engine/model/documentfragment~DocumentFragment} View item converted to Model DocumentFragment. */ toModel( viewElementOrFragment, context = '$root' ) { const { conversionResult, markers } = this.viewToModel.convert( viewElementOrFragment, { context: [ context ] } ); let documentFragment; if ( !conversionResult.is( 'documentFragment' ) ) { documentFragment = new ModelDocumentFragment( [ conversionResult ] ); } else { documentFragment = conversionResult; } // Set markers to the documentFragment. for ( const marker of markers ) { documentFragment.markers.set( marker[ 0 ], marker[ 1 ] ); } return documentFragment; } /** * Removes all event listeners set by the DataController. */ destroy() {} /** * See {@link module:engine/controller/insertcontent~insertContent}. * * @fires insertContent * @param {module:engine/model/documentfragment~DocumentFragment} content The content to insert. * @param {module:engine/model/selection~Selection} selection Selection into which the content should be inserted. * @param {module:engine/model/batch~Batch} [batch] Batch to which deltas will be added. If not specified, then * changes will be added to a new batch. */ insertContent( content, selection, batch ) { this.fire( 'insertContent', { content, selection, batch } ); } /** * See {@link module:engine/controller/deletecontent~deleteContent}. * * Note: For the sake of predictability, the resulting selection should always be collapsed. * In cases where a feature wants to modify deleting behavior so selection isn't collapsed * (e.g. a table feature may want to keep row selection after pressing Backspace), * then that behavior should be implemented in the view's listener. At the same time, the table feature * will need to modify this method's behavior too, e.g. to "delete contents and then collapse * the selection inside the last selected cell" or "delete the row and collapse selection somewhere near". * That needs to be done in order to ensure that other features which use `deleteContent()` will work well with tables. * * @fires deleteContent * @param {module:engine/model/selection~Selection} selection Selection of which the content should be deleted. * @param {module:engine/model/batch~Batch} batch Batch to which deltas will be added. * @param {Object} options See {@link module:engine/controller/deletecontent~deleteContent}'s options. */ deleteContent( selection, batch, options ) { this.fire( 'deleteContent', { batch, selection, options } ); } /** * See {@link module:engine/controller/modifyselection~modifySelection}. * * @fires modifySelection * @param {module:engine/model/selection~Selection} selection The selection to modify. * @param {Object} options See {@link module:engine/controller/modifyselection~modifySelection}'s options. */ modifySelection( selection, options ) { this.fire( 'modifySelection', { selection, options } ); } /** * See {@link module:engine/controller/getselectedcontent~getSelectedContent}. * * @fires module:engine/controller/datacontroller~DataController#getSelectedContent * @param {module:engine/model/selection~Selection} selection The selection of which content will be retrieved. * @returns {module:engine/model/documentfragment~DocumentFragment} Document fragment holding the clone of the selected content. */ getSelectedContent( selection ) { const evtData = { selection }; this.fire( 'getSelectedContent', evtData ); return evtData.content; } } mix( DataController, EmitterMixin ); /** * Result of parsing view to model. * * @typedef {Object} {engine/controller/datacontroller~ParsedModelData} * @property {module:engine/model/documentfragment~DocumentFragment|module:engine/model/node~Node} modelItem * Fragment of parsed model. * @property {Map} markers List of parsed marker stamps. */ /** * Event fired when {@link #insertContent} method is called. * The {@link #insertContent default action of that method} is implemented as a * listener to this event so it can be fully customized by the features. * * @event insertContent * @param {Object} data * @param {module:engine/view/documentfragment~DocumentFragment} data.content The content to insert. * @param {module:engine/model/selection~Selection} data.selection Selection into which the content should be inserted. * @param {module:engine/model/batch~Batch} [data.batch] Batch to which deltas will be added. */ /** * Event fired when {@link #deleteContent} method is called. * The {@link module:engine/controller/deletecontent~deleteContent default action of that method} is implemented as a * listener to this event so it can be fully customized by the features. * * @event deleteContent * @param {Object} data * @param {module:engine/model/batch~Batch} data.batch * @param {module:engine/model/selection~Selection} data.selection * @param {Object} data.options See {@link module:engine/controller/deletecontent~deleteContent}'s options. */ /** * Event fired when {@link #modifySelection} method is called. * The {@link module:engine/controller/modifyselection~modifySelection default action of that method} is implemented as a * listener to this event so it can be fully customized by the features. * * @event modifySelection * @param {Object} data * @param {module:engine/model/selection~Selection} data.selection * @param {Object} data.options See {@link module:engine/controller/modifyselection~modifySelection}'s options. */ /** * Event fired when {@link module:engine/controller/datacontroller~DataController#getSelectedContent} method is called. * The {@link module:engine/controller/getselectedcontent~getSelectedContent default action of that method} is implemented as a * listener to this event so it can be fully customized by the features. * * @event module:engine/controller/datacontroller~DataController#getSelectedContent * @param {Object} data * @param {module:engine/model/selection~Selection} data.selection * @param {module:engine/model/documentfragment~DocumentFragment} data.content The document fragment to return * (holding a clone of the selected content). */