8
0

viewconversiondispatcher.js 12 KB

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