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