src/editor/editorconfig.jsdoc
/**
* @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 core/editor/editorconfig
*/
/**
* CKEditor configuration options.
*
* An object defining the editor configuration can be passed when initializing the editor:
*
* EditorClass
* .create( {
* toolbar: [ 'bold', 'italic' ],
* image: {
* styles: [
* ...
* ]
* }
* } )
* .then( ... )
* .catch( ... );
*
* Check the {@glink builds/guides/integration/configuration Configuration guide} for more information
* about setting configuration options.
*
* @interface EditorConfig
*/
/**
* The initial editor data to be used instead of the provided element's HTML content.
*
* ClassicEditor
* .create( document.querySelector( '#editor' ), {
* initialData: '<h2>Initial data</h2><p>Foo bar.</p>'
* } )
* .then( ... )
* .catch( ... );
*
* By default, the editor is initialized with the content of the element on which this editor is initialized.
* See {@link module:core/editor/editor~Editor.create Editor.create()}.
*
* This configuration option lets you override initial data if an element is passed to `Editor.create()`.
* It is especially useful if it is difficult for your integration to put the data inside the HTML element.
*
* **Note:** If initial data is passed to `Editor.create()` as a parameter and, at the same time, via this configuration option,
* an error will be thrown as those two options exclude themselves.
*
* @member {String} module:core/editor/editorconfig~EditorConfig#initialData
*/
/**
* The `config.initialData` option cannot be used together with initial data passed as the first parameter of
* {@link module:core/editor/editor~Editor.create `Editor.create()`}.
*
* @error editor-create-initial-data
*/
/**
* The list of plugins to load.
*
* If you use an {@glink builds/guides/overview editor build} you can define the list of plugins to load
* using the names of plugins that are available:
*
* const config = {
* plugins: [ 'Bold', 'Italic', 'Typing', 'Enter', ... ]
* };
*
* You can check the list of plugins available in a build using this snippet:
*
* ClassicEditor.builtinPlugins.map( plugin => plugin.pluginName );
*
* If you use an editor creator directly (imported from a package like `@ckeditor/ckeditor5-editor-classic`) or you
* want to load additional plugins which were not included in a build you use, then you need to specify
* the plugins using their constructors:
*
* // A preset of plugins is a plugin as well.
* import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
* // The bold plugin.
* import Bold from '@ckeditor/ckeditor5-editor-basic-styles/src/bold';
*
* const config = {
* plugins: [ Essentials, Bold ]
* };
*
* **Note:** To load additional plugins, you should use the {@link #extraPlugins `extraPlugins`} configuration.
* To narrow the list of loaded plugins, use the {@link #removePlugins `removePlugins`} configuration.
*
* @member {Array.<String|Function>} module:core/editor/editorconfig~EditorConfig#plugins
*/
/**
* The list of additional plugins to load along those already available in the
* {@glink builds/guides/overview editor build}. It extends the {@link #plugins `plugins`} configuration.
*
* function MyPlugin( editor ) {
* // ...
* }
*
* const config = {
* extraPlugins: [ MyPlugin ]
* };
*
* **Note:** This configuration works only for simple plugins which utilize the
* {@link module:core/plugin~PluginInterface plugin interface} and have no dependencies. To extend a
* build with complex features, create a {@glink builds/guides/development/custom-builds custom build}.
*
* **Note:** Make sure you include the new features in you toolbar configuration. Learn more
* about {@glink builds/guides/integration/configuration#toolbar-setup toolbar setup}.
*
* @member {Array.<Function>} module:core/editor/editorconfig~EditorConfig#extraPlugins
*/
/**
* The list of plugins which should not be loaded despite being available in an {@glink builds/guides/overview editor build}.
*
* const config = {
* removePlugins: [ 'Bold', 'Italic' ]
* };
*
* **Note:** Be careful when removing plugins using `config.removePlugins` from CKEditor builds.
* If removed plugins were providing toolbar buttons, the default toolbar configuration included in a build
* will become invalid. In such case you need to provide the updated
* {@link module:core/editor/editorconfig~EditorConfig#toolbar toolbar configuration}.
*
* @member {Array.<String>} module:core/editor/editorconfig~EditorConfig#removePlugins
*/
/**
* The editor toolbar configuration.
*
* Simple format (specifies only toolbar items):
*
* const config = {
* toolbar: [ 'bold', 'italic', '|', 'undo', 'redo' ]
* };
*
* Extended format:
*
* const config = {
* toolbar: {
* items: [ 'bold', 'italic', '|', 'undo', 'redo' ],
*
* viewportTopOffset: 30,
*
* shouldNotGroupWhenFull: true
* }
* };
*
* Options which can be set using the extended format:
*
* * **`toolbar.items`** – An array of toolbar item names. The components (buttons, dropdowns, etc.) which can be used
* as toolbar items are defined in `editor.ui.componentFactory` and can be listed using the following snippet:
*
* Array.from( editor.ui.componentFactory.names() );
*
* You can also use `'|'` to create a separator between groups of items:
*
* toolbar: [ 'bold', 'italic', '|', 'undo', 'redo' ]
*
* * **`toolbar.viewportTopOffset`** – The offset (in pixels) from the top of the viewport used when positioning a sticky toolbar.
* Useful when a page with which the editor is being integrated has some other sticky or fixed elements
* (e.g. the top menu). Thanks to setting the toolbar offset the toolbar will not be positioned underneath or above the page's UI.
* * **`toolbar.shouldNotGroupWhenFull`** – When set `true`, the toolbar will stop grouping items that wrap to the next line when
* there is not enough space to display them in a single row.
*
* @member {Array.<String>|Object} module:core/editor/editorconfig~EditorConfig#toolbar
*/
/**
* The language of the editor UI and its content.
*
* Note: You do not have to specify this option if your build is optimized for one UI language or if it is
* the default language (English is the default language for CDN builds), unless you want to change
* the language of your content.
*
* Simple usage (change the language of the UI and the content):
*
* ClassicEditor
* .create( document.querySelector( '#editor' ), {
* // The UI of the editor as well as its content will be in German.
* language: 'de'
* } )
* .then( editor => {
* console.log( editor );
* } )
* .catch( error => {
* console.error( error );
* } );
*
* Use different languages for the UI and the content using the object syntax:
*
* ClassicEditor
* .create( document.querySelector( '#editor' ), {
* language: {
* // The UI will be in English.
* ui: 'en',
*
* // But the content will be edited in Arabic.
* content: 'ar'
* }
* } )
* .then( editor => {
* console.log( editor );
* } )
* .catch( error => {
* console.error( error );
* } );
*
* The language of the content has an impact on the editing experience, for instance it affects screen readers
* and spell checkers. It is also particularly useful for typing in certain languages (e.g. right–to–left ones)
* because it changes the default alignment of the text.
*
* The language codes are defined in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) standard.
*
* You need to add the corresponding translation file for the new UI language to work.
* Translation files are available on CDN for predefined builds:
*
* `<script src="https://cdn.ckeditor.com/ckeditor5/[version.number]/[distribution]/lang/[lang].js"></script>`
*
* But you can add them manually by coping from the `node_modules/@ckeditor/ckeditor5-build-[name]/build/lang/[lang].js'`.
*
* Check the {@glink features/ui-language UI language guide} for more information about the localization options and translation process.
*
* @member {String|Object} module:core/editor/editorconfig~EditorConfig#language
*/
/**
* Specifies the text displayed in the editor when there is no content (editor is empty). It is intended to
* help users locate the editor in the application (form) and prompt them to input the content. Work similarly
* as to the native DOM
* [`placeholder` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#The_placeholder_attribute)
* used by inputs.
*
* const config = {
* placeholder: 'Type some text...'
* };
*
* The placeholder text is displayed as a pseudo–element of an empty paragraph in the editor content.
* The paragraph has the `.ck-placeholder` CSS class and the `data-placeholder` attribute.
*
* <p data-placeholder="Type some text..." class="ck-placeholder">
* ::before
* </p>
*
* **Note**: Placeholder text can also be set using the `placeholder` attribute if a `<textarea>` is passed to
* the `create()` method, e.g. {@link module:editor-classic/classiceditor~ClassicEditor.create `ClassicEditor.create()`}.
*
* **Note**: This configuration has precedence over the value of the `placeholder` attribute of a `<textarea>`
* element passed to the `create()` method.
*
* See the {@glink features/editor-placeholder "Editor placeholder" guide} for more information and live examples.
*
* @member {String} module:core/editor/editorconfig~EditorConfig#placeholder
*/