|
|
@@ -22,7 +22,7 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
|
|
|
import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
|
|
|
|
|
|
/**
|
|
|
- * Class representing a basic, generic editor.
|
|
|
+ * The class representing a basic, generic editor.
|
|
|
*
|
|
|
* Check out the list of its subclasses to learn about specific editor implementations.
|
|
|
*
|
|
|
@@ -30,12 +30,12 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
|
|
|
* {@link module:editor-inline/inlineeditor~InlineEditor}) should extend this class. They can add their
|
|
|
* own methods and properties.
|
|
|
*
|
|
|
- * When you are implementing a plugin, then this editor represents the API
|
|
|
+ * When you are implementing a plugin, this editor represents the API
|
|
|
* which your plugin can expect to get when using its {@link module:core/plugin~Plugin#editor} property.
|
|
|
*
|
|
|
* This API should be sufficient in order to implement the "editing" part of your feature
|
|
|
* (schema definition, conversion, commands, keystrokes, etc.).
|
|
|
- * It does not define the editor UI, which is available only if the
|
|
|
+ * It does not define the editor UI, which is available only if
|
|
|
* the specific editor implements also the {@link module:core/editor/editorwithui~EditorWithUI} interface
|
|
|
* (as most editor implementations do).
|
|
|
*
|
|
|
@@ -44,16 +44,16 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
|
|
|
*/
|
|
|
export default class Editor {
|
|
|
/**
|
|
|
- * Creates a new instance of the Editor class.
|
|
|
+ * Creates a new instance of the editor class.
|
|
|
*
|
|
|
* Usually, not to be used directly. See the static {@link module:core/editor/editor~Editor.create `create()`} method.
|
|
|
*
|
|
|
- * @param {Object} [config={}] The editor config.
|
|
|
+ * @param {Object} [config={}] The editor configuration.
|
|
|
*/
|
|
|
constructor( config = {} ) {
|
|
|
/**
|
|
|
* The editor context.
|
|
|
- * When it is not provided through the configuration then the editor creates it.
|
|
|
+ * When it is not provided through the configuration, the editor creates it.
|
|
|
*
|
|
|
* @protected
|
|
|
* @type {module:core/context~Context}
|
|
|
@@ -64,7 +64,7 @@ export default class Editor {
|
|
|
const availablePlugins = this.constructor.builtinPlugins;
|
|
|
|
|
|
/**
|
|
|
- * Holds all configurations specific to this editor instance.
|
|
|
+ * Stores all configurations specific to this editor instance.
|
|
|
*
|
|
|
* editor.config.get( 'image.toolbar' );
|
|
|
* // -> [ 'imageStyle:full', 'imageStyle:side', '|', 'imageTextAlternative' ]
|
|
|
@@ -79,7 +79,7 @@ export default class Editor {
|
|
|
/**
|
|
|
* The plugins loaded and in use by this editor instance.
|
|
|
*
|
|
|
- * editor.plugins.get( 'Clipboard' ); // -> instance of the Clipboard plugin.
|
|
|
+ * editor.plugins.get( 'Clipboard' ); // -> An instance of the clipboard plugin.
|
|
|
*
|
|
|
* @readonly
|
|
|
* @member {module:core/plugincollection~PluginCollection}
|
|
|
@@ -121,11 +121,11 @@ export default class Editor {
|
|
|
*
|
|
|
* The editor is in one of the following states:
|
|
|
*
|
|
|
- * * `initializing` - during the editor initialization (before {@link module:core/editor/editor~Editor.create `Editor.create()`})
|
|
|
- * finished its job,
|
|
|
- * * `ready` - after the promise returned by the {@link module:core/editor/editor~Editor.create `Editor.create()`}
|
|
|
- * method is resolved,
|
|
|
- * * `destroyed` - once the {@link #destroy `editor.destroy()`} method was called.
|
|
|
+ * * `initializing` – During the editor initialization (before {@link module:core/editor/editor~Editor.create `Editor.create()`})
|
|
|
+ * finished its job.
|
|
|
+ * * `ready` – After the promise returned by the {@link module:core/editor/editor~Editor.create `Editor.create()`}
|
|
|
+ * method is resolved.
|
|
|
+ * * `destroyed` – Once the {@link #destroy `editor.destroy()`} method was called.
|
|
|
*
|
|
|
* @observable
|
|
|
* @member {'initializing'|'ready'|'destroyed'} #state
|
|
|
@@ -161,7 +161,7 @@ export default class Editor {
|
|
|
|
|
|
/**
|
|
|
* The {@link module:engine/controller/datacontroller~DataController data controller}.
|
|
|
- * Used e.g. for setting and retrieving editor data.
|
|
|
+ * Used e.g. for setting and retrieving the editor data.
|
|
|
*
|
|
|
* @readonly
|
|
|
* @member {module:engine/controller/datacontroller~DataController}
|
|
|
@@ -179,9 +179,9 @@ export default class Editor {
|
|
|
this.editing.view.document.bind( 'isReadOnly' ).to( this );
|
|
|
|
|
|
/**
|
|
|
- * Conversion manager through which you can register model to view and view to model converters.
|
|
|
+ * Conversion manager through which you can register model-to-view and view-to-model converters.
|
|
|
*
|
|
|
- * See {@link module:engine/conversion/conversion~Conversion}'s documentation to learn how to add converters.
|
|
|
+ * See the {@link module:engine/conversion/conversion~Conversion} documentation to learn how to add converters.
|
|
|
*
|
|
|
* @readonly
|
|
|
* @member {module:engine/conversion/conversion~Conversion}
|
|
|
@@ -191,7 +191,7 @@ export default class Editor {
|
|
|
this.conversion.addAlias( 'editingDowncast', this.editing.downcastDispatcher );
|
|
|
|
|
|
/**
|
|
|
- * Instance of the {@link module:core/editingkeystrokehandler~EditingKeystrokeHandler}.
|
|
|
+ * An instance of the {@link module:core/editingkeystrokehandler~EditingKeystrokeHandler}.
|
|
|
*
|
|
|
* It allows setting simple keystrokes:
|
|
|
*
|
|
|
@@ -202,14 +202,14 @@ export default class Editor {
|
|
|
* editor.keystrokes.set( 'Ctrl+E', ( data, cancel ) => {
|
|
|
* console.log( data.keyCode );
|
|
|
*
|
|
|
- * // Prevent default (native) action and stop the underlying keydown event
|
|
|
+ * // Prevent the default (native) action and stop the underlying keydown event
|
|
|
* // so no other editor feature will interfere.
|
|
|
* cancel();
|
|
|
* } );
|
|
|
*
|
|
|
- * Note: Certain, typing oriented keystrokes (like <kbd>Backspace</kbd> or <kbd>Enter</kbd>) are handled
|
|
|
- * by low level mechanism and trying to listen to them via the keystroke handler will not work reliably.
|
|
|
- * To handle those specific keystrokes see the events fired by the
|
|
|
+ * Note: Certain typing-oriented keystrokes (like <kbd>Backspace</kbd> or <kbd>Enter</kbd>) are handled
|
|
|
+ * by a low-level mechanism and trying to listen to them via the keystroke handler will not work reliably.
|
|
|
+ * To handle these specific keystrokes, see the events fired by the
|
|
|
* {@link module:engine/view/document~Document editing view document} (`editor.editing.view.document`).
|
|
|
*
|
|
|
* @readonly
|
|
|
@@ -220,10 +220,10 @@ export default class Editor {
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * Loads and initializes plugins specified in the config.
|
|
|
+ * Loads and initializes plugins specified in the configuration.
|
|
|
*
|
|
|
* @returns {Promise.<module:core/plugin~LoadedPlugins>} A promise which resolves
|
|
|
- * once the initialization is completed providing an array of loaded plugins.
|
|
|
+ * once the initialization is completed, providing an array of loaded plugins.
|
|
|
*/
|
|
|
initPlugins() {
|
|
|
const config = this.config;
|
|
|
@@ -264,18 +264,18 @@ export default class Editor {
|
|
|
this.keystrokes.destroy();
|
|
|
} )
|
|
|
// Remove the editor from the context.
|
|
|
- // When the context was created by this editor then then the context will be destroyed.
|
|
|
+ // When the context was created by this editor, the context will be destroyed.
|
|
|
.then( () => this._context._removeEditor( this ) );
|
|
|
}
|
|
|
|
|
|
/**
|
|
|
- * Executes specified command with given parameters.
|
|
|
+ * Executes the specified command with given parameters.
|
|
|
*
|
|
|
* Shorthand for:
|
|
|
*
|
|
|
* editor.commands.get( commandName ).execute( ... );
|
|
|
*
|
|
|
- * @param {String} commandName Name of command to execute.
|
|
|
+ * @param {String} commandName The name of the command to execute.
|
|
|
* @param {*} [...commandParams] Command parameters.
|
|
|
*/
|
|
|
execute( ...args ) {
|
|
|
@@ -308,11 +308,11 @@ export default class Editor {
|
|
|
mix( Editor, ObservableMixin );
|
|
|
|
|
|
/**
|
|
|
- * Fired when {@link module:engine/controller/datacontroller~DataController#event:ready data} and all additional
|
|
|
+ * Fired when the {@link module:engine/controller/datacontroller~DataController#event:ready data} and all additional
|
|
|
* editor components are ready.
|
|
|
*
|
|
|
* Note: This event is most useful for plugin developers. When integrating the editor with your website or
|
|
|
- * application you do not have to listen to `editor#ready` because when the promise returned by the static
|
|
|
+ * application, you do not have to listen to `editor#ready` because when the promise returned by the static
|
|
|
* {@link module:core/editor/editor~Editor.create `Editor.create()`} event is resolved, the editor is already ready.
|
|
|
* In fact, since the first moment when the editor instance is available to you is inside `then()`'s callback,
|
|
|
* you cannot even add a listener to the `editor#ready` event.
|
|
|
@@ -335,21 +335,19 @@ mix( Editor, ObservableMixin );
|
|
|
/**
|
|
|
* This error is thrown when a user tries to use a `<textarea>` element to create a non-classic editor in it.
|
|
|
*
|
|
|
- * Textarea element represents a plain-text and cannot be used as a editable root element with included CKEditor5.
|
|
|
- * Content of an editor should be nicely present to the user and show him how it's going to looks like. Textarea element
|
|
|
- * doesn't support such behavior.
|
|
|
+ * The textarea element represents plain text and in general, cannot be used as an editable root element with CKEditor 5 included.
|
|
|
+ * Only {@glink builds/guides/overview#classic-editor Classic Editor} has implemented a special mechanism that
|
|
|
+ * **replaces** the DOM element and loads the data from it.
|
|
|
*
|
|
|
- * Typically you can use a `div` for storing editor content instead:
|
|
|
+ * Typically you can use a `div` for storing the editor content instead:
|
|
|
*
|
|
|
* <div id="editor">
|
|
|
* <p>Initial content.</p>
|
|
|
* </div>
|
|
|
*
|
|
|
- * Only {@glink builds/guides/overview#classic-editor Classic Editor} has implemented a special system, which
|
|
|
- * **replace** DOM element and load data from it
|
|
|
- * ({@link module:editor-classic/classiceditor~ClassicEditor.create more information}). All other editors
|
|
|
- * use an existing element, load data from it and make this element editable. Details about behaviour of each editor
|
|
|
- * might be found in an associated description of a `create` method of each editor.
|
|
|
+ * ({@link module:editor-classic/classiceditor~ClassicEditor.create read more}). All other editor types
|
|
|
+ * use an existing element, load the data from it, and make this element editable. Refer to the description of the `create()` method
|
|
|
+ * for each editor type to learn more about this behavior.
|
|
|
*
|
|
|
* @error editor-wrong-element
|
|
|
*/
|
|
|
@@ -370,29 +368,29 @@ mix( Editor, ObservableMixin );
|
|
|
* ClassicEditor
|
|
|
* .create( sourceElement )
|
|
|
* .then( editor => {
|
|
|
- * editor.plugins.get( FooPlugin ); // -> instance of the Foo plugin
|
|
|
- * editor.plugins.get( BarPlugin ); // -> instance of the Bar plugin
|
|
|
+ * editor.plugins.get( FooPlugin ); // -> An instance of the Foo plugin.
|
|
|
+ * editor.plugins.get( BarPlugin ); // -> An instance of the Bar plugin.
|
|
|
* } );
|
|
|
*
|
|
|
* ClassicEditor
|
|
|
* .create( sourceElement, {
|
|
|
- * // Don't initialize this plugins (note: it's defined by a string):
|
|
|
+ * // Do not initialize these plugins (note: it is defined by a string):
|
|
|
* removePlugins: [ 'Foo' ]
|
|
|
* } )
|
|
|
* .then( editor => {
|
|
|
- * editor.plugins.get( FooPlugin ); // -> undefined
|
|
|
- * editor.config.get( BarPlugin ); // -> instance of the Bar plugin
|
|
|
+ * editor.plugins.get( FooPlugin ); // -> Undefined.
|
|
|
+ * editor.config.get( BarPlugin ); // -> An instance of the Bar plugin.
|
|
|
* } );
|
|
|
*
|
|
|
* ClassicEditor
|
|
|
* .create( sourceElement, {
|
|
|
- * // Load only this plugin. Can also be define by a string if
|
|
|
+ * // Load only this plugin. It can also be defined by a string if
|
|
|
* // this plugin was built into the editor class.
|
|
|
* plugins: [ FooPlugin ]
|
|
|
* } )
|
|
|
* .then( editor => {
|
|
|
- * editor.plugins.get( FooPlugin ); // -> instance of the Foo plugin
|
|
|
- * editor.config.get( BarPlugin ); // -> undefined
|
|
|
+ * editor.plugins.get( FooPlugin ); // -> An instance of the Foo plugin.
|
|
|
+ * editor.config.get( BarPlugin ); // -> Undefined.
|
|
|
* } );
|
|
|
*
|
|
|
* See also {@link module:core/editor/editor~Editor.defaultConfig}.
|
|
|
@@ -402,8 +400,8 @@ mix( Editor, ObservableMixin );
|
|
|
*/
|
|
|
|
|
|
/**
|
|
|
- * The default config which is built into the editor class.
|
|
|
- * It is used in CKEditor 5 builds to provide the default config options which are later used during editor initialization.
|
|
|
+ * The default configuration which is built into the editor class.
|
|
|
+ * It is used in CKEditor 5 builds to provide the default configuration options which are later used during the editor initialization.
|
|
|
*
|
|
|
* ClassicEditor.defaultConfig = {
|
|
|
* foo: 1,
|
|
|
@@ -417,7 +415,7 @@ mix( Editor, ObservableMixin );
|
|
|
* editor.config.get( 'bar' ); // -> 2
|
|
|
* } );
|
|
|
*
|
|
|
- * // The default options can be overridden by the config passed to create().
|
|
|
+ * // The default options can be overridden by the configuration passed to create().
|
|
|
* ClassicEditor
|
|
|
* .create( sourceElement, { bar: 3 } )
|
|
|
* .then( editor => {
|