view.js 15 KB

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