editorconfig.jsdoc

/**
 * @license Copyright (c) 2003-2019, 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
 *			}
 *		};
 *
 * Options which can be set using the extended format:
 *
 * * **`toolbar.items`** &ndash; 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`** &ndash; 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.
 *
 * @member {Array.<String>|Object} module:core/editor/editorconfig~EditorConfig#toolbar
 */

/**
 * The editor UI's language.
 *
 * The language code is defined in the [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1) standard.
 * CKEditor 5 currently supports around 20 languages and the number is growing.
 *
 * Note: You do not have to specify this option if your build is optimized for one language or if it is the default language
 * (English is the default language for CDN builds).
 *
 * Simple usage:
 *
 *		ClassicEditor
 *			.create( document.querySelector( '#editor' ), {
 *				language: 'de'
 *			} )
 *			.then( editor => {
 *				console.log( editor );
 *			} )
 *			.catch( error => {
 *				console.error( error );
 *			} );
 *
 * After this step you need to attach the corresponding translation file. 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} 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
 */