widget.js 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449
  1. /**
  2. * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md.
  4. */
  5. /**
  6. * @module widget/widget
  7. */
  8. import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
  9. import MouseObserver from '@ckeditor/ckeditor5-engine/src/view/observer/mouseobserver';
  10. import { getLabel, isWidget, WIDGET_SELECTED_CLASS_NAME } from './utils';
  11. import { getCode, keyCodes, parseKeystroke } from '@ckeditor/ckeditor5-utils/src/keyboard';
  12. import '../theme/widget.css';
  13. const selectAllKeystrokeCode = parseKeystroke( 'Ctrl+A' );
  14. /**
  15. * The widget plugin. It enables base support for widgets.
  16. *
  17. * See {@glink api/widget package page} for more details and documentation.
  18. *
  19. * This plugin enables multiple behaviors required by widgets:
  20. *
  21. * * The model to view selection converter for the editing pipeline (it handles widget custom selection rendering).
  22. * If a converted selection wraps around a widget element, that selection is marked as
  23. * {@link module:engine/view/selection~Selection#isFake fake}. Additionally, the `ck-widget_selected` CSS class
  24. * is added to indicate that widget has been selected.
  25. * * The mouse and keyboard events handling on and around widget elements.
  26. *
  27. * @extends module:core/plugin~Plugin.
  28. */
  29. export default class Widget extends Plugin {
  30. /**
  31. * @inheritDoc
  32. */
  33. static get pluginName() {
  34. return 'Widget';
  35. }
  36. /**
  37. * @inheritDoc
  38. */
  39. init() {
  40. const view = this.editor.editing.view;
  41. const viewDocument = view.document;
  42. /**
  43. * Holds previously selected widgets.
  44. *
  45. * @private
  46. * @type {Set.<module:engine/view/element~Element>}
  47. */
  48. this._previouslySelected = new Set();
  49. // Model to view selection converter.
  50. // Converts selection placed over widget element to fake selection
  51. this.editor.editing.downcastDispatcher.on( 'selection', ( evt, data, conversionApi ) => {
  52. // Remove selected class from previously selected widgets.
  53. this._clearPreviouslySelectedWidgets( conversionApi.writer );
  54. const viewWriter = conversionApi.writer;
  55. const viewSelection = viewWriter.document.selection;
  56. const selectedElement = viewSelection.getSelectedElement();
  57. let lastMarked = null;
  58. for ( const range of viewSelection.getRanges() ) {
  59. for ( const value of range ) {
  60. const node = value.item;
  61. // Do not mark nested widgets in selected one. See: #57.
  62. if ( isWidget( node ) && !isChild( node, lastMarked ) ) {
  63. viewWriter.addClass( WIDGET_SELECTED_CLASS_NAME, node );
  64. this._previouslySelected.add( node );
  65. lastMarked = node;
  66. // Check if widget is a single element selected.
  67. if ( node == selectedElement ) {
  68. viewWriter.setSelection( viewSelection.getRanges(), { fake: true, label: getLabel( selectedElement ) } );
  69. }
  70. }
  71. }
  72. }
  73. }, { priority: 'low' } );
  74. // If mouse down is pressed on widget - create selection over whole widget.
  75. view.addObserver( MouseObserver );
  76. this.listenTo( viewDocument, 'mousedown', ( ...args ) => this._onMousedown( ...args ) );
  77. // Handle custom keydown behaviour.
  78. this.listenTo( viewDocument, 'keydown', ( ...args ) => this._onKeydown( ...args ), { priority: 'high' } );
  79. // Handle custom delete behaviour.
  80. this.listenTo( viewDocument, 'delete', ( evt, data ) => {
  81. if ( this._handleDelete( data.direction == 'forward' ) ) {
  82. data.preventDefault();
  83. evt.stop();
  84. }
  85. }, { priority: 'high' } );
  86. }
  87. /**
  88. * Handles {@link module:engine/view/document~Document#event:mousedown mousedown} events on widget elements.
  89. *
  90. * @private
  91. * @param {module:utils/eventinfo~EventInfo} eventInfo
  92. * @param {module:engine/view/observer/domeventdata~DomEventData} domEventData
  93. */
  94. _onMousedown( eventInfo, domEventData ) {
  95. const editor = this.editor;
  96. const view = editor.editing.view;
  97. const viewDocument = view.document;
  98. let element = domEventData.target;
  99. // Do nothing if inside nested editable.
  100. if ( isInsideNestedEditable( element ) ) {
  101. return;
  102. }
  103. // If target is not a widget element - check if one of the ancestors is.
  104. if ( !isWidget( element ) ) {
  105. element = element.findAncestor( isWidget );
  106. if ( !element ) {
  107. return;
  108. }
  109. }
  110. domEventData.preventDefault();
  111. // Focus editor if is not focused already.
  112. if ( !viewDocument.isFocused ) {
  113. view.focus();
  114. }
  115. // Create model selection over widget.
  116. const modelElement = editor.editing.mapper.toModelElement( element );
  117. this._setSelectionOverElement( modelElement );
  118. }
  119. /**
  120. * Handles {@link module:engine/view/document~Document#event:keydown keydown} events.
  121. *
  122. * @private
  123. * @param {module:utils/eventinfo~EventInfo} eventInfo
  124. * @param {module:engine/view/observer/domeventdata~DomEventData} domEventData
  125. */
  126. _onKeydown( eventInfo, domEventData ) {
  127. const keyCode = domEventData.keyCode;
  128. const isForward = keyCode == keyCodes.delete || keyCode == keyCodes.arrowdown || keyCode == keyCodes.arrowright;
  129. let wasHandled = false;
  130. // Checks if the keys were handled and then prevents the default event behaviour and stops
  131. // the propagation.
  132. if ( isArrowKeyCode( keyCode ) ) {
  133. wasHandled = this._handleArrowKeys( isForward );
  134. } else if ( isSelectAllKeyCode( domEventData ) ) {
  135. wasHandled = this._selectAllNestedEditableContent() || this._selectAllContent();
  136. } else if ( keyCode === keyCodes.enter ) {
  137. wasHandled = this._handleEnterKey( domEventData.shiftKey );
  138. }
  139. if ( wasHandled ) {
  140. domEventData.preventDefault();
  141. eventInfo.stop();
  142. }
  143. }
  144. /**
  145. * Handles delete keys: backspace and delete.
  146. *
  147. * @private
  148. * @param {Boolean} isForward Set to true if delete was performed in forward direction.
  149. * @returns {Boolean|undefined} Returns `true` if keys were handled correctly.
  150. */
  151. _handleDelete( isForward ) {
  152. // Do nothing when the read only mode is enabled.
  153. if ( this.editor.isReadOnly ) {
  154. return;
  155. }
  156. const modelDocument = this.editor.model.document;
  157. const modelSelection = modelDocument.selection;
  158. // Do nothing on non-collapsed selection.
  159. if ( !modelSelection.isCollapsed ) {
  160. return;
  161. }
  162. const objectElement = this._getObjectElementNextToSelection( isForward );
  163. if ( objectElement ) {
  164. this.editor.model.change( writer => {
  165. let previousNode = modelSelection.anchor.parent;
  166. // Remove previous element if empty.
  167. while ( previousNode.isEmpty ) {
  168. const nodeToRemove = previousNode;
  169. previousNode = nodeToRemove.parent;
  170. writer.remove( nodeToRemove );
  171. }
  172. this._setSelectionOverElement( objectElement );
  173. } );
  174. return true;
  175. }
  176. }
  177. /**
  178. * Handles arrow keys.
  179. *
  180. * @private
  181. * @param {Boolean} isForward Set to true if arrow key should be handled in forward direction.
  182. * @returns {Boolean|undefined} Returns `true` if keys were handled correctly.
  183. */
  184. _handleArrowKeys( isForward ) {
  185. const model = this.editor.model;
  186. const schema = model.schema;
  187. const modelDocument = model.document;
  188. const modelSelection = modelDocument.selection;
  189. const objectElement = modelSelection.getSelectedElement();
  190. // If object element is selected.
  191. if ( objectElement && schema.isObject( objectElement ) ) {
  192. const position = isForward ? modelSelection.getLastPosition() : modelSelection.getFirstPosition();
  193. const newRange = schema.getNearestSelectionRange( position, isForward ? 'forward' : 'backward' );
  194. if ( newRange ) {
  195. model.change( writer => {
  196. writer.setSelection( newRange );
  197. } );
  198. }
  199. return true;
  200. }
  201. // If selection is next to object element.
  202. // Return if not collapsed.
  203. if ( !modelSelection.isCollapsed ) {
  204. return;
  205. }
  206. const objectElement2 = this._getObjectElementNextToSelection( isForward );
  207. if ( !!objectElement2 && schema.isObject( objectElement2 ) ) {
  208. this._setSelectionOverElement( objectElement2 );
  209. return true;
  210. }
  211. }
  212. /**
  213. * Handles the enter key, giving users and access to positions in the editable directly before
  214. * (<kbd>Shift</kbd>+<kbd>Enter</kbd>) or after (<kbd>Enter</kbd>) the selected widget.
  215. * It improves the UX, mainly when the widget is the first or last child of the root editable
  216. * and there's no other way to type after or before it.
  217. *
  218. * @private
  219. * @param {Boolean} isBackwards Set to true if the new paragraph is to be inserted before
  220. * the selected widget (<kbd>Shift</kbd>+<kbd>Enter</kbd>).
  221. * @returns {Boolean|undefined} Returns `true` if keys were handled correctly.
  222. */
  223. _handleEnterKey( isBackwards ) {
  224. const model = this.editor.model;
  225. const modelSelection = model.document.selection;
  226. const objectElement = modelSelection.getSelectedElement();
  227. if ( objectElement && model.schema.isObject( objectElement ) ) {
  228. model.change( writer => {
  229. let position = writer.createPositionAt( objectElement, isBackwards ? 'before' : 'after' );
  230. const paragraph = writer.createElement( 'paragraph' );
  231. if ( !model.schema.isLimit( objectElement.parent ) ) {
  232. position = writer.split( position ).position;
  233. }
  234. writer.insert( paragraph, position );
  235. writer.setSelection( paragraph, 'in' );
  236. } );
  237. return true;
  238. }
  239. }
  240. /**
  241. * Extends the {@link module:engine/model/selection~Selection document's selection} to span the entire
  242. * content of the nested editable if already anchored in one.
  243. *
  244. * See: {@link module:engine/model/schema~Schema#getLimitElement}.
  245. *
  246. * @private
  247. */
  248. _selectAllNestedEditableContent() {
  249. const model = this.editor.model;
  250. const documentSelection = model.document.selection;
  251. const limitElement = model.schema.getLimitElement( documentSelection );
  252. if ( documentSelection.getFirstRange().root == limitElement ) {
  253. return false;
  254. }
  255. model.change( writer => {
  256. writer.setSelection( writer.createRangeIn( limitElement ) );
  257. } );
  258. return true;
  259. }
  260. /**
  261. * Handles <kbd>CTRL + A</kbd> when widget is selected.
  262. *
  263. * @private
  264. * @returns {Boolean} Returns true if widget was selected and selecting all was handled by this method.
  265. */
  266. _selectAllContent() {
  267. const model = this.editor.model;
  268. const editing = this.editor.editing;
  269. const view = editing.view;
  270. const viewDocument = view.document;
  271. const viewSelection = viewDocument.selection;
  272. const selectedElement = viewSelection.getSelectedElement();
  273. // Only widget is selected.
  274. // https://github.com/ckeditor/ckeditor5-widget/issues/23
  275. if ( selectedElement && isWidget( selectedElement ) ) {
  276. const widgetParent = editing.mapper.toModelElement( selectedElement.parent );
  277. model.change( writer => {
  278. writer.setSelection( writer.createRangeIn( widgetParent ) );
  279. } );
  280. return true;
  281. }
  282. return false;
  283. }
  284. /**
  285. * Sets {@link module:engine/model/selection~Selection document's selection} over given element.
  286. *
  287. * @private
  288. * @param {module:engine/model/element~Element} element
  289. */
  290. _setSelectionOverElement( element ) {
  291. this.editor.model.change( writer => {
  292. writer.setSelection( writer.createRangeOn( element ) );
  293. } );
  294. }
  295. /**
  296. * Checks if {@link module:engine/model/element~Element element} placed next to the current
  297. * {@link module:engine/model/selection~Selection model selection} exists and is marked in
  298. * {@link module:engine/model/schema~Schema schema} as `object`.
  299. *
  300. * @private
  301. * @param {Boolean} forward Direction of checking.
  302. * @returns {module:engine/model/element~Element|null}
  303. */
  304. _getObjectElementNextToSelection( forward ) {
  305. const model = this.editor.model;
  306. const schema = model.schema;
  307. const modelSelection = model.document.selection;
  308. // Clone current selection to use it as a probe. We must leave default selection as it is so it can return
  309. // to its current state after undo.
  310. const probe = model.createSelection( modelSelection );
  311. model.modifySelection( probe, { direction: forward ? 'forward' : 'backward' } );
  312. const objectElement = forward ? probe.focus.nodeBefore : probe.focus.nodeAfter;
  313. if ( !!objectElement && schema.isObject( objectElement ) ) {
  314. return objectElement;
  315. }
  316. return null;
  317. }
  318. /**
  319. * Removes CSS class from previously selected widgets.
  320. *
  321. * @private
  322. * @param {module:engine/view/downcastwriter~DowncastWriter} writer
  323. */
  324. _clearPreviouslySelectedWidgets( writer ) {
  325. for ( const widget of this._previouslySelected ) {
  326. writer.removeClass( WIDGET_SELECTED_CLASS_NAME, widget );
  327. }
  328. this._previouslySelected.clear();
  329. }
  330. }
  331. // Returns 'true' if provided key code represents one of the arrow keys.
  332. //
  333. // @param {Number} keyCode
  334. // @returns {Boolean}
  335. function isArrowKeyCode( keyCode ) {
  336. return keyCode == keyCodes.arrowright ||
  337. keyCode == keyCodes.arrowleft ||
  338. keyCode == keyCodes.arrowup ||
  339. keyCode == keyCodes.arrowdown;
  340. }
  341. // Returns 'true' if provided (DOM) key event data corresponds with the Ctrl+A keystroke.
  342. //
  343. // @param {module:engine/view/observer/keyobserver~KeyEventData} domEventData
  344. // @returns {Boolean}
  345. function isSelectAllKeyCode( domEventData ) {
  346. return getCode( domEventData ) == selectAllKeystrokeCode;
  347. }
  348. // Returns `true` when element is a nested editable or is placed inside one.
  349. //
  350. // @param {module:engine/view/element~Element}
  351. // @returns {Boolean}
  352. function isInsideNestedEditable( element ) {
  353. while ( element ) {
  354. if ( element.is( 'editableElement' ) && !element.is( 'rootElement' ) ) {
  355. return true;
  356. }
  357. // Click on nested widget should select it.
  358. if ( isWidget( element ) ) {
  359. return false;
  360. }
  361. element = element.parent;
  362. }
  363. return false;
  364. }
  365. // Checks whether the specified `element` is a child of the `parent` element.
  366. //
  367. // @param {module:engine/view/element~Element} element An element to check.
  368. // @param {module:engine/view/element~Element|null} parent A parent for the element.
  369. // @returns {Boolean}
  370. function isChild( element, parent ) {
  371. if ( !parent ) {
  372. return false;
  373. }
  374. return Array.from( element.getAncestors() ).includes( parent );
  375. }