8
0

viewconversiondispatcher.js 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266
  1. /**
  2. * @license Copyright (c) 2003-2017, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module engine/conversion/viewconversiondispatcher
  7. */
  8. import ViewConsumable from './viewconsumable';
  9. import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
  10. import mix from '@ckeditor/ckeditor5-utils/src/mix';
  11. import extend from '@ckeditor/ckeditor5-utils/src/lib/lodash/extend';
  12. /**
  13. * `ViewConversionDispatcher` is a central point of {@link module:engine/view/view view} conversion, which is a process of
  14. * converting given {@link module:engine/view/documentfragment~DocumentFragment view document fragment} or
  15. * {@link module:engine/view/element~Element}
  16. * into another structure. In default application, {@link module:engine/view/view view} is converted to {@link module:engine/model/model}.
  17. *
  18. * During conversion process, for all {@link module:engine/view/node~Node view nodes} from the converted view document fragment,
  19. * `ViewConversionDispatcher` fires corresponding events. Special callbacks called "converters" should listen to
  20. * `ViewConversionDispatcher` for those events.
  21. *
  22. * Each callback, as a first argument, is passed a special object `data` that has `input` and `output` properties.
  23. * `input` property contains {@link module:engine/view/node~Node view node} or
  24. * {@link module:engine/view/documentfragment~DocumentFragment view document fragment}
  25. * that is converted at the moment and might be handled by the callback. `output` property should be used to save the result
  26. * of conversion. Keep in mind that the `data` parameter is customizable and may contain other values - see
  27. * {@link ~ViewConversionDispatcher#convert}. It is also shared by reference by all callbacks
  28. * listening to given event. **Note**: in view to model conversion - `data` contains `context` property that is an array
  29. * of {@link module:engine/model/element~Element model elements}. These are model elements that will be the parent of currently
  30. * converted view item. `context` property is used in examples below.
  31. *
  32. * The second parameter passed to a callback is an instance of {@link module:engine/conversion/viewconsumable~ViewConsumable}. It stores
  33. * information about what parts of processed view item are still waiting to be handled. After a piece of view item
  34. * was converted, appropriate consumable value should be {@link module:engine/conversion/viewconsumable~ViewConsumable#consume consumed}.
  35. *
  36. * The third parameter passed to a callback is an instance of {@link ~ViewConversionDispatcher}
  37. * which provides additional tools for converters.
  38. *
  39. * Examples of providing callbacks for `ViewConversionDispatcher`:
  40. *
  41. * // Converter for paragraphs (<p>).
  42. * viewDispatcher.on( 'element:p', ( evt, data, consumable, conversionApi ) => {
  43. * const paragraph = new ModelElement( 'paragraph' );
  44. * const schemaQuery = {
  45. * name: 'paragraph',
  46. * inside: data.context
  47. * };
  48. *
  49. * if ( conversionApi.schema.check( schemaQuery ) ) {
  50. * if ( !consumable.consume( data.input, { name: true } ) ) {
  51. * // Before converting this paragraph's children we have to update their context by this paragraph.
  52. * data.context.push( paragraph );
  53. * const children = conversionApi.convertChildren( data.input, consumable, data );
  54. * data.context.pop();
  55. * paragraph.appendChildren( children );
  56. * data.output = paragraph;
  57. * }
  58. * }
  59. * } );
  60. *
  61. * // Converter for links (<a>).
  62. * viewDispatcher.on( 'element:a', ( evt, data, consumable, conversionApi ) => {
  63. * if ( consumable.consume( data.input, { name: true, attributes: [ 'href' ] } ) ) {
  64. * // <a> element is inline and is represented by an attribute in the model.
  65. * // This is why we are not updating `context` property.
  66. * data.output = conversionApi.convertChildren( data.input, consumable, data );
  67. *
  68. * for ( let item of Range.createFrom( data.output ) ) {
  69. * const schemaQuery = {
  70. * name: item.name || '$text',
  71. * attribute: 'link',
  72. * inside: data.context
  73. * };
  74. *
  75. * if ( conversionApi.schema.check( schemaQuery ) ) {
  76. * item.setAttribute( 'link', data.input.getAttribute( 'href' ) );
  77. * }
  78. * }
  79. * }
  80. * } );
  81. *
  82. * // Fire conversion.
  83. * // Always take care where the converted model structure will be appended to. If this `viewDocumentFragment`
  84. * // is going to be appended directly to a '$root' element, use that in `context`.
  85. * viewDispatcher.convert( viewDocumentFragment, { context: [ '$root' ] } );
  86. *
  87. * Before each conversion process, `ViewConversionDispatcher` fires {@link ~ViewConversionDispatcher#event:viewCleanup}
  88. * event which can be used to prepare tree view for conversion.
  89. *
  90. * @mixes module:utils/emittermixin~EmitterMixin
  91. * @fires viewCleanup
  92. * @fires element
  93. * @fires text
  94. * @fires documentFragment
  95. */
  96. export default class ViewConversionDispatcher {
  97. /**
  98. * Creates a `ViewConversionDispatcher` that operates using passed API.
  99. *
  100. * @see module:engine/conversion/viewconversiondispatcher~ViewConversionApi
  101. * @param {Object} [conversionApi] Additional properties for interface that will be passed to events fired
  102. * by `ViewConversionDispatcher`.
  103. */
  104. constructor( conversionApi = {} ) {
  105. /**
  106. * Interface passed by dispatcher to the events callbacks.
  107. *
  108. * @member {module:engine/conversion/viewconversiondispatcher~ViewConversionApi}
  109. */
  110. this.conversionApi = extend( {}, conversionApi );
  111. // `convertItem` and `convertChildren` are bound to this `ViewConversionDispatcher` instance and
  112. // set on `conversionApi`. This way only a part of `ViewConversionDispatcher` API is exposed.
  113. this.conversionApi.convertItem = this._convertItem.bind( this );
  114. this.conversionApi.convertChildren = this._convertChildren.bind( this );
  115. }
  116. /**
  117. * Starts the conversion process. The entry point for the conversion.
  118. *
  119. * @fires element
  120. * @fires text
  121. * @fires documentFragment
  122. * @param {module:engine/view/documentfragment~DocumentFragment|module:engine/view/element~Element}
  123. * viewItem Part of the view to be converted.
  124. * @param {Object} [additionalData] Additional data to be passed in `data` argument when firing `ViewConversionDispatcher`
  125. * events. See also {@link ~ViewConversionDispatcher#event:element element event}.
  126. * @returns {module:engine/model/documentfragment~DocumentFragment} Model document fragment that is a result of the conversion process.
  127. */
  128. convert( viewItem, additionalData = {} ) {
  129. this.fire( 'viewCleanup', viewItem );
  130. const consumable = ViewConsumable.createFrom( viewItem );
  131. return this._convertItem( viewItem, consumable, additionalData );
  132. }
  133. /**
  134. * @private
  135. * @see module:engine/conversion/viewconversiondispatcher~ViewConversionApi#convertItem
  136. */
  137. _convertItem( input, consumable, additionalData = {} ) {
  138. const data = extend( {}, additionalData, {
  139. input: input,
  140. output: null
  141. } );
  142. if ( input.is( 'element' ) ) {
  143. this.fire( 'element:' + input.name, data, consumable, this.conversionApi );
  144. } else if ( input.is( 'text' ) ) {
  145. this.fire( 'text', data, consumable, this.conversionApi );
  146. } else {
  147. this.fire( 'documentFragment', data, consumable, this.conversionApi );
  148. }
  149. return data.output;
  150. }
  151. /**
  152. * @private
  153. * @see module:engine/conversion/viewconversiondispatcher~ViewConversionApi#convertChildren
  154. */
  155. _convertChildren( input, consumable, additionalData = {} ) {
  156. const viewChildren = Array.from( input.getChildren() );
  157. const convertedChildren = viewChildren.map( ( viewChild ) => this._convertItem( viewChild, consumable, additionalData ) );
  158. // Flatten and remove nulls.
  159. return convertedChildren.reduce( ( a, b ) => b ? a.concat( b ) : a, [] );
  160. }
  161. /**
  162. * Fired before the first conversion event, at the beginning of view to model conversion process.
  163. *
  164. * @event viewCleanup
  165. * @param {module:engine/view/documentfragment~DocumentFragment|module:engine/view/element~Element}
  166. * viewItem Part of the view to be converted.
  167. */
  168. /**
  169. * Fired when {@link module:engine/view/element~Element} is converted.
  170. *
  171. * `element` is a namespace event for a class of events. Names of actually called events follow this pattern:
  172. * `element:<elementName>` where `elementName` is the name of converted element. This way listeners may listen to
  173. * all elements conversion or to conversion of specific elements.
  174. *
  175. * @event element
  176. * @param {Object} data Object containing conversion input and a placeholder for conversion output and possibly other
  177. * values (see {@link #convert}).
  178. * Keep in mind that this object is shared by reference between all callbacks that will be called.
  179. * This means that callbacks can add their own values if needed,
  180. * and those values will be available in other callbacks.
  181. * @param {module:engine/view/element~Element} data.input Converted element.
  182. * @param {*} data.output The current state of conversion result. Every change to converted element should
  183. * be reflected by setting or modifying this property.
  184. * @param {module:engine/model/schema~SchemaPath} data.context The conversion context.
  185. * @param {module:engine/conversion/viewconsumable~ViewConsumable} consumable Values to consume.
  186. * @param {Object} conversionApi Conversion interface to be used by callback, passed in `ViewConversionDispatcher` constructor.
  187. * Besides of properties passed in constructor, it also has `convertItem` and `convertChildren` methods which are references
  188. * to {@link #_convertItem} and
  189. * {@link ~ViewConversionDispatcher#_convertChildren}. Those methods are needed to convert
  190. * the whole view-tree they were exposed in `conversionApi` for callbacks.
  191. */
  192. /**
  193. * Fired when {@link module:engine/view/text~Text} is converted.
  194. *
  195. * @event text
  196. * @see #event:element
  197. */
  198. /**
  199. * Fired when {@link module:engine/view/documentfragment~DocumentFragment} is converted.
  200. *
  201. * @event documentFragment
  202. * @see #event:element
  203. */
  204. }
  205. mix( ViewConversionDispatcher, EmitterMixin );
  206. /**
  207. * Conversion interface that is registered for given {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher}
  208. * and is passed as one of parameters when {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher dispatcher}
  209. * fires it's events.
  210. *
  211. * `ViewConversionApi` object is built by {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher} constructor.
  212. * The exact list of properties of this object is determined by the object passed to the constructor.
  213. *
  214. * @interface ViewConversionApi
  215. */
  216. /**
  217. * Starts conversion of given item by firing an appropriate event.
  218. *
  219. * Every fired event is passed (as first parameter) an object with `output` property. Every event may set and/or
  220. * modify that property. When all callbacks are done, the final value of `output` property is returned by this method.
  221. *
  222. * @method #convertItem
  223. * @fires module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#event:element
  224. * @fires module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#event:text
  225. * @fires module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#event:documentFragment
  226. * @param {module:engine/view/documentfragment~DocumentFragment|module:engine/view/element~Element|module:engine/view/text~Text}
  227. * input Item to convert.
  228. * @param {module:engine/conversion/viewconsumable~ViewConsumable} consumable Values to consume.
  229. * @param {Object} [additionalData] Additional data to be passed in `data` argument when firing `ViewConversionDispatcher`
  230. * events. See also {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#event:element element event}.
  231. * @returns {*} The result of item conversion, created and modified by callbacks attached to fired event.
  232. */
  233. /**
  234. * Starts conversion of all children of given item by firing appropriate events for all those children.
  235. *
  236. * @method #convertChildren
  237. * @fires module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#event:element
  238. * @fires module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#event:text
  239. * @fires module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#event:documentFragment
  240. * @param {module:engine/view/documentfragment~DocumentFragment|module:engine/view/element~Element}
  241. * input Item which children will be converted.
  242. * @param {module:engine/conversion/viewconsumable~ViewConsumable} consumable Values to consume.
  243. * @param {Object} [additionalData] Additional data to be passed in `data` argument when firing `ViewConversionDispatcher`
  244. * events. See also {@link module:engine/conversion/viewconversiondispatcher~ViewConversionDispatcher#event:element element event}.
  245. * @returns {Array.<*>} Array containing results of conversion of all children of given item.
  246. */