datacontroller.js 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303
  1. /**
  2. * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module engine/controller/datacontroller
  7. */
  8. import mix from '../../utils/mix.js';
  9. import EmitterMixin from '../../utils/emittermixin.js';
  10. import Mapper from '../conversion/mapper.js';
  11. import ModelConversionDispatcher from '../conversion/modelconversiondispatcher.js';
  12. import { insertText } from '../conversion/model-to-view-converters.js';
  13. import ViewConversionDispatcher from '../conversion/viewconversiondispatcher.js';
  14. import { convertText, convertToModelFragment } from '../conversion/view-to-model-converters.js';
  15. import ViewDocumentFragment from '../view/documentfragment.js';
  16. import ModelRange from '../model/range.js';
  17. import ModelPosition from '../model/position.js';
  18. import insertContent from './insertcontent.js';
  19. import deleteContent from './deletecontent.js';
  20. import modifySelection from './modifyselection.js';
  21. /**
  22. * Controller for the data pipeline. The data pipeline controls how data is retrieved from the document
  23. * and set inside it. Hence, the controller features two methods which allow to {@link #get get}
  24. * and {@link #set set} data of the {@link #model model}
  25. * using given:
  26. *
  27. * * {@link module:engine/dataProcessor.DataProcessor data processor},
  28. * * {@link module:engine/conversion/modelconversiondispatcher~ModelConversionDispatcher model to view} and
  29. * * {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher view to model} converters.
  30. *
  31. * @mixes module:utils/emittermixin~EmitterMixin
  32. */
  33. export default class DataController {
  34. /**
  35. * Creates data controller instance.
  36. *
  37. * @param {module:engine/model/document~Document} model Document model.
  38. * @param {module:engine/dataProcessor~DataProcessor} [dataProcessor] Data processor which should used by the controller.
  39. */
  40. constructor( model, dataProcessor ) {
  41. /**
  42. * Document model.
  43. *
  44. * @readonly
  45. * @member {module:engine/model/document}
  46. */
  47. this.model = model;
  48. /**
  49. * Data processor used during the conversion.
  50. *
  51. * @readonly
  52. * @member {engine.dataProcessor.DataProcessor}
  53. */
  54. this.processor = dataProcessor;
  55. /**
  56. * Mapper used for the conversion. It has no permanent bindings, because they are created when getting data and
  57. * cleared directly after data are converted. However, the mapper is defined as class property, because
  58. * it needs to be passed to the `ModelConversionDispatcher` as a conversion API.
  59. *
  60. * @member {engine.conversion.Mapper}
  61. */
  62. this.mapper = new Mapper();
  63. /**
  64. * Model to view conversion dispatcher used by the {@link #get get method}.
  65. * To attach model to view converter to the data pipeline you need to add lister to this property:
  66. *
  67. * data.modelToView( 'insert:$element', customInsertConverter );
  68. *
  69. * Or use {@link engine.conversion.ModelConverterBuilder}:
  70. *
  71. * buildModelConverter().for( data.modelToView ).fromAttribute( 'bold' ).toElement( 'b' );
  72. *
  73. * @readonly
  74. * @member {engine.conversion.ModelConversionDispatcher}
  75. */
  76. this.modelToView = new ModelConversionDispatcher( {
  77. mapper: this.mapper
  78. } );
  79. this.modelToView.on( 'insert:$text', insertText(), { priority: 'lowest' } );
  80. /**
  81. * View to model conversion dispatcher used by the {@link #set set method}.
  82. * To attach view to model converter to the data pipeline you need to add lister to this property:
  83. *
  84. * data.viewToModel( 'element', customElementConverter );
  85. *
  86. * Or use {@link engine.conversion.ViewConverterBuilder}:
  87. *
  88. * buildViewConverter().for( data.viewToModel ).fromElement( 'b' ).toAttribute( 'bold', 'true' );
  89. *
  90. * @readonly
  91. * @member {engine.conversion.ViewConversionDispatcher}
  92. */
  93. this.viewToModel = new ViewConversionDispatcher( {
  94. schema: model.schema
  95. } );
  96. // Define default converters for text and elements.
  97. //
  98. // Note that if there is no default converter for the element it will be skipped, for instance `<b>foo</b>` will be
  99. // converted to nothing. We add `convertToModelFragment` as a last converter so it converts children of that
  100. // element to the document fragment so `<b>foo</b>` will be converted to `foo` if there is no converter for `<b>`.
  101. this.viewToModel.on( 'text', convertText(), { priority: 'lowest' } );
  102. this.viewToModel.on( 'element', convertToModelFragment(), { priority: 'lowest' } );
  103. this.viewToModel.on( 'documentFragment', convertToModelFragment(), { priority: 'lowest' } );
  104. this.on( 'insertContent', ( evt, data ) => insertContent( this, data.content, data.selection, data.batch ) );
  105. this.on( 'deleteContent', ( evt, data ) => deleteContent( data.selection, data.batch, data.options ) );
  106. this.on( 'modifySelection', ( evt, data ) => modifySelection( data.selection, data.options ) );
  107. }
  108. /**
  109. * Returns model's data converted by the {@link #modelToView model to view converters} and
  110. * formatted by the {@link #processor data processor}.
  111. *
  112. * @param {String} [rootName='main'] Root name.
  113. * @returns {String} Output data.
  114. */
  115. get( rootName = 'main' ) {
  116. // Get model range.
  117. return this.stringify( this.model.getRoot( rootName ) );
  118. }
  119. /**
  120. * Returns the content of the given {@link module:engine/model/Element model's element} converted by the
  121. * {@link #modelToView model to view converters} and formatted by the
  122. * {@link #processor data processor}.
  123. *
  124. * @param {module:engine/model/Element} modelElement Element which content will be stringified.
  125. * @returns {String} Output data.
  126. */
  127. stringify( modelElement ) {
  128. // model -> view
  129. const viewDocumentFragment = this.toView( modelElement );
  130. // view -> data
  131. return this.processor.toData( viewDocumentFragment );
  132. }
  133. /**
  134. * Returns the content of the given {@link module:engine/model/Element model's element} converted by the
  135. * {@link #modelToView model to view converters} to the
  136. * {@link engine.view.DocumentFragment view DocumentFragment}.
  137. *
  138. * @param {module:engine/model/Element} modelElement Element which content will be stringified.
  139. * @returns {engine.view.DocumentFragment} Output view DocumentFragment.
  140. */
  141. toView( modelElement ) {
  142. const modelRange = ModelRange.createIn( modelElement );
  143. const viewDocumentFragment = new ViewDocumentFragment();
  144. this.mapper.bindElements( modelElement, viewDocumentFragment );
  145. this.modelToView.convertInsertion( modelRange );
  146. this.mapper.clearBindings();
  147. return viewDocumentFragment;
  148. }
  149. /**
  150. * Sets input data parsed by the {@link #processor data processor} and
  151. * converted by the {@link #viewToModel view to model converters}.
  152. *
  153. * This method also creates a batch with all the changes applied. If all you need is to parse data use
  154. * the {@link #parse} method.
  155. *
  156. * @param {String} data Input data.
  157. * @param {String} [rootName='main'] Root name.
  158. */
  159. set( data, rootName = 'main' ) {
  160. // Save to model.
  161. const modelRoot = this.model.getRoot( rootName );
  162. this.model.enqueueChanges( () => {
  163. // Clearing selection is a workaround for ticket #569 (LiveRange loses position after removing data from document).
  164. // After fixing it this code should be removed.
  165. this.model.selection.removeAllRanges();
  166. this.model.selection.clearAttributes();
  167. // Initial batch should be ignored by features like undo, etc.
  168. this.model.batch( 'transparent' )
  169. .remove( ModelRange.createIn( modelRoot ) )
  170. .insert( ModelPosition.createAt( modelRoot, 0 ), this.parse( data ) );
  171. } );
  172. }
  173. /**
  174. * Returns data parsed by the {@link #processor data processor} and then
  175. * converted by the {@link #viewToModel view to model converters}.
  176. *
  177. * @see #set
  178. * @param {String} data Data to parse.
  179. * @param {String} [context='$root'] Base context in which view will be converted to the model. See:
  180. * {@link engine.conversion.ViewConversionDispatcher#convert}.
  181. * @returns {module:engine/model/DocumentFragment} Parsed data.
  182. */
  183. parse( data, context = '$root' ) {
  184. // data -> view
  185. const viewDocumentFragment = this.processor.toView( data );
  186. // view -> model
  187. return this.viewToModel.convert( viewDocumentFragment, { context: [ context ] } );
  188. }
  189. /**
  190. * Removes all event listeners set by the DataController.
  191. */
  192. destroy() {}
  193. /**
  194. * See {@link engine.controller.insertContent}.
  195. *
  196. * @fires insertContent
  197. * @param {module:engine/model/DocumentFragment} content The content to insert.
  198. * @param {module:engine/model/Selection} selection Selection into which the content should be inserted.
  199. * @param {module:engine/model/Batch} [batch] Batch to which deltas will be added. If not specified, then
  200. * changes will be added to a new batch.
  201. */
  202. insertContent( content, selection, batch ) {
  203. this.fire( 'insertContent', { content, selection, batch } );
  204. }
  205. /**
  206. * See {@link engine.controller.deleteContent}.
  207. *
  208. * Note: For the sake of predictability, the resulting selection should always be collapsed.
  209. * In cases where a feature wants to modify deleting behavior so selection isn't collapsed
  210. * (e.g. a table feature may want to keep row selection after pressing <kbd>Backspace</kbd>),
  211. * then that behavior should be implemented in the view's listener. At the same time, the table feature
  212. * will need to modify this method's behavior too, e.g. to "delete contents and then collapse
  213. * the selection inside the last selected cell" or "delete the row and collapse selection somewhere near".
  214. * That needs to be done in order to ensure that other features which use `deleteContent()` will work well with tables.
  215. *
  216. * @fires deleteContent
  217. * @param {module:engine/model/Selection} selection Selection of which the content should be deleted.
  218. * @param {module:engine/model/Batch} batch Batch to which deltas will be added.
  219. * @param {Object} options See {@link engine.controller.deleteContent}'s options.
  220. */
  221. deleteContent( selection, batch, options ) {
  222. this.fire( 'deleteContent', { batch, selection, options } );
  223. }
  224. /**
  225. * See {@link engine.controller.modifySelection}.
  226. *
  227. * @fires modifySelection
  228. * @param {module:engine/model/Selection} The selection to modify.
  229. * @param {Object} options See {@link engine.controller.modifySelection}'s options.
  230. */
  231. modifySelection( selection, options ) {
  232. this.fire( 'modifySelection', { selection, options } );
  233. }
  234. }
  235. mix( DataController, EmitterMixin );
  236. /**
  237. * Event fired when {@link #insertContent} method is called.
  238. * The {@link .insertContent default action of that method} is implemented as a
  239. * listener to this event so it can be fully customized by the features.
  240. *
  241. * @event insertContent
  242. * @param {Object} data
  243. * @param {engine.view.DocumentFragment} data.content The content to insert.
  244. * @param {module:engine/model/Selection} data.selection Selection into which the content should be inserted.
  245. * @param {module:engine/model/Batch} [data.batch] Batch to which deltas will be added.
  246. */
  247. /**
  248. * Event fired when {@link #deleteContent} method is called.
  249. * The {@link engine.controller.deleteContent default action of that method} is implemented as a
  250. * listener to this event so it can be fully customized by the features.
  251. *
  252. * @event deleteContent
  253. * @param {Object} data
  254. * @param {module:engine/model/Batch} data.batch
  255. * @param {module:engine/model/Selection} data.selection
  256. * @param {Object} data.options See {@link engine.controller.deleteContent}'s options.
  257. */
  258. /**
  259. * Event fired when {@link #modifySelection} method is called.
  260. * The {@link module:engine/controller/modifyselection~modifySelection default action of that method} is implemented as a
  261. * listener to this event so it can be fully customized by the features.
  262. *
  263. * @event modifySelection
  264. * @param {Object} data
  265. * @param {module:engine/model/Selection} data.selection
  266. * @param {Object} data.options See {@link module:engine/controller/modifyselection~modifySelection}'s options.
  267. */