-
-
Notifications
You must be signed in to change notification settings - Fork 3.7k
/
rawelement.js
148 lines (139 loc) · 5.62 KB
/
rawelement.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
/**
* @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
*/
/**
* @module engine/view/rawelement
*/
import Element from './element';
import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
import Node from './node';
/**
* The raw element class.
*
* The raw elements work as data containers ("wrappers", "sandboxes") but their children are not managed or
* even recognized by the editor. This encapsulation allows integrations to maintain custom DOM structures
* in the editor content without, for instance, worrying about compatibility with other editor features.
* Raw elements are a perfect tool for integration with external frameworks and data sources.
*
* Unlike {@link module:engine/view/uielement~UIElement UI elements}, raw elements act like real editor
* content (similar to {@link module:engine/view/containerelement~ContainerElement} or
* {@link module:engine/view/emptyelement~EmptyElement}), they are considered by the editor selection and
* {@link module:widget/utils~toWidget they can work as widgets}.
*
* To create a new raw element, use the
* {@link module:engine/view/downcastwriter~DowncastWriter#createRawElement `downcastWriter#createRawElement()`} method.
*
* @extends module:engine/view/element~Element
*/
export default class RawElement extends Element {
/**
* Creates a new instance of a raw element.
*
* Throws the `view-rawelement-cannot-add` {@link module:utils/ckeditorerror~CKEditorError CKEditorError} when the `children`
* parameter is passed to inform that the usage of `RawElement` is incorrect (adding child nodes to `RawElement` is forbidden).
*
* @see module:engine/view/downcastwriter~DowncastWriter#createRawElement
* @protected
* @param {module:engine/view/document~Document} document The document instance to which this element belongs.
* @param {String} name A node name.
* @param {Object|Iterable} [attrs] The collection of attributes.
* @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
* A list of nodes to be inserted into the created element.
*/
constructor( document, name, attrs, children ) {
super( document, name, attrs, children );
// Override the default of the base class.
this._isAllowedInsideAttributeElement = true;
/**
* Returns `null` because filler is not needed for raw elements.
*
* @method #getFillerOffset
* @returns {null} Always returns null.
*/
this.getFillerOffset = getFillerOffset;
}
/**
* Checks whether this object is of the given type or name.
*
* rawElement.is( 'rawElement' ); // -> true
* rawElement.is( 'element' ); // -> true
* rawElement.is( 'node' ); // -> true
* rawElement.is( 'view:rawElement' ); // -> true
* rawElement.is( 'view:element' ); // -> true
* rawElement.is( 'view:node' ); // -> true
*
* rawElement.is( 'model:element' ); // -> false
* rawElement.is( 'documentFragment' ); // -> false
*
* Assuming that the object being checked is a raw element, you can also check its
* {@link module:engine/view/rawelement~RawElement#name name}:
*
* rawElement.is( 'img' ); // -> true if this is an img element
* rawElement.is( 'rawElement', 'img' ); // -> same as above
* text.is( 'img' ); -> false
*
* {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
*
* @param {String} type The type to check when the `name` parameter is present.
* Otherwise, it acts like the `name` parameter.
* @param {String} [name] The element name.
* @returns {Boolean}
*/
is( type, name = null ) {
if ( !name ) {
return type === 'rawElement' || type === 'view:rawElement' ||
// 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 === 'rawElement' || type === 'view:rawElement' ||
type === 'element' || type === 'view:element'
);
}
}
/**
* Overrides the {@link module:engine/view/element~Element#_insertChild} method.
* Throws the `view-rawelement-cannot-add` {@link module:utils/ckeditorerror~CKEditorError CKEditorError} to prevent
* adding any child nodes to a raw element.
*
* @protected
*/
_insertChild( index, nodes ) {
if ( nodes && ( nodes instanceof Node || Array.from( nodes ).length > 0 ) ) {
/**
* Cannot add children to a {@link module:engine/view/rawelement~RawElement} instance.
*
* @error view-rawelement-cannot-add
*/
throw new CKEditorError(
'view-rawelement-cannot-add',
[ this, nodes ]
);
}
}
/**
* This allows rendering the children of a {@link module:engine/view/rawelement~RawElement} on the DOM level.
* This method is called by the {@link module:engine/view/domconverter~DomConverter} with the raw DOM element
* passed as an argument, leaving the number and shape of the children up to the integrator.
*
* This method **must be defined** for the raw element to work:
*
* const myRawElement = downcastWriter.createRawElement( 'div' );
*
* myRawElement.render = function( domElement ) {
* domElement.innerHTML = '<b>This is the raw content of myRawElement.</b>';
* };
*
* @method #render
* @param {HTMLElement} domElement The native DOM element representing the raw view element.
*/
}
// Returns `null` because block filler is not needed for raw elements.
//
// @returns {null}
function getFillerOffset() {
return null;
}