view.js 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610
  1. /**
  2. * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module engine/view/view
  7. */
  8. import Document from './document';
  9. import DowncastWriter from './downcastwriter';
  10. import Renderer from './renderer';
  11. import DomConverter from './domconverter';
  12. import Position from './position';
  13. import Range from './range';
  14. import Selection from './selection';
  15. import MutationObserver from './observer/mutationobserver';
  16. import KeyObserver from './observer/keyobserver';
  17. import FakeSelectionObserver from './observer/fakeselectionobserver';
  18. import SelectionObserver from './observer/selectionobserver';
  19. import FocusObserver from './observer/focusobserver';
  20. import CompositionObserver from './observer/compositionobserver';
  21. import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
  22. import log from '@ckeditor/ckeditor5-utils/src/log';
  23. import mix from '@ckeditor/ckeditor5-utils/src/mix';
  24. import { scrollViewportToShowTarget } from '@ckeditor/ckeditor5-utils/src/dom/scroll';
  25. import { injectUiElementHandling } from './uielement';
  26. import { injectQuirksHandling } from './filler';
  27. import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  28. /**
  29. * Editor's view controller class. Its main responsibility is DOM - View management for editing purposes, to provide
  30. * abstraction over the DOM structure and events and hide all browsers quirks.
  31. *
  32. * View controller renders view document to DOM whenever view structure changes. To determine when view can be rendered,
  33. * all changes need to be done using the {@link module:engine/view/view~View#change} method, using
  34. * {@link module:engine/view/downcastwriter~DowncastWriter}:
  35. *
  36. * view.change( writer => {
  37. * writer.insert( position, writer.createText( 'foo' ) );
  38. * } );
  39. *
  40. * View controller also register {@link module:engine/view/observer/observer~Observer observers} which observes changes
  41. * on DOM and fire events on the {@link module:engine/view/document~Document Document}.
  42. * Note that the following observers are added by the class constructor and are always available:
  43. *
  44. * * {@link module:engine/view/observer/mutationobserver~MutationObserver},
  45. * * {@link module:engine/view/observer/selectionobserver~SelectionObserver},
  46. * * {@link module:engine/view/observer/focusobserver~FocusObserver},
  47. * * {@link module:engine/view/observer/keyobserver~KeyObserver},
  48. * * {@link module:engine/view/observer/fakeselectionobserver~FakeSelectionObserver}.
  49. * * {@link module:engine/view/observer/compositionobserver~CompositionObserver}.
  50. *
  51. * This class also {@link module:engine/view/view~View#attachDomRoot binds the DOM and the view elements}.
  52. *
  53. * If you do not need full a DOM - view management, and only want to transform a tree of view elements to a tree of DOM
  54. * elements you do not need this controller. You can use the {@link module:engine/view/domconverter~DomConverter DomConverter} instead.
  55. *
  56. * @mixes module:utils/observablemixin~ObservableMixin
  57. */
  58. export default class View {
  59. constructor() {
  60. /**
  61. * Instance of the {@link module:engine/view/document~Document} associated with this view controller.
  62. *
  63. * @readonly
  64. * @type {module:engine/view/document~Document}
  65. */
  66. this.document = new Document();
  67. /**
  68. * Instance of the {@link module:engine/view/domconverter~DomConverter domConverter} use by
  69. * {@link module:engine/view/view~View#renderer renderer}
  70. * and {@link module:engine/view/observer/observer~Observer observers}.
  71. *
  72. * @readonly
  73. * @type {module:engine/view/domconverter~DomConverter}
  74. */
  75. this.domConverter = new DomConverter();
  76. /**
  77. * Instance of the {@link module:engine/view/renderer~Renderer renderer}.
  78. *
  79. * @protected
  80. * @type {module:engine/view/renderer~Renderer}
  81. */
  82. this._renderer = new Renderer( this.domConverter, this.document.selection );
  83. this._renderer.bind( 'isFocused' ).to( this.document );
  84. /**
  85. * Roots of the DOM tree. Map on the `HTMLElement`s with roots names as keys.
  86. *
  87. * @readonly
  88. * @type {Map.<String, HTMLElement>}
  89. */
  90. this.domRoots = new Map();
  91. /**
  92. * Map of registered {@link module:engine/view/observer/observer~Observer observers}.
  93. *
  94. * @private
  95. * @type {Map.<Function, module:engine/view/observer/observer~Observer>}
  96. */
  97. this._observers = new Map();
  98. /**
  99. * Is set to `true` when {@link #change view changes} are currently in progress.
  100. *
  101. * @private
  102. * @type {Boolean}
  103. */
  104. this._ongoingChange = false;
  105. /**
  106. * Used to prevent calling {@link #render} and {@link #change} during rendering view to the DOM.
  107. *
  108. * @private
  109. * @type {Boolean}
  110. */
  111. this._renderingInProgress = false;
  112. /**
  113. * Used to prevent calling {@link #render} and {@link #change} during rendering view to the DOM.
  114. *
  115. * @private
  116. * @type {Boolean}
  117. */
  118. this._postFixersInProgress = false;
  119. /**
  120. * Internal flag to temporary disable rendering. See usage in the editing controller.
  121. *
  122. * @protected
  123. * @type {Boolean}
  124. */
  125. this._renderingDisabled = false;
  126. /**
  127. * Internal flag to disable rendering when there are no changes since the last rendering.
  128. *
  129. * @private
  130. * @type {Boolean}
  131. */
  132. this._hasChangedSinceTheLastRendering = false;
  133. /**
  134. * DowncastWriter instance used in {@link #change change method} callbacks.
  135. *
  136. * @private
  137. * @type {module:engine/view/downcastwriter~DowncastWriter}
  138. */
  139. this._writer = new DowncastWriter( this.document );
  140. // Add default observers.
  141. this.addObserver( MutationObserver );
  142. this.addObserver( SelectionObserver );
  143. this.addObserver( FocusObserver );
  144. this.addObserver( KeyObserver );
  145. this.addObserver( FakeSelectionObserver );
  146. this.addObserver( CompositionObserver );
  147. // Inject quirks handlers.
  148. injectQuirksHandling( this );
  149. injectUiElementHandling( this );
  150. // Use 'normal' priority so that rendering is performed as first when using that priority.
  151. this.on( 'render', () => {
  152. this._render();
  153. // Informs that layout has changed after render.
  154. this.document.fire( 'layoutChanged' );
  155. // Reset the `_hasChangedSinceTheLastRendering` flag after rendering.
  156. this._hasChangedSinceTheLastRendering = false;
  157. } );
  158. // Listen to the selection changes.
  159. this.listenTo( this.document, 'selectionChange', () => {
  160. this._hasChangedSinceTheLastRendering = true;
  161. } );
  162. this.listenTo( this.document, 'selectionChange', () => {
  163. this._hasChangedSinceTheLastRendering = true;
  164. } );
  165. }
  166. /**
  167. * Attaches DOM root element to the view element and enable all observers on that element.
  168. * Also {@link module:engine/view/renderer~Renderer#markToSync mark element} to be synchronized with the view
  169. * what means that all child nodes will be removed and replaced with content of the view root.
  170. *
  171. * This method also will change view element name as the same as tag name of given dom root.
  172. * Name is always transformed to lower case.
  173. *
  174. * @param {Element} domRoot DOM root element.
  175. * @param {String} [name='main'] Name of the root.
  176. */
  177. attachDomRoot( domRoot, name = 'main' ) {
  178. const viewRoot = this.document.getRoot( name );
  179. // Set view root name the same as DOM root tag name.
  180. viewRoot._name = domRoot.tagName.toLowerCase();
  181. this.domRoots.set( name, domRoot );
  182. this.domConverter.bindElements( domRoot, viewRoot );
  183. this._renderer.markToSync( 'children', viewRoot );
  184. this._renderer.domDocuments.add( domRoot.ownerDocument );
  185. viewRoot.on( 'change:children', ( evt, node ) => this._renderer.markToSync( 'children', node ) );
  186. viewRoot.on( 'change:attributes', ( evt, node ) => this._renderer.markToSync( 'attributes', node ) );
  187. viewRoot.on( 'change:text', ( evt, node ) => this._renderer.markToSync( 'text', node ) );
  188. viewRoot.on( 'change', () => {
  189. this._hasChangedSinceTheLastRendering = true;
  190. } );
  191. for ( const observer of this._observers.values() ) {
  192. observer.observe( domRoot, name );
  193. }
  194. }
  195. /**
  196. * Gets DOM root element.
  197. *
  198. * @param {String} [name='main'] Name of the root.
  199. * @returns {Element} DOM root element instance.
  200. */
  201. getDomRoot( name = 'main' ) {
  202. return this.domRoots.get( name );
  203. }
  204. /**
  205. * Creates observer of the given type if not yet created, {@link module:engine/view/observer/observer~Observer#enable enables} it
  206. * and {@link module:engine/view/observer/observer~Observer#observe attaches} to all existing and future
  207. * {@link #domRoots DOM roots}.
  208. *
  209. * Note: Observers are recognized by their constructor (classes). A single observer will be instantiated and used only
  210. * when registered for the first time. This means that features and other components can register a single observer
  211. * multiple times without caring whether it has been already added or not.
  212. *
  213. * @param {Function} Observer The constructor of an observer to add.
  214. * Should create an instance inheriting from {@link module:engine/view/observer/observer~Observer}.
  215. * @returns {module:engine/view/observer/observer~Observer} Added observer instance.
  216. */
  217. addObserver( Observer ) {
  218. let observer = this._observers.get( Observer );
  219. if ( observer ) {
  220. return observer;
  221. }
  222. observer = new Observer( this );
  223. this._observers.set( Observer, observer );
  224. for ( const [ name, domElement ] of this.domRoots ) {
  225. observer.observe( domElement, name );
  226. }
  227. observer.enable();
  228. return observer;
  229. }
  230. /**
  231. * Returns observer of the given type or `undefined` if such observer has not been added yet.
  232. *
  233. * @param {Function} Observer The constructor of an observer to get.
  234. * @returns {module:engine/view/observer/observer~Observer|undefined} Observer instance or undefined.
  235. */
  236. getObserver( Observer ) {
  237. return this._observers.get( Observer );
  238. }
  239. /**
  240. * Disables all added observers.
  241. */
  242. disableObservers() {
  243. for ( const observer of this._observers.values() ) {
  244. observer.disable();
  245. }
  246. }
  247. /**
  248. * Enables all added observers.
  249. */
  250. enableObservers() {
  251. for ( const observer of this._observers.values() ) {
  252. observer.enable();
  253. }
  254. }
  255. /**
  256. * Scrolls the page viewport and {@link #domRoots} with their ancestors to reveal the
  257. * caret, if not already visible to the user.
  258. */
  259. scrollToTheSelection() {
  260. const range = this.document.selection.getFirstRange();
  261. if ( range ) {
  262. scrollViewportToShowTarget( {
  263. target: this.domConverter.viewRangeToDom( range ),
  264. viewportOffset: 20
  265. } );
  266. }
  267. }
  268. /**
  269. * It will focus DOM element representing {@link module:engine/view/editableelement~EditableElement EditableElement}
  270. * that is currently having selection inside.
  271. */
  272. focus() {
  273. if ( !this.document.isFocused ) {
  274. const editable = this.document.selection.editableElement;
  275. if ( editable ) {
  276. this.domConverter.focus( editable );
  277. this.render( { force: true } );
  278. } else {
  279. /**
  280. * Before focusing view document, selection should be placed inside one of the view's editables.
  281. * Normally its selection will be converted from model document (which have default selection), but
  282. * when using view document on its own, we need to manually place selection before focusing it.
  283. *
  284. * @error view-focus-no-selection
  285. */
  286. log.warn( 'view-focus-no-selection: There is no selection in any editable to focus.' );
  287. }
  288. }
  289. }
  290. /**
  291. * The `change()` method is the primary way of changing the view. You should use it to modify any node in the view tree.
  292. * It makes sure that after all changes are made the view is rendered to the DOM. It prevents situations when the DOM is updated
  293. * when the view state is not yet correct. It allows to nest calls one inside another and still performs a single rendering
  294. * after all those changes are made. It also returns the return value of its callback.
  295. *
  296. * const text = view.change( writer => {
  297. * const newText = writer.createText( 'foo' );
  298. * writer.insert( position1, newText );
  299. *
  300. * view.change( writer => {
  301. * writer.insert( position2, writer.createText( 'bar' ) );
  302. * } );
  303. *
  304. * writer.remove( range );
  305. *
  306. * return newText;
  307. * } );
  308. *
  309. * When the outermost change block is done and rendering to the DOM is over the
  310. * {@link module:engine/view/view~View#event:render `View#render`} event is fired.
  311. *
  312. * This method throws a `applying-view-changes-on-rendering` error when
  313. * the change block is used after rendering to the DOM has started.
  314. *
  315. * @param {Function} callback Callback function which may modify the view.
  316. * @returns {*} Value returned by the callback.
  317. */
  318. change( callback ) {
  319. if ( this._renderingInProgress || this._postFixersInProgress ) {
  320. /**
  321. * Thrown when there is an attempt to make changes to the view tree when it is in incorrect state. This may
  322. * cause some unexpected behaviour and inconsistency between the DOM and the view.
  323. * This may be caused by:
  324. *
  325. * * calling {@link #change} or {@link #render} during rendering process,
  326. * * calling {@link #change} or {@link #render} inside of
  327. * {@link module:engine/view/document~Document#registerPostFixer post-fixer function}.
  328. *
  329. * @error cannot-change-view-tree
  330. */
  331. throw new CKEditorError(
  332. 'cannot-change-view-tree: ' +
  333. 'Attempting to make changes to the view when it is in an incorrect state: rendering or post-fixers are in progress. ' +
  334. 'This may cause some unexpected behavior and inconsistency between the DOM and the view.'
  335. );
  336. }
  337. // Recursive call to view.change() method - execute listener immediately.
  338. if ( this._ongoingChange ) {
  339. return callback( this._writer );
  340. }
  341. // This lock will assure that all recursive calls to view.change() will end up in same block - one "render"
  342. // event for all nested calls.
  343. this._ongoingChange = true;
  344. const callbackResult = callback( this._writer );
  345. this._ongoingChange = false;
  346. // This lock is used by editing controller to render changes from outer most model.change() once. As plugins might call
  347. // view.change() inside model.change() block - this will ensures that postfixers and rendering are called once after all changes.
  348. // Also, we don't need to render anything if there're no changes since last rendering.
  349. if ( !this._renderingDisabled && this._hasChangedSinceTheLastRendering ) {
  350. this._postFixersInProgress = true;
  351. this.document._callPostFixers( this._writer );
  352. this._postFixersInProgress = false;
  353. this.fire( 'render' );
  354. }
  355. return callbackResult;
  356. }
  357. /**
  358. * Renders {@link module:engine/view/document~Document view document} to DOM. If any view changes are
  359. * currently in progress, rendering will start after all {@link #change change blocks} are processed.
  360. * If no changes are detected view will not re-render, unless the `options.force` is set to `true`.
  361. *
  362. * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `applying-view-changes-on-rendering` when
  363. * trying to re-render when rendering to DOM has already started.
  364. *
  365. * @param {Object} [options] Rendering options
  366. * @param {Boolean} [options.force=false] A flag ensures that the view will re-render even when nothing has changed.
  367. */
  368. render( options = {} ) {
  369. if ( options.force ) {
  370. this._hasChangedSinceTheLastRendering = true;
  371. }
  372. this.change( () => {} );
  373. }
  374. /**
  375. * Destroys this instance. Makes sure that all observers are destroyed and listeners removed.
  376. */
  377. destroy() {
  378. for ( const observer of this._observers.values() ) {
  379. observer.destroy();
  380. }
  381. this.document.destroy();
  382. this.stopListening();
  383. }
  384. /**
  385. * Creates position at the given location. The location can be specified as:
  386. *
  387. * * a {@link module:engine/view/position~Position position},
  388. * * parent element and offset (offset defaults to `0`),
  389. * * parent element and `'end'` (sets position at the end of that element),
  390. * * {@link module:engine/view/item~Item view item} and `'before'` or `'after'` (sets position before or after given view item).
  391. *
  392. * This method is a shortcut to other constructors such as:
  393. *
  394. * * {@link #createPositionBefore},
  395. * * {@link #createPositionAfter},
  396. *
  397. * @param {module:engine/view/item~Item|module:engine/model/position~Position} itemOrPosition
  398. * @param {Number|'end'|'before'|'after'} [offset] Offset or one of the flags. Used only when
  399. * first parameter is a {@link module:engine/view/item~Item view item}.
  400. */
  401. createPositionAt( itemOrPosition, offset ) {
  402. return Position._createAt( itemOrPosition, offset );
  403. }
  404. /**
  405. * Creates a new position after given view item.
  406. *
  407. * @param {module:engine/view/item~Item} item View item after which the position should be located.
  408. * @returns {module:engine/view/position~Position}
  409. */
  410. createPositionAfter( item ) {
  411. return Position._createAfter( item );
  412. }
  413. /**
  414. * Creates a new position before given view item.
  415. *
  416. * @param {module:engine/view/item~Item} item View item before which the position should be located.
  417. * @returns {module:engine/view/position~Position}
  418. */
  419. createPositionBefore( item ) {
  420. return Position._createBefore( item );
  421. }
  422. /**
  423. * Creates a range spanning from `start` position to `end` position.
  424. *
  425. * **Note:** This factory method creates it's own {@link module:engine/view/position~Position} instances basing on passed values.
  426. *
  427. * @param {module:engine/view/position~Position} start Start position.
  428. * @param {module:engine/view/position~Position} [end] End position. If not set, range will be collapsed at `start` position.
  429. * @returns {module:engine/view/range~Range}
  430. */
  431. createRange( start, end ) {
  432. return new Range( start, end );
  433. }
  434. /**
  435. * Creates a range that starts before given {@link module:engine/view/item~Item view item} and ends after it.
  436. *
  437. * @param {module:engine/view/item~Item} item
  438. * @returns {module:engine/view/range~Range}
  439. */
  440. createRangeOn( item ) {
  441. return Range._createOn( item );
  442. }
  443. /**
  444. * Creates a range inside an {@link module:engine/view/element~Element element} which starts before the first child of
  445. * that element and ends after the last child of that element.
  446. *
  447. * @param {module:engine/view/element~Element} element Element which is a parent for the range.
  448. * @returns {module:engine/view/range~Range}
  449. */
  450. createRangeIn( element ) {
  451. return Range._createIn( element );
  452. }
  453. /**
  454. Creates new {@link module:engine/view/selection~Selection} instance.
  455. *
  456. * // Creates empty selection without ranges.
  457. * const selection = view.createSelection();
  458. *
  459. * // Creates selection at the given range.
  460. * const range = view.createRange( start, end );
  461. * const selection = view.createSelection( range );
  462. *
  463. * // Creates selection at the given ranges
  464. * const ranges = [ view.createRange( start1, end2 ), view.createRange( star2, end2 ) ];
  465. * const selection = view.createSelection( ranges );
  466. *
  467. * // Creates selection from the other selection.
  468. * const otherSelection = view.createSelection();
  469. * const selection = view.createSelection( otherSelection );
  470. *
  471. * // Creates selection from the document selection.
  472. * const selection = view.createSelection( editor.editing.view.document.selection );
  473. *
  474. * // Creates selection at the given position.
  475. * const position = view.createPositionFromPath( root, path );
  476. * const selection = view.createSelection( position );
  477. *
  478. * // Creates collapsed selection at the position of given item and offset.
  479. * const paragraph = view.createContainerElement( 'paragraph' );
  480. * const selection = view.createSelection( paragraph, offset );
  481. *
  482. * // Creates a range inside an {@link module:engine/view/element~Element element} which starts before the
  483. * // first child of that element and ends after the last child of that element.
  484. * const selection = view.createSelection( paragraph, 'in' );
  485. *
  486. * // Creates a range on an {@link module:engine/view/item~Item item} which starts before the item and ends
  487. * // just after the item.
  488. * const selection = view.createSelection( paragraph, 'on' );
  489. *
  490. * `Selection`'s factory method allow passing additional options (`backward`, `fake` and `label`) as the last argument.
  491. *
  492. * // Creates backward selection.
  493. * const selection = view.createSelection( range, { backward: true } );
  494. *
  495. * Fake selection does not render as browser native selection over selected elements and is hidden to the user.
  496. * This way, no native selection UI artifacts are displayed to the user and selection over elements can be
  497. * represented in other way, for example by applying proper CSS class.
  498. *
  499. * Additionally fake's selection label can be provided. It will be used to describe fake selection in DOM
  500. * (and be properly handled by screen readers).
  501. *
  502. * // Creates fake selection with label.
  503. * const selection = view.createSelection( range, { fake: true, label: 'foo' } );
  504. *
  505. * @param {module:engine/view/selection~Selectable} [selectable=null]
  506. * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Offset or place when selectable is an `Item`.
  507. * @param {Object} [options]
  508. * @param {Boolean} [options.backward] Sets this selection instance to be backward.
  509. * @param {Boolean} [options.fake] Sets this selection instance to be marked as `fake`.
  510. * @param {String} [options.label] Label for the fake selection.
  511. * @returns {module:engine/view/selection~Selection}
  512. */
  513. createSelection( selectable, placeOrOffset, options ) {
  514. return new Selection( selectable, placeOrOffset, options );
  515. }
  516. /**
  517. * Renders all changes. In order to avoid triggering the observers (e.g. mutations) all observers are disabled
  518. * before rendering and re-enabled after that.
  519. *
  520. * @private
  521. */
  522. _render() {
  523. this._renderingInProgress = true;
  524. this.disableObservers();
  525. this._renderer.render();
  526. this.enableObservers();
  527. this._renderingInProgress = false;
  528. }
  529. /**
  530. * Fired after a topmost {@link module:engine/view/view~View#change change block} and all
  531. * {@link module:engine/view/document~Document#registerPostFixer post-fixers} are executed.
  532. *
  533. * Actual rendering is performed as a first listener on 'normal' priority.
  534. *
  535. * view.on( 'render', () => {
  536. * // Rendering to the DOM is complete.
  537. * } );
  538. *
  539. * This event is useful when you want to update interface elements after the rendering, e.g. position of the
  540. * balloon panel. If you wants to change view structure use
  541. * {@link module:engine/view/document~Document#registerPostFixer post-fixers}.
  542. *
  543. * @event module:engine/view/view~View#event:render
  544. */
  545. }
  546. mix( View, ObservableMixin );