uielement.js 9.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module engine/view/uielement
  7. */
  8. import Element from './element';
  9. import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  10. import Node from './node';
  11. import { keyCodes } from '@ckeditor/ckeditor5-utils/src/keyboard';
  12. /**
  13. * UI element class. It should be used to represent editing UI which needs to be injected into the editing view
  14. * If possible, you should keep your UI outside the editing view. However, if that is not possible,
  15. * UI elements can be used.
  16. *
  17. * How a UI element is rendered is in your control (you pass a callback to
  18. * {@link module:engine/view/downcastwriter~DowncastWriter#createUIElement `downcastWriter#createUIElement()`}).
  19. * The editor will ignore your UI element – the selection cannot be placed in it, it is skipped (invisible) when
  20. * the user modifies the selection by using arrow keys and the editor does not listen to any mutations which
  21. * happen inside your UI elements.
  22. *
  23. * The limitation is that you cannot convert a model element to a UI element. UI elements need to be
  24. * created for {@link module:engine/model/markercollection~Marker markers} or as additinal elements
  25. * inside normal {@link module:engine/view/containerelement~ContainerElement container elements}.
  26. *
  27. * To create a new UI element use the
  28. * {@link module:engine/view/downcastwriter~DowncastWriter#createUIElement `downcastWriter#createUIElement()`} method.
  29. *
  30. * @extends module:engine/view/element~Element
  31. */
  32. export default class UIElement extends Element {
  33. /**
  34. * Creates new instance of UIElement.
  35. *
  36. * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-uielement-cannot-add` when third parameter is passed,
  37. * to inform that usage of UIElement is incorrect (adding child nodes to UIElement is forbidden).
  38. *
  39. * @see module:engine/view/downcastwriter~DowncastWriter#createUIElement
  40. * @protected
  41. * @param {module:engine/view/document~Document} document The document instance to which this element belongs.
  42. * @param {String} name Node name.
  43. * @param {Object|Iterable} [attributes] Collection of attributes.
  44. * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
  45. * A list of nodes to be inserted into created element.
  46. */
  47. constructor( document, name, attributes, children ) {
  48. super( document, name, attributes, children );
  49. /**
  50. * Returns `null` because filler is not needed for UIElements.
  51. *
  52. * @method #getFillerOffset
  53. * @returns {null} Always returns null.
  54. */
  55. this.getFillerOffset = getFillerOffset;
  56. }
  57. /**
  58. * Checks whether this object is of the given.
  59. *
  60. * uiElement.is( 'uiElement' ); // -> true
  61. * uiElement.is( 'element' ); // -> true
  62. * uiElement.is( 'node' ); // -> true
  63. * uiElement.is( 'view:uiElement' ); // -> true
  64. * uiElement.is( 'view:element' ); // -> true
  65. * uiElement.is( 'view:node' ); // -> true
  66. *
  67. * uiElement.is( 'model:element' ); // -> false
  68. * uiElement.is( 'documentFragment' ); // -> false
  69. *
  70. * Assuming that the object being checked is an ui element, you can also check its
  71. * {@link module:engine/view/uielement~UIElement#name name}:
  72. *
  73. * uiElement.is( 'element', 'span' ); // -> true if this is a span ui element
  74. * uiElement.is( 'uiElement', 'span' ); // -> same as above
  75. * text.is( 'element', 'span' ); -> false
  76. *
  77. * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
  78. *
  79. * @param {String} type Type to check.
  80. * @param {String} [name] Element name.
  81. * @returns {Boolean}
  82. */
  83. is( type, name = null ) {
  84. if ( !name ) {
  85. return type === 'uiElement' || type === 'view:uiElement' ||
  86. // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
  87. type === 'element' || type === 'view:element' ||
  88. type === 'node' || type === 'view:node';
  89. } else {
  90. return name === this.name && (
  91. type === 'uiElement' || type === 'view:uiElement' ||
  92. type === 'element' || type === 'view:element'
  93. );
  94. }
  95. }
  96. /**
  97. * Overrides {@link module:engine/view/element~Element#_insertChild} method.
  98. * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-uielement-cannot-add` to prevent adding any child nodes
  99. * to UIElement.
  100. *
  101. * @protected
  102. */
  103. _insertChild( index, nodes ) {
  104. if ( nodes && ( nodes instanceof Node || Array.from( nodes ).length > 0 ) ) {
  105. /**
  106. * Cannot add children to {@link module:engine/view/uielement~UIElement}.
  107. *
  108. * @error view-uielement-cannot-add
  109. */
  110. throw new CKEditorError( 'view-uielement-cannot-add', this );
  111. }
  112. }
  113. /**
  114. * Renders this {@link module:engine/view/uielement~UIElement} to DOM. This method is called by
  115. * {@link module:engine/view/domconverter~DomConverter}.
  116. * Do not use inheritance to create custom rendering method, replace `render()` method instead:
  117. *
  118. * const myUIElement = downcastWriter.createUIElement( 'span' );
  119. * myUIElement.render = function( domDocument ) {
  120. * const domElement = this.toDomElement( domDocument );
  121. * domElement.innerHTML = '<b>this is ui element</b>';
  122. *
  123. * return domElement;
  124. * };
  125. *
  126. * If changes in your UI element should trigger some editor UI update you should call
  127. * the {@link module:core/editor/editorui~EditorUI#update `editor.ui.update()`} method
  128. * after rendering your UI element.
  129. *
  130. * @param {Document} domDocument
  131. * @returns {HTMLElement}
  132. */
  133. render( domDocument ) {
  134. return this.toDomElement( domDocument );
  135. }
  136. /**
  137. * Creates DOM element based on this view UIElement.
  138. * Note that each time this method is called new DOM element is created.
  139. *
  140. * @param {Document} domDocument
  141. * @returns {HTMLElement}
  142. */
  143. toDomElement( domDocument ) {
  144. const domElement = domDocument.createElement( this.name );
  145. for ( const key of this.getAttributeKeys() ) {
  146. domElement.setAttribute( key, this.getAttribute( key ) );
  147. }
  148. return domElement;
  149. }
  150. }
  151. /**
  152. * This function injects UI element handling to the given {@link module:engine/view/document~Document document}.
  153. *
  154. * A callback is added to {@link module:engine/view/document~Document#event:keydown document keydown event}.
  155. * The callback handles the situation when right arrow key is pressed and selection is collapsed before a UI element.
  156. * Without this handler, it would be impossible to "jump over" UI element using right arrow key.
  157. *
  158. * @param {module:engine/view/view~View} view View controller to which the quirks handling will be injected.
  159. */
  160. export function injectUiElementHandling( view ) {
  161. view.document.on( 'keydown', ( evt, data ) => jumpOverUiElement( evt, data, view.domConverter ) );
  162. }
  163. // Returns `null` because block filler is not needed for UIElements.
  164. //
  165. // @returns {null}
  166. function getFillerOffset() {
  167. return null;
  168. }
  169. // Selection cannot be placed in a `UIElement`. Whenever it is placed there, it is moved before it. This
  170. // causes a situation when it is impossible to jump over `UIElement` using right arrow key, because the selection
  171. // ends up in ui element (in DOM) and is moved back to the left. This handler fixes this situation.
  172. function jumpOverUiElement( evt, data, domConverter ) {
  173. if ( data.keyCode == keyCodes.arrowright ) {
  174. const domSelection = data.domTarget.ownerDocument.defaultView.getSelection();
  175. const domSelectionCollapsed = domSelection.rangeCount == 1 && domSelection.getRangeAt( 0 ).collapsed;
  176. // Jump over UI element if selection is collapsed or shift key is pressed. These are the cases when selection would extend.
  177. if ( domSelectionCollapsed || data.shiftKey ) {
  178. const domParent = domSelection.focusNode;
  179. const domOffset = domSelection.focusOffset;
  180. const viewPosition = domConverter.domPositionToView( domParent, domOffset );
  181. // In case if dom element is not converted to view or is not mapped or something. Happens for example in some tests.
  182. if ( viewPosition === null ) {
  183. return;
  184. }
  185. // Skip all following ui elements.
  186. let jumpedOverAnyUiElement = false;
  187. const nextViewPosition = viewPosition.getLastMatchingPosition( value => {
  188. if ( value.item.is( 'uiElement' ) ) {
  189. // Remember that there was at least one ui element.
  190. jumpedOverAnyUiElement = true;
  191. }
  192. // Jump over ui elements, jump over empty attribute elements, move up from inside of attribute element.
  193. if ( value.item.is( 'uiElement' ) || value.item.is( 'attributeElement' ) ) {
  194. return true;
  195. }
  196. // Don't jump over text or don't get out of container element.
  197. return false;
  198. } );
  199. // If anything has been skipped, fix position.
  200. // This `if` could be possibly omitted but maybe it is better not to mess with DOM selection if not needed.
  201. if ( jumpedOverAnyUiElement ) {
  202. const newDomPosition = domConverter.viewPositionToDom( nextViewPosition );
  203. if ( domSelectionCollapsed ) {
  204. // Selection was collapsed, so collapse it at further position.
  205. domSelection.collapse( newDomPosition.parent, newDomPosition.offset );
  206. } else {
  207. // Selection was not collapse, so extend it instead of collapsing.
  208. domSelection.extend( newDomPosition.parent, newDomPosition.offset );
  209. }
  210. }
  211. }
  212. }
  213. }