view.js 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415
  1. /**
  2. * @license Copyright (c) 2003-2018, 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 Writer from './writer';
  10. import Renderer from './renderer';
  11. import DomConverter from './domconverter';
  12. import MutationObserver from './observer/mutationobserver';
  13. import KeyObserver from './observer/keyobserver';
  14. import FakeSelectionObserver from './observer/fakeselectionobserver';
  15. import SelectionObserver from './observer/selectionobserver';
  16. import FocusObserver from './observer/focusobserver';
  17. import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
  18. import log from '@ckeditor/ckeditor5-utils/src/log';
  19. import mix from '@ckeditor/ckeditor5-utils/src/mix';
  20. import { scrollViewportToShowTarget } from '@ckeditor/ckeditor5-utils/src/dom/scroll';
  21. import { injectUiElementHandling } from './uielement';
  22. import { injectQuirksHandling } from './filler';
  23. import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  24. /**
  25. * Editor's view controller class. Its main responsibility is DOM - View management for editing purposes, to provide
  26. * abstraction over the DOM structure and events and hide all browsers quirks.
  27. *
  28. * View controller renders view document to DOM whenever view structure changes. To determine when view can be rendered,
  29. * all changes need to be done using the {@link module:engine/view/view~View#change} method, using
  30. * {@link module:engine/view/writer~Writer}:
  31. *
  32. * view.change( writer => {
  33. * writer.insert( position, writer.createText( 'foo' ) );
  34. * } );
  35. *
  36. * View controller also register {@link module:engine/view/observer/observer~Observer observers} which observes changes
  37. * on DOM and fire events on the {@link module:engine/view/document~Document Document}.
  38. * Note that the following observers are added by the class constructor and are always available:
  39. *
  40. * * {@link module:engine/view/observer/mutationobserver~MutationObserver},
  41. * * {@link module:engine/view/observer/selectionobserver~SelectionObserver},
  42. * * {@link module:engine/view/observer/focusobserver~FocusObserver},
  43. * * {@link module:engine/view/observer/keyobserver~KeyObserver},
  44. * * {@link module:engine/view/observer/fakeselectionobserver~FakeSelectionObserver}.
  45. *
  46. * This class also {@link module:engine/view/view~View#attachDomRoot bind DOM and View elements}.
  47. *
  48. * If you do not need full DOM - View management, and want to only transform the tree of view elements to the DOM
  49. * elements you do not need this controller, you can use the {@link module:engine/view/domconverter~DomConverter DomConverter}.
  50. *
  51. * @mixes module:utils/observablemixin~ObservableMixin
  52. */
  53. export default class View {
  54. constructor() {
  55. /**
  56. * Instance of the {@link module:engine/view/document~Document} associated with this view controller.
  57. *
  58. * @readonly
  59. * @member {module:engine/view/document~Document} module:engine/view/view~View#document
  60. */
  61. this.document = new Document();
  62. /**
  63. * Instance of the {@link module:engine/view/domconverter~DomConverter domConverter} use by
  64. * {@link module:engine/view/view~View#renderer renderer}
  65. * and {@link module:engine/view/observer/observer~Observer observers}.
  66. *
  67. * @readonly
  68. * @member {module:engine/view/domconverter~DomConverter} module:engine/view/view~View#domConverter
  69. */
  70. this.domConverter = new DomConverter();
  71. /**
  72. * Instance of the {@link module:engine/view/renderer~Renderer renderer}.
  73. *
  74. * @protected
  75. * @member {module:engine/view/renderer~Renderer} module:engine/view/view~View#renderer
  76. */
  77. this._renderer = new Renderer( this.domConverter, this.document.selection );
  78. this._renderer.bind( 'isFocused' ).to( this.document );
  79. /**
  80. * Roots of the DOM tree. Map on the `HTMLElement`s with roots names as keys.
  81. *
  82. * @readonly
  83. * @member {Map} module:engine/view/view~View#domRoots
  84. */
  85. this.domRoots = new Map();
  86. /**
  87. * Map of registered {@link module:engine/view/observer/observer~Observer observers}.
  88. *
  89. * @private
  90. * @member {Map.<Function, module:engine/view/observer/observer~Observer>} module:engine/view/view~View#_observers
  91. */
  92. this._observers = new Map();
  93. /**
  94. * Is set to `true` when {@link #change view changes} are currently in progress.
  95. *
  96. * @private
  97. * @member {Boolean} module:engine/view/view~View#_ongoingChange
  98. */
  99. this._ongoingChange = false;
  100. /**
  101. * Is set to `true` when rendering view to DOM was started.
  102. * This is used to check whether view document can accept changes in current state.
  103. * From the moment when rendering to DOM is stared view tree is locked to prevent changes that will not be
  104. * reflected in the DOM.
  105. *
  106. * @private
  107. * @member {Boolean} module:engine/view/view~View#_renderingStarted
  108. */
  109. this._renderingStarted = false;
  110. /**
  111. * Writer instance used in {@link #change change method) callbacks.
  112. *
  113. * @private
  114. * @member {module:engine/view/writer~Writer} module:engine/view/view~View#_writer
  115. */
  116. this._writer = new Writer( this.document );
  117. // Add default observers.
  118. this.addObserver( MutationObserver );
  119. this.addObserver( SelectionObserver );
  120. this.addObserver( FocusObserver );
  121. this.addObserver( KeyObserver );
  122. this.addObserver( FakeSelectionObserver );
  123. // Inject quirks handlers.
  124. injectQuirksHandling( this );
  125. injectUiElementHandling( this );
  126. // Use 'low` priority so that all listeners on 'normal` priority will be executed before.
  127. this.on( 'render', () => {
  128. this._render();
  129. }, { priority: 'low' } );
  130. }
  131. /**
  132. * Attaches DOM root element to the view element and enable all observers on that element.
  133. * Also {@link module:engine/view/renderer~Renderer#markToSync mark element} to be synchronized with the view
  134. * what means that all child nodes will be removed and replaced with content of the view root.
  135. *
  136. * This method also will change view element name as the same as tag name of given dom root.
  137. * Name is always transformed to lower case.
  138. *
  139. * @param {Element} domRoot DOM root element.
  140. * @param {String} [name='main'] Name of the root.
  141. */
  142. attachDomRoot( domRoot, name = 'main' ) {
  143. const viewRoot = this.document.getRoot( name );
  144. // Set view root name the same as DOM root tag name.
  145. viewRoot._name = domRoot.tagName.toLowerCase();
  146. this.domRoots.set( name, domRoot );
  147. this.domConverter.bindElements( domRoot, viewRoot );
  148. this._renderer.markToSync( 'children', viewRoot );
  149. this._renderer.domDocuments.add( domRoot.ownerDocument );
  150. viewRoot.on( 'change:children', ( evt, node ) => this._renderer.markToSync( 'children', node ) );
  151. viewRoot.on( 'change:attributes', ( evt, node ) => this._renderer.markToSync( 'attributes', node ) );
  152. viewRoot.on( 'change:text', ( evt, node ) => this._renderer.markToSync( 'text', node ) );
  153. for ( const observer of this._observers.values() ) {
  154. observer.observe( domRoot, name );
  155. }
  156. }
  157. /**
  158. * Gets DOM root element.
  159. *
  160. * @param {String} [name='main'] Name of the root.
  161. * @returns {Element} DOM root element instance.
  162. */
  163. getDomRoot( name = 'main' ) {
  164. return this.domRoots.get( name );
  165. }
  166. /**
  167. * Creates observer of the given type if not yet created, {@link module:engine/view/observer/observer~Observer#enable enables} it
  168. * and {@link module:engine/view/observer/observer~Observer#observe attaches} to all existing and future
  169. * {@link #domRoots DOM roots}.
  170. *
  171. * Note: Observers are recognized by their constructor (classes). A single observer will be instantiated and used only
  172. * when registered for the first time. This means that features and other components can register a single observer
  173. * multiple times without caring whether it has been already added or not.
  174. *
  175. * @param {Function} Observer The constructor of an observer to add.
  176. * Should create an instance inheriting from {@link module:engine/view/observer/observer~Observer}.
  177. * @returns {module:engine/view/observer/observer~Observer} Added observer instance.
  178. */
  179. addObserver( Observer ) {
  180. let observer = this._observers.get( Observer );
  181. if ( observer ) {
  182. return observer;
  183. }
  184. observer = new Observer( this );
  185. this._observers.set( Observer, observer );
  186. for ( const [ name, domElement ] of this.domRoots ) {
  187. observer.observe( domElement, name );
  188. }
  189. observer.enable();
  190. return observer;
  191. }
  192. /**
  193. * Returns observer of the given type or `undefined` if such observer has not been added yet.
  194. *
  195. * @param {Function} Observer The constructor of an observer to get.
  196. * @returns {module:engine/view/observer/observer~Observer|undefined} Observer instance or undefined.
  197. */
  198. getObserver( Observer ) {
  199. return this._observers.get( Observer );
  200. }
  201. /**
  202. * Disables all added observers.
  203. */
  204. disableObservers() {
  205. for ( const observer of this._observers.values() ) {
  206. observer.disable();
  207. }
  208. }
  209. /**
  210. * Enables all added observers.
  211. */
  212. enableObservers() {
  213. for ( const observer of this._observers.values() ) {
  214. observer.enable();
  215. }
  216. }
  217. /**
  218. * Scrolls the page viewport and {@link #domRoots} with their ancestors to reveal the
  219. * caret, if not already visible to the user.
  220. */
  221. scrollToTheSelection() {
  222. const range = this.document.selection.getFirstRange();
  223. if ( range ) {
  224. scrollViewportToShowTarget( {
  225. target: this.domConverter.viewRangeToDom( range ),
  226. viewportOffset: 20
  227. } );
  228. }
  229. }
  230. /**
  231. * It will focus DOM element representing {@link module:engine/view/editableelement~EditableElement EditableElement}
  232. * that is currently having selection inside.
  233. */
  234. focus() {
  235. if ( !this.document.isFocused ) {
  236. const editable = this.document.selection.editableElement;
  237. if ( editable ) {
  238. this.domConverter.focus( editable );
  239. this.render();
  240. } else {
  241. /**
  242. * Before focusing view document, selection should be placed inside one of the view's editables.
  243. * Normally its selection will be converted from model document (which have default selection), but
  244. * when using view document on its own, we need to manually place selection before focusing it.
  245. *
  246. * @error view-focus-no-selection
  247. */
  248. log.warn( 'view-focus-no-selection: There is no selection in any editable to focus.' );
  249. }
  250. }
  251. }
  252. /**
  253. * Change method is the primary way of changing the view. You should use it to modify any node in the view tree.
  254. * It makes sure that after all changes are made view is rendered to DOM. It prevents situations when DOM is updated
  255. * when view state is not yet correct. It allows to nest calls one inside another and still perform single rendering
  256. * after all changes are applied.
  257. *
  258. * view.change( writer => {
  259. * writer.insert( position1, writer.createText( 'foo' ) );
  260. *
  261. * view.change( writer => {
  262. * writer.insert( position2, writer.createText( 'bar' ) );
  263. * } );
  264. *
  265. * writer.remove( range );
  266. * } );
  267. *
  268. * Change block is executed immediately.
  269. *
  270. * When the outermost change block is done and rendering to DOM is over it fires
  271. * {@link module:engine/view/view~View#event:render} event.
  272. *
  273. * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `applying-view-changes-on-rendering` when
  274. * change block is used after rendering to DOM has started.
  275. *
  276. * @param {Function} callback Callback function which may modify the view.
  277. */
  278. change( callback ) {
  279. // Check if change is performed in correct moment.
  280. this._assertRenderingInProgress();
  281. // If other changes are in progress wait with rendering until every ongoing change is over.
  282. if ( this._ongoingChange ) {
  283. callback( this._writer );
  284. } else {
  285. this._ongoingChange = true;
  286. callback( this._writer );
  287. this.fire( 'render' );
  288. this._ongoingChange = false;
  289. this._renderingStarted = false;
  290. }
  291. }
  292. /**
  293. * Renders {@link module:engine/view/document~Document view document} to DOM. If any view changes are
  294. * currently in progress, rendering will start after all {@link #change change blocks} are processed.
  295. *
  296. * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `applying-view-changes-on-rendering` when
  297. * trying to re-render when rendering to DOM has already started.
  298. */
  299. render() {
  300. // Check if rendering is performed in correct moment.
  301. this._assertRenderingInProgress();
  302. // Render only if no ongoing changes are in progress. If there are some, view document will be rendered after all
  303. // changes are done. This way view document will not be rendered in the middle of some changes.
  304. if ( !this._ongoingChange ) {
  305. this.fire( 'render' );
  306. this._renderingStarted = false;
  307. }
  308. }
  309. /**
  310. * Destroys this instance. Makes sure that all observers are destroyed and listeners removed.
  311. */
  312. destroy() {
  313. for ( const observer of this._observers.values() ) {
  314. observer.destroy();
  315. }
  316. this.stopListening();
  317. }
  318. /**
  319. * Renders all changes. In order to avoid triggering the observers (e.g. mutations) all observers are disabled
  320. * before rendering and re-enabled after that.
  321. *
  322. * @private
  323. */
  324. _render() {
  325. this._renderingStarted = true;
  326. this.disableObservers();
  327. this._renderer.render();
  328. this.enableObservers();
  329. }
  330. /**
  331. * Throws `applying-view-changes-on-rendering` error when trying to modify or re-render view tree when rendering is
  332. * already started
  333. *
  334. * @private
  335. */
  336. _assertRenderingInProgress() {
  337. if ( this._renderingStarted ) {
  338. /**
  339. * There is an attempt to make changes in the view tree after the rendering process
  340. * has started. This may cause unexpected behaviour and inconsistency between the DOM and the view.
  341. * This may be caused by:
  342. * * calling `view.change()` or `view.render()` methods during rendering process,
  343. * * calling `view.change()` or `view.render()` methods in callbacks to
  344. * {module:engine/view/document~Document#event:change view document change event) on `low` priority, after
  345. * rendering is over for current `change` block.
  346. *
  347. * @error applying-view-changes-on-rendering
  348. */
  349. throw new CKEditorError(
  350. 'applying-view-changes-on-rendering: ' +
  351. 'Attempting to make changes in the view during rendering process. ' +
  352. 'This may cause some unexpected behaviour and inconsistency between the DOM and the view.'
  353. );
  354. }
  355. }
  356. /**
  357. * Fired after a topmost {@link module:engine/view/view~View#change change block} is finished and the DOM rendering has
  358. * been executed.
  359. *
  360. * Actual rendering is performed on 'low' priority. This means that all listeners on 'normal' and above priorities
  361. * will be executed after changes made to view tree but before rendering to the DOM. Use `low` priority for callbacks that
  362. * should be executed after rendering to the DOM.
  363. *
  364. * @event module:engine/view/view~View#event:render
  365. */
  366. }
  367. mix( View, ObservableMixin );