model.js 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340
  1. /**
  2. * @license Copyright (c) 2003-2016, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. import Mapper from '/ckeditor5/engine/conversion/mapper.js';
  6. import Document from '/ckeditor5/engine/model/document.js';
  7. import Range from '/ckeditor5/engine/model/range.js';
  8. import Position from '/ckeditor5/engine/model/position.js';
  9. import RootElement from '/ckeditor5/engine/model/rootelement.js';
  10. import ModelConversionDispatcher from '/ckeditor5/engine/conversion/modelconversiondispatcher.js';
  11. import ModelSelection from '/ckeditor5/engine/model/selection.js';
  12. import ModelDocumentFragment from '/ckeditor5/engine/model/documentfragment.js';
  13. import ModelElement from '/ckeditor5/engine/model/element.js';
  14. import ModelText from '/ckeditor5/engine/model/text.js';
  15. import ViewConversionDispatcher from '/ckeditor5/engine/conversion/viewconversiondispatcher.js';
  16. import ViewSelection from '/ckeditor5/engine/view/selection.js';
  17. import ViewDocumentFragment from '/ckeditor5/engine/view/documentfragment.js';
  18. import ViewElement from '/ckeditor5/engine/view/containerelement.js';
  19. import ViewText from '/ckeditor5/engine/view/text.js';
  20. import viewWriter from '/ckeditor5/engine/view/writer.js';
  21. import { parse as viewParse, stringify as viewStringify } from '/tests/engine/_utils/view.js';
  22. import { convertRangeSelection, convertCollapsedSelection } from '/ckeditor5/engine/conversion/model-selection-to-view-converters.js';
  23. import { convertText, convertToModelFragment } from '/ckeditor5/engine/conversion/view-to-model-converters.js';
  24. // Test utils uses `<$text foo="bar">Lorem ipsum</$text>` notation to create text with attributes, but `$text` is not
  25. // valid XML element name, so needs to be parsed before conversion to view.
  26. const VIEW_TEXT_WITH_ATTRIBUTES_ELEMENT = 'view-text-with-attributes';
  27. const DATA_STRING_TEXT_WITH_ATTRIBUTES_ELEMENT = '$text';
  28. /**
  29. * Writes the contents of the {@link engine.model.Document Document} to an HTML-like string.
  30. *
  31. * ** Note: ** {@link engine.model.Text text} node contains attributes will be represented as:
  32. * <$text attribute="value">Text data</$text>
  33. *
  34. * @param {engine.model.Document} document
  35. * @param {Object} [options]
  36. * @param {Boolean} [options.withoutSelection=false] Whether to write the selection. When set to `true` selection will
  37. * be not included in returned string.
  38. * @param {Boolean} [options.rootName='main'] Name of the root from which data should be stringified. If not provided
  39. * default `main` name will be used.
  40. * @returns {String} The stringified data.
  41. */
  42. export function getData( document, options = {} ) {
  43. if ( !( document instanceof Document ) ) {
  44. throw new TypeError( 'Document needs to be an instance of engine.model.Document.' );
  45. }
  46. const withoutSelection = !!options.withoutSelection;
  47. const rootName = options.rootName || 'main';
  48. const root = document.getRoot( rootName );
  49. return withoutSelection ? getData._stringify( root ) : getData._stringify( root, document.selection );
  50. }
  51. // Set stringify as getData private method - needed for testing/spying.
  52. getData._stringify = stringify;
  53. /**
  54. * Sets the contents of the {@link engine.model.Document Document} provided as HTML-like string.
  55. * It uses {@link engine.model.Document#enqueueChanges enqueueChanges} method.
  56. *
  57. * ** Note: ** Remember to register elements in {@link engine.model.Document#schema document's schema} before inserting them.
  58. *
  59. * ** Note: ** To create {@link engine.model.Text text} node witch containing attributes use:
  60. * <$text attribute="value">Text data</$text>
  61. *
  62. * @param {engine.model.Document} document
  63. * @param {String} data HTML-like string to write into Document.
  64. * @param {Object} options
  65. * @param {String} [options.rootName='main'] Root name where parsed data will be stored. If not provided, default `main`
  66. * name will be used.
  67. * @param {Array<Object>} [options.selectionAttributes] List of attributes which will be passed to selection.
  68. * @param {String} [options.batchType='transparent'] Batch type used for inserting elements. See {@link engine.model.Batch#type}.
  69. */
  70. export function setData( document, data, options = {} ) {
  71. if ( !( document instanceof Document ) ) {
  72. throw new TypeError( 'Document needs to be an instance of engine.model.Document.' );
  73. }
  74. let modelDocumentFragment, selection;
  75. const mapper = new Mapper();
  76. const modelRoot = document.getRoot( options.rootName || 'main' );
  77. // Parse data string to model.
  78. const parsedResult = setData._parse( data, document.schema, mapper );
  79. // Retrieve DocumentFragment and Selection from parsed model.
  80. if ( parsedResult.model ) {
  81. modelDocumentFragment = parsedResult.model;
  82. selection = parsedResult.selection;
  83. } else {
  84. modelDocumentFragment = parsedResult;
  85. }
  86. document.enqueueChanges( () => {
  87. // Replace existing model in document by new one.
  88. document.batch( options.batchType || 'transparent' )
  89. .remove( Range.createFromElement( modelRoot ) )
  90. .insert( Position.createAt( modelRoot, 0 ), modelDocumentFragment );
  91. // Clear selection
  92. document.selection.clearAttributes();
  93. document.selection.removeAllRanges();
  94. // Set attributes to selection if specified.
  95. if ( options.selectionAttributes ) {
  96. document.selection.setAttributesTo( options.selectionAttributes );
  97. }
  98. // Convert view selection to model if selection is defined.
  99. if ( selection ) {
  100. const ranges = [];
  101. for ( let viewRange of selection.getRanges() ) {
  102. ranges.push( ( mapper.toModelRange( viewRange ) ) );
  103. }
  104. document.selection.setRanges( ranges, selection.isBackward );
  105. }
  106. } );
  107. }
  108. // Set parse as setData private method - needed for testing/spying.
  109. setData._parse = parse;
  110. /**
  111. * Converts model nodes to HTML-like string representation.
  112. *
  113. * ** Note: ** {@link engine.model.Text text} node contains attributes will be represented as:
  114. * <$text attribute="value">Text data</$text>
  115. *
  116. * @param {engine.model.RootElement|engine.model.Element|engine.model.Text|
  117. * engine.model.DocumentFragment} node Node to stringify.
  118. * @param {engine.model.Selection|engine.model.Position|engine.model.Range} [selectionOrPositionOrRange=null]
  119. * Selection instance which ranges will be included in returned string data. If Range instance is provided - it will be
  120. * converted to selection containing this range. If Position instance is provided - it will be converted to selection
  121. * containing one range collapsed at this position.
  122. * @returns {String} HTML-like string representing the model.
  123. */
  124. export function stringify( node, selectionOrPositionOrRange = null ) {
  125. const mapper = new Mapper();
  126. let selection, range;
  127. // Create a range wrapping passed node.
  128. if ( node instanceof RootElement || node instanceof ModelDocumentFragment ) {
  129. range = Range.createFromElement( node );
  130. } else {
  131. // Node is detached - create new document fragment.
  132. if ( !node.parent ) {
  133. const fragment = new ModelDocumentFragment( node );
  134. range = Range.createFromElement( fragment );
  135. } else {
  136. range = new Range(
  137. Position.createBefore( node ),
  138. Position.createAfter( node )
  139. );
  140. }
  141. }
  142. // Get selection from passed selection or position or range if at least one is specified.
  143. if ( selectionOrPositionOrRange instanceof ModelSelection ) {
  144. selection = selectionOrPositionOrRange;
  145. } else if ( selectionOrPositionOrRange instanceof Range ) {
  146. selection = new ModelSelection();
  147. selection.addRange( selectionOrPositionOrRange );
  148. } else if ( selectionOrPositionOrRange instanceof Position ) {
  149. selection = new ModelSelection();
  150. selection.addRange( new Range( selectionOrPositionOrRange, selectionOrPositionOrRange ) );
  151. }
  152. // Setup model -> view converter.
  153. const viewDocumentFragment = new ViewDocumentFragment();
  154. const viewSelection = new ViewSelection();
  155. const modelToView = new ModelConversionDispatcher( { mapper, viewSelection } );
  156. modelToView.on( 'insert:$text', insertText() );
  157. modelToView.on( 'insert', insertElement() );
  158. modelToView.on( 'selection', convertRangeSelection() );
  159. modelToView.on( 'selection', convertCollapsedSelection() );
  160. mapper.bindElements( node, viewDocumentFragment );
  161. // Convert view to model.
  162. modelToView.convertInsert( range );
  163. modelToView.convertSelection( selection );
  164. mapper.clearBindings();
  165. // Parse view to data string.
  166. let data = viewStringify( viewDocumentFragment, viewSelection, { characterForSelectionInText: [ '[', ']' ] } );
  167. // Replace valid XML text element name to `$text`.
  168. return data.replace( new RegExp( VIEW_TEXT_WITH_ATTRIBUTES_ELEMENT, 'g' ), DATA_STRING_TEXT_WITH_ATTRIBUTES_ELEMENT );
  169. }
  170. /**
  171. * Parses HTML-like string and returns model {@link engine.model.RootElement rootElement}.
  172. *
  173. * ** Note: ** To create {@link engine.model.Text text} node witch containing attributes use:
  174. * <$text attribute="value">Text data</$text>
  175. *
  176. * @param {String} data HTML-like string to be parsed.
  177. * @param {engine.model.schema} schema Schema instance uses by converters for validation. Element not registered
  178. * in schema won't be created.
  179. * @param {engine.model.mapper} [mapper=new Mapper()] Mapper instance uses mainly by `setData` method to map position
  180. * between {@link engine.view.document Document} and {@link engine.model.document Document}.
  181. * @returns {engine.model.Element|engine.model.Text|engine.model.DocumentFragment|Object} Returns parsed model node or
  182. * object with two fields `model` and `selection` when selection ranges were included in data to parse.
  183. */
  184. export function parse( data, schema, mapper = new Mapper() ) {
  185. // Replace not accepted by XML `$text` element by valid one.
  186. data = data.replace( new RegExp( '\\' + DATA_STRING_TEXT_WITH_ATTRIBUTES_ELEMENT, 'g' ), VIEW_TEXT_WITH_ATTRIBUTES_ELEMENT );
  187. // Parse data to view using view utils.
  188. const parsedResult = viewParse( data );
  189. // Retrieve DocumentFragment and Selection from parsed view.
  190. let viewDocumentFragment, selection;
  191. if ( parsedResult.view && parsedResult.selection ) {
  192. viewDocumentFragment = parsedResult.view;
  193. selection = parsedResult.selection;
  194. } else {
  195. viewDocumentFragment = parsedResult;
  196. }
  197. viewDocumentFragment = viewDocumentFragment.parent ? viewDocumentFragment.parent : viewDocumentFragment;
  198. // Setup view -> model converter.
  199. const viewToModel = new ViewConversionDispatcher( { mapper, schema } );
  200. viewToModel.on( 'text', convertText() );
  201. viewToModel.on( `element:${ VIEW_TEXT_WITH_ATTRIBUTES_ELEMENT }`, convertToModelTextWithAttributes(), null, 9999 );
  202. viewToModel.on( 'element', convertToModelElement(), null, 9999 );
  203. viewToModel.on( 'documentFragment', convertToModelFragment(), null, 9999 );
  204. // Convert view to model.
  205. let root = viewToModel.convert( viewDocumentFragment, { context: [ '$root' ] } );
  206. // If root DocumentFragment contains only one element - return that element.
  207. if ( root instanceof DocumentFragment && root.childCount == 1 ) {
  208. root = root.getChild( 0 );
  209. }
  210. // Return model end selection when selection was specified.
  211. if ( selection ) {
  212. return {
  213. model: root,
  214. selection: selection
  215. };
  216. }
  217. // Otherwise return model only.
  218. return root;
  219. }
  220. // -- converters view -> model -----------------------------------------------------
  221. function convertToModelElement() {
  222. return ( evt, data, consumable, conversionApi ) => {
  223. const schemaQuery = {
  224. name: data.input.name,
  225. inside: data.context
  226. };
  227. // `VIEW_TEXT_WITH_ATTRIBUTES_ELEMENT` is handled in specified way by `convertToModelTextWithAttributes`.
  228. if ( data.input.name !== VIEW_TEXT_WITH_ATTRIBUTES_ELEMENT ) {
  229. if ( !conversionApi.schema.check( schemaQuery ) ) {
  230. throw new Error( `Element '${ schemaQuery.name }' not allowed in context.` );
  231. }
  232. if ( consumable.consume( data.input, { name: true } ) ) {
  233. data.output = new ModelElement( data.input.name, data.input.getAttributes() );
  234. conversionApi.mapper.bindElements( data.output, data.input );
  235. data.context.push( data.output );
  236. data.output.appendChildren( conversionApi.convertChildren( data.input, consumable, data ) );
  237. data.context.pop();
  238. }
  239. }
  240. };
  241. }
  242. function convertToModelTextWithAttributes() {
  243. return ( evt, data, consumable, conversionApi ) => {
  244. const schemaQuery = {
  245. name: '$text',
  246. inside: data.context
  247. };
  248. if ( !conversionApi.schema.check( schemaQuery ) ) {
  249. throw new Error( `Element '${ schemaQuery.name }' not allowed in context.` );
  250. }
  251. if ( conversionApi.schema.check( schemaQuery ) ) {
  252. if ( consumable.consume( data.input, { name: true } ) ) {
  253. data.output = new ModelText( data.input.getChild( 0 ).data, data.input.getAttributes() );
  254. }
  255. }
  256. };
  257. }
  258. // -- converters model -> view -----------------------------------------------------
  259. function insertElement() {
  260. return ( evt, data, consumable, conversionApi ) => {
  261. consumable.consume( data.item, 'insert' );
  262. const viewPosition = conversionApi.mapper.toViewPosition( data.range.start );
  263. const viewElement = new ViewElement( data.item.name, data.item.getAttributes() );
  264. conversionApi.mapper.bindElements( data.item, viewElement );
  265. viewWriter.insert( viewPosition, viewElement );
  266. };
  267. }
  268. function insertText() {
  269. return ( evt, data, consumable, conversionApi ) => {
  270. consumable.consume( data.item, 'insert' );
  271. const viewPosition = conversionApi.mapper.toViewPosition( data.range.start );
  272. const textAttributes = data.item.getAttributes();
  273. let node;
  274. if ( textAttributes.length ) {
  275. node = new ViewElement( VIEW_TEXT_WITH_ATTRIBUTES_ELEMENT, textAttributes );
  276. } else {
  277. node = new ViewText( data.item.data );
  278. }
  279. viewWriter.insert( viewPosition, node );
  280. evt.stop();
  281. };
  282. }