-
Notifications
You must be signed in to change notification settings - Fork 3.6k
/
classiceditor.ts
262 lines (235 loc) · 10.2 KB
/
classiceditor.ts
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
257
258
259
260
261
262
/**
* @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
*/
/**
* @module editor-classic/classiceditor
*/
import ClassicEditorUI from './classiceditorui.js';
import ClassicEditorUIView from './classiceditoruiview.js';
import {
Editor,
Context,
ElementApiMixin,
attachToForm,
type EditorConfig,
type EditorReadyEvent
} from 'ckeditor5/src/core.js';
import { getDataFromElement, CKEditorError } from 'ckeditor5/src/utils.js';
import { ContextWatchdog, EditorWatchdog } from 'ckeditor5/src/watchdog.js';
import { isElement as _isElement } from 'lodash-es';
/**
* The {@glink installation/getting-started/predefined-builds#classic-editor classic editor} implementation.
* It uses an inline editable and a sticky toolbar, all enclosed in a boxed UI.
* See the {@glink examples/builds/classic-editor demo}.
*
* In order to create a classic editor instance, use the static
* {@link module:editor-classic/classiceditor~ClassicEditor.create `ClassicEditor.create()`} method.
*
* # Classic editor and classic build
*
* The classic editor can be used directly from source (if you installed the
* [`@ckeditor/ckeditor5-editor-classic`](https://www.npmjs.com/package/@ckeditor/ckeditor5-editor-classic) package)
* but it is also available in the {@glink installation/getting-started/predefined-builds#classic-editor classic build}.
*
* {@glink installation/getting-started/predefined-builds 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 easier customization.
*
* Read more about initializing the editor from source or as a build in
* {@link module:editor-classic/classiceditor~ClassicEditor.create `ClassicEditor.create()`}.
*/
export default class ClassicEditor extends ElementApiMixin( Editor ) {
/**
* @inheritDoc
*/
public readonly ui: ClassicEditorUI;
/**
* Creates an instance of the classic editor.
*
* **Note:** do not use the constructor to create editor instances. Use the static
* {@link module:editor-classic/classiceditor~ClassicEditor.create `ClassicEditor.create()`} method instead.
*
* @param sourceElementOrData The DOM element that will be the source for the created editor
* or the editor's initial data. For more information see
* {@link module:editor-classic/classiceditor~ClassicEditor.create `ClassicEditor.create()`}.
* @param config The editor configuration.
*/
protected constructor( sourceElementOrData: HTMLElement | string, config: EditorConfig = {} ) {
// If both `config.initialData` is set and initial data is passed as the constructor parameter, then throw.
if ( !isElement( sourceElementOrData ) && config.initialData !== undefined ) {
// Documented in core/editor/editorconfig.jsdoc.
// eslint-disable-next-line ckeditor5-rules/ckeditor-error-message
throw new CKEditorError( 'editor-create-initial-data', null );
}
super( config );
this.config.define( 'menuBar.isVisible', false );
if ( this.config.get( 'initialData' ) === undefined ) {
this.config.set( 'initialData', getInitialData( sourceElementOrData ) );
}
if ( isElement( sourceElementOrData ) ) {
this.sourceElement = sourceElementOrData;
}
this.model.document.createRoot();
const shouldToolbarGroupWhenFull = !this.config.get( 'toolbar.shouldNotGroupWhenFull' );
const menuBarConfig = this.config.get( 'menuBar' )!;
const view = new ClassicEditorUIView( this.locale, this.editing.view, {
shouldToolbarGroupWhenFull,
useMenuBar: menuBarConfig.isVisible
} );
this.ui = new ClassicEditorUI( this, view );
attachToForm( this );
}
/**
* Destroys the editor instance, releasing all resources used by it.
*
* Updates the original editor element with the data if the
* {@link module:core/editor/editorconfig~EditorConfig#updateSourceElementOnDestroy `updateSourceElementOnDestroy`}
* configuration option is set to `true`.
*/
public override destroy(): Promise<unknown> {
if ( this.sourceElement ) {
this.updateSourceElement();
}
this.ui.destroy();
return super.destroy();
}
/**
* Creates a new classic editor instance.
*
* There are three ways how the editor can be initialized.
*
* # Replacing a DOM element (and loading data from it)
*
* You can initialize the editor using an existing DOM element:
*
* ```ts
* ClassicEditor
* .create( document.querySelector( '#editor' ) )
* .then( editor => {
* console.log( 'Editor was initialized', editor );
* } )
* .catch( err => {
* console.error( err.stack );
* } );
* ```
*
* The element's content will be used as the editor data and the element will be replaced by the editor UI.
*
* # Creating a detached editor
*
* Alternatively, you can initialize the editor by passing the initial data directly as a string.
* In this case, the editor will render an element that must be inserted into the DOM:
*
* ```ts
* ClassicEditor
* .create( '<p>Hello world!</p>' )
* .then( editor => {
* console.log( 'Editor was initialized', editor );
*
* // Initial data was provided so the editor UI element needs to be added manually to the DOM.
* document.body.appendChild( editor.ui.element );
* } )
* .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.
*
* # Replacing a 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:
*
* ```ts
* ClassicEditor
* .create( document.querySelector( '#editor' ), {
* initialData: '<h2>Initial data</h2><p>Foo bar.</p>'
* } )
* .then( editor => {
* console.log( 'Editor was initialized', editor );
* } )
* .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 installation/getting-started/predefined-builds editor build} (for example – `@ckeditor/ckeditor5-build-classic`).
*
* If you want to use the classic editor from source (`@ckeditor/ckeditor5-editor-classic/src/classiceditor`),
* 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 installation/advanced/alternative-setups/integrating-from-source-webpack dedicated guide}.
*
* @param 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
* and the {@link module:editor-classic/classiceditorui~ClassicEditorUI#element editor element} will replace the passed element
* in the DOM (the original one will be hidden and the editor will be injected next to it).
*
* If the {@link module:core/editor/editorconfig~EditorConfig#updateSourceElementOnDestroy updateSourceElementOnDestroy}
* option is set to `true`, the editor data will be set back to the original element once the editor is destroyed and when a form,
* in which this element is contained, is submitted (if the original element is a `<textarea>`). This ensures seamless integration
* with native web forms.
*
* 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 under the {@link module:editor-classic/classiceditorui~ClassicEditorUI#element `editor.ui.element`} property.
*
* @param config The editor configuration.
* @returns A promise resolved once the editor is ready. The promise resolves with the created editor instance.
*/
public static override create( sourceElementOrData: HTMLElement | string, config: EditorConfig = {} ): Promise<ClassicEditor> {
return new Promise( resolve => {
const editor = new this( sourceElementOrData, config );
resolve(
editor.initPlugins()
.then( () => editor.ui.init( isElement( sourceElementOrData ) ? sourceElementOrData : null ) )
.then( () => editor.data.init( editor.config.get( 'initialData' )! ) )
.then( () => editor.fire<EditorReadyEvent>( 'ready' ) )
.then( () => editor )
);
} );
}
/**
* The {@link module:core/context~Context} class.
*
* Exposed as static editor field for easier access in editor builds.
*/
public static Context = Context;
/**
* The {@link module:watchdog/editorwatchdog~EditorWatchdog} class.
*
* Exposed as static editor field for easier access in editor builds.
*/
public static EditorWatchdog = EditorWatchdog;
/**
* The {@link module:watchdog/contextwatchdog~ContextWatchdog} class.
*
* Exposed as static editor field for easier access in editor builds.
*/
public static ContextWatchdog = ContextWatchdog;
}
function getInitialData( sourceElementOrData: HTMLElement | string ): string {
return isElement( sourceElementOrData ) ? getDataFromElement( sourceElementOrData ) : sourceElementOrData;
}
function isElement( value: any ): value is Element {
return _isElement( value );
}