uielement.js 9.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237
  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( 'span' ); // -> true if this is a span ui element
  74. * uiElement.is( 'uiElement', 'span' ); // -> same as above
  75. * text.is( '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 when `name` parameter is present.
  80. * Otherwise, it acts like the `name` parameter.
  81. * @param {String} [name] Element name.
  82. * @returns {Boolean}
  83. */
  84. is( type, name = null ) {
  85. if ( !name ) {
  86. return type === 'uiElement' || type === 'view:uiElement' ||
  87. // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
  88. type === this.name || type === 'view:' + this.name ||
  89. type === 'element' || type === 'view:element' ||
  90. type === 'node' || type === 'view:node';
  91. } else {
  92. return name === this.name && (
  93. type === 'uiElement' || type === 'view:uiElement' ||
  94. type === 'element' || type === 'view:element'
  95. );
  96. }
  97. }
  98. /**
  99. * Overrides {@link module:engine/view/element~Element#_insertChild} method.
  100. * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-uielement-cannot-add` to prevent adding any child nodes
  101. * to UIElement.
  102. *
  103. * @protected
  104. */
  105. _insertChild( index, nodes ) {
  106. if ( nodes && ( nodes instanceof Node || Array.from( nodes ).length > 0 ) ) {
  107. /**
  108. * Cannot add children to {@link module:engine/view/uielement~UIElement}.
  109. *
  110. * @error view-uielement-cannot-add
  111. */
  112. throw new CKEditorError( 'view-uielement-cannot-add: Cannot add child nodes to UIElement instance.', this );
  113. }
  114. }
  115. /**
  116. * Renders this {@link module:engine/view/uielement~UIElement} to DOM. This method is called by
  117. * {@link module:engine/view/domconverter~DomConverter}.
  118. * Do not use inheritance to create custom rendering method, replace `render()` method instead:
  119. *
  120. * const myUIElement = downcastWriter.createUIElement( 'span' );
  121. * myUIElement.render = function( domDocument ) {
  122. * const domElement = this.toDomElement( domDocument );
  123. * domElement.innerHTML = '<b>this is ui element</b>';
  124. *
  125. * return domElement;
  126. * };
  127. *
  128. * If changes in your UI element should trigger some editor UI update you should call
  129. * the {@link module:core/editor/editorui~EditorUI#update `editor.ui.update()`} method
  130. * after rendering your UI element.
  131. *
  132. * @param {Document} domDocument
  133. * @returns {HTMLElement}
  134. */
  135. render( domDocument ) {
  136. return this.toDomElement( domDocument );
  137. }
  138. /**
  139. * Creates DOM element based on this view UIElement.
  140. * Note that each time this method is called new DOM element is created.
  141. *
  142. * @param {Document} domDocument
  143. * @returns {HTMLElement}
  144. */
  145. toDomElement( domDocument ) {
  146. const domElement = domDocument.createElement( this.name );
  147. for ( const key of this.getAttributeKeys() ) {
  148. domElement.setAttribute( key, this.getAttribute( key ) );
  149. }
  150. return domElement;
  151. }
  152. }
  153. /**
  154. * This function injects UI element handling to the given {@link module:engine/view/document~Document document}.
  155. *
  156. * A callback is added to {@link module:engine/view/document~Document#event:keydown document keydown event}.
  157. * The callback handles the situation when right arrow key is pressed and selection is collapsed before a UI element.
  158. * Without this handler, it would be impossible to "jump over" UI element using right arrow key.
  159. *
  160. * @param {module:engine/view/view~View} view View controller to which the quirks handling will be injected.
  161. */
  162. export function injectUiElementHandling( view ) {
  163. view.document.on( 'keydown', ( evt, data ) => jumpOverUiElement( evt, data, view.domConverter ) );
  164. }
  165. // Returns `null` because block filler is not needed for UIElements.
  166. //
  167. // @returns {null}
  168. function getFillerOffset() {
  169. return null;
  170. }
  171. // Selection cannot be placed in a `UIElement`. Whenever it is placed there, it is moved before it. This
  172. // causes a situation when it is impossible to jump over `UIElement` using right arrow key, because the selection
  173. // ends up in ui element (in DOM) and is moved back to the left. This handler fixes this situation.
  174. function jumpOverUiElement( evt, data, domConverter ) {
  175. if ( data.keyCode == keyCodes.arrowright ) {
  176. const domSelection = data.domTarget.ownerDocument.defaultView.getSelection();
  177. const domSelectionCollapsed = domSelection.rangeCount == 1 && domSelection.getRangeAt( 0 ).collapsed;
  178. // Jump over UI element if selection is collapsed or shift key is pressed. These are the cases when selection would extend.
  179. if ( domSelectionCollapsed || data.shiftKey ) {
  180. const domParent = domSelection.focusNode;
  181. const domOffset = domSelection.focusOffset;
  182. const viewPosition = domConverter.domPositionToView( domParent, domOffset );
  183. // In case if dom element is not converted to view or is not mapped or something. Happens for example in some tests.
  184. if ( viewPosition === null ) {
  185. return;
  186. }
  187. // Skip all following ui elements.
  188. let jumpedOverAnyUiElement = false;
  189. const nextViewPosition = viewPosition.getLastMatchingPosition( value => {
  190. if ( value.item.is( 'uiElement' ) ) {
  191. // Remember that there was at least one ui element.
  192. jumpedOverAnyUiElement = true;
  193. }
  194. // Jump over ui elements, jump over empty attribute elements, move up from inside of attribute element.
  195. if ( value.item.is( 'uiElement' ) || value.item.is( 'attributeElement' ) ) {
  196. return true;
  197. }
  198. // Don't jump over text or don't get out of container element.
  199. return false;
  200. } );
  201. // If anything has been skipped, fix position.
  202. // This `if` could be possibly omitted but maybe it is better not to mess with DOM selection if not needed.
  203. if ( jumpedOverAnyUiElement ) {
  204. const newDomPosition = domConverter.viewPositionToDom( nextViewPosition );
  205. if ( domSelectionCollapsed ) {
  206. // Selection was collapsed, so collapse it at further position.
  207. domSelection.collapse( newDomPosition.parent, newDomPosition.offset );
  208. } else {
  209. // Selection was not collapse, so extend it instead of collapsing.
  210. domSelection.extend( newDomPosition.parent, newDomPosition.offset );
  211. }
  212. }
  213. }
  214. }
  215. }