-
-
Notifications
You must be signed in to change notification settings - Fork 3.7k
/
decouplededitor.js
256 lines (236 loc) · 10.3 KB
/
decouplededitor.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
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
/**
* @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 editor-decoupled/decouplededitor
*/
import { Editor, DataApiMixin, secureSourceElement } from 'ckeditor5/src/core';
import { CKEditorError, getDataFromElement, setDataInElement, mix } from 'ckeditor5/src/utils';
import { isElement } from 'lodash-es';
import DecoupledEditorUI from './decouplededitorui';
import DecoupledEditorUIView from './decouplededitoruiview';
/**
* The {@glink builds/guides/overview#document-editor decoupled editor} implementation.
* It provides an inline editable and a toolbar. However, unlike other editors,
* it does not render these components anywhere in the DOM unless configured.
*
* This type of an editor is dedicated to integrations which require a customized UI with an open
* structure, allowing developers to specify the exact location of the interface.
*
* See the document editor {@glink examples/builds/document-editor demo} to learn about possible use cases
* for the decoupled editor.
*
* In order to create a decoupled editor instance, use the static
* {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create `DecoupledEditor.create()`} method.
*
* # Decoupled editor and document editor build
*
* The decoupled editor can be used directly from source (if you installed the
* [`@ckeditor/ckeditor5-editor-decoupled`](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-decoupled) package)
* but it is also available in the {@glink builds/guides/overview#document-editor document editor build}.
*
* {@glink builds/guides/overview Builds} are ready-to-use editors with plugins bundled in. When using the editor from
* source you need to take care of loading all plugins by yourself
* (through the {@link module:core/editor/editorconfig~EditorConfig#plugins `config.plugins`} option).
* Using the editor from source gives much better flexibility and allows for easier customization.
*
* Read more about initializing the editor from source or as a build in
* {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create `DecoupledEditor.create()`}.
*
* @mixes module:core/editor/utils/dataapimixin~DataApiMixin
* @implements module:core/editor/editorwithui~EditorWithUI
* @extends module:core/editor/editor~Editor
*/
export default class DecoupledEditor extends Editor {
/**
* Creates an instance of the decoupled editor.
*
* **Note:** Do not use the constructor to create editor instances. Use the static
* {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create `DecoupledEditor.create()`} method instead.
*
* @protected
* @param {HTMLElement|String} sourceElementOrData The DOM element that will be the source for the created editor
* (on which the editor will be initialized) or initial data for the editor. For more information see
* {@link module:editor-balloon/ballooneditor~BalloonEditor.create `BalloonEditor.create()`}.
* @param {module:core/editor/editorconfig~EditorConfig} config The editor configuration.
*/
constructor( sourceElementOrData, config ) {
super( config );
if ( isElement( sourceElementOrData ) ) {
this.sourceElement = sourceElementOrData;
secureSourceElement( this );
}
this.model.document.createRoot();
const shouldToolbarGroupWhenFull = !this.config.get( 'toolbar.shouldNotGroupWhenFull' );
const view = new DecoupledEditorUIView( this.locale, this.editing.view, {
editableElement: this.sourceElement,
shouldToolbarGroupWhenFull
} );
this.ui = new DecoupledEditorUI( this, view );
}
/**
* Destroys the editor instance, releasing all resources used by it.
*
* **Note**: The decoupled editor does not remove the toolbar and editable when destroyed. You can
* do that yourself in the destruction chain:
*
* editor.destroy()
* .then( () => {
* // Remove the toolbar from DOM.
* editor.ui.view.toolbar.element.remove();
*
* // Remove the editable from DOM.
* editor.ui.view.editable.element.remove();
*
* console.log( 'Editor was destroyed' );
* } );
*
* @returns {Promise}
*/
destroy() {
// Cache the data, then destroy.
// It's safe to assume that the model->view conversion will not work after super.destroy().
const data = this.getData();
this.ui.destroy();
return super.destroy()
.then( () => {
if ( this.sourceElement ) {
setDataInElement( this.sourceElement, data );
}
} );
}
/**
* Creates a new decoupled editor instance.
*
* Remember that `DecoupledEditor` does not append the toolbar element to your web page so you have to do it manually after the editor
* has been initialized.
*
* There are two ways how the editor can be initialized.
*
* # Using an existing DOM element (and loading data from it)
*
* You can initialize the editor using an existing DOM element:
*
* DecoupledEditor
* .create( document.querySelector( '#editor' ) )
* .then( editor => {
* console.log( 'Editor was initialized', editor );
*
* // Append the toolbar to the <body> element.
* document.body.appendChild( editor.ui.view.toolbar.element );
* } )
* .catch( err => {
* console.error( err.stack );
* } );
*
* The element's content will be used as the editor data and the element will become the editable element.
*
* # Creating a detached editor
*
* Alternatively, you can initialize the editor by passing the initial data directly as a string.
* In this case, you will have to manually append both the toolbar element and the editable element to your web page.
*
* DecoupledEditor
* .create( '<p>Hello world!</p>' )
* .then( editor => {
* console.log( 'Editor was initialized', editor );
*
* // Append the toolbar to the <body> element.
* document.body.appendChild( editor.ui.view.toolbar.element );
*
* // Initial data was provided so the editor UI element needs to be added manually to the DOM.
* document.body.appendChild( editor.ui.getEditableElement() );
* } )
* .catch( err => {
* console.error( err.stack );
* } );
*
* This lets you dynamically append the editor to your web page whenever it is convenient for you. You may use this method if your
* web page content is generated on the client side and the DOM structure is not ready at the moment when you initialize the editor.
*
* # Using an existing DOM element (and data provided in `config.initialData`)
*
* You can also mix these two ways by providing a DOM element to be used and passing the initial data through the configuration:
*
* DecoupledEditor
* .create( document.querySelector( '#editor' ), {
* initialData: '<h2>Initial data</h2><p>Foo bar.</p>'
* } )
* .then( editor => {
* console.log( 'Editor was initialized', editor );
*
* // Append the toolbar to the <body> element.
* document.body.appendChild( editor.ui.view.toolbar.element );
* } )
* .catch( err => {
* console.error( err.stack );
* } );
*
* This method can be used to initialize the editor on an existing element with the specified content in case if your integration
* makes it difficult to set the content of the source element.
*
* Note that an error will be thrown if you pass the initial data both as the first parameter and also in the configuration.
*
* # Configuring the editor
*
* See the {@link module:core/editor/editorconfig~EditorConfig editor configuration documentation} to learn more about
* customizing plugins, toolbar and more.
*
* # Using the editor from source
*
* The code samples listed in the previous sections of this documentation assume that you are using an
* {@glink builds/guides/overview editor build} (for example – `@ckeditor/ckeditor5-build-decoupled`).
*
* If you want to use the decoupled editor from source (`@ckeditor/ckeditor5-editor-decoupled/src/decouplededitor`),
* you need to define the list of
* {@link module:core/editor/editorconfig~EditorConfig#plugins plugins to be initialized} and
* {@link module:core/editor/editorconfig~EditorConfig#toolbar toolbar items}. Read more about using the editor from
* source in the {@glink builds/guides/integration/advanced-setup "Advanced setup" guide}.
*
* @param {HTMLElement|String} sourceElementOrData The DOM element that will be the source for the created editor
* or the editor's initial data.
*
* If a DOM element is passed, its content will be automatically loaded to the editor upon initialization.
* Moreover, the editor data will be set back to the original element once the editor is destroyed.
*
* If the initial data is passed, a detached editor will be created. In this case you need to insert it into the DOM manually.
* It is available via
* {@link module:editor-decoupled/decouplededitorui~DecoupledEditorUI#getEditableElement `editor.ui.getEditableElement()`}.
*
* @param {module:core/editor/editorconfig~EditorConfig} [config] The editor configuration.
* @returns {Promise} A promise resolved once the editor is ready. The promise resolves with the created editor instance.
*/
static create( sourceElementOrData, config = {} ) {
return new Promise( resolve => {
const isHTMLElement = isElement( sourceElementOrData );
if ( isHTMLElement && sourceElementOrData.tagName === 'TEXTAREA' ) {
// Documented in core/editor/editor.js
// eslint-disable-next-line ckeditor5-rules/ckeditor-error-message
throw new CKEditorError( 'editor-wrong-element', null );
}
const editor = new this( sourceElementOrData, config );
resolve(
editor.initPlugins()
.then( () => {
editor.ui.init();
} )
.then( () => {
if ( !isHTMLElement && config.initialData ) {
// Documented in core/editor/editorconfig.jdoc.
// eslint-disable-next-line ckeditor5-rules/ckeditor-error-message
throw new CKEditorError( 'editor-create-initial-data', null );
}
const initialData = config.initialData !== undefined ? config.initialData : getInitialData( sourceElementOrData );
return editor.data.init( initialData );
} )
.then( () => editor.fire( 'ready' ) )
.then( () => editor )
);
} );
}
}
mix( DecoupledEditor, DataApiMixin );
function getInitialData( sourceElementOrData ) {
return isElement( sourceElementOrData ) ? getDataFromElement( sourceElementOrData ) : sourceElementOrData;
}