diff --git a/packages/ckeditor5-core/src/editor/editorconfig.ts b/packages/ckeditor5-core/src/editor/editorconfig.ts index eaf15b14b2d..78d29cfcc1f 100644 --- a/packages/ckeditor5-core/src/editor/editorconfig.ts +++ b/packages/ckeditor5-core/src/editor/editorconfig.ts @@ -109,6 +109,12 @@ export interface EditorConfig extends EngineConfig { * If `config.initialData` is not set when the editor is initialized, the data received in `Editor.create()` call * will be used to set `config.initialData`. As a result, `initialData` is always set in the editor's config and * plugins can read and/or modify it during initialization. + * + * **This property has been deprecated and will be removed in the future versions of CKEditor. Please use + * {@link module:core/editor/editorconfig~EditorConfig#root `root.initialData`} or + * {@link module:core/editor/editorconfig~EditorConfig#roots `roots..initialData`} instead.** + * + * @deprecated */ initialData?: string | Record; @@ -537,6 +543,12 @@ export interface EditorConfig extends EngineConfig { * element passed to the `create()` method. * * See the {@glink features/editor-placeholder "Editor placeholder"} guide for more information and live examples. + * + * **This property has been deprecated and will be removed in the future versions of CKEditor. Please use + * {@link module:core/editor/editorconfig~EditorConfig#root `root.placeholder`} or + * {@link module:core/editor/editorconfig~EditorConfig#roots `roots..placeholder`} instead.** + * + * @deprecated */ placeholder?: string | Record; @@ -864,8 +876,231 @@ export interface EditorConfig extends EngineConfig { * .then( ... ) * .catch( ... ); * ``` + * + * **This property has been deprecated and will be removed in the future versions of CKEditor. Please use + * {@link module:core/editor/editorconfig~EditorConfig#root `root.label`} or + * {@link module:core/editor/editorconfig~EditorConfig#roots `roots..label`} instead.** + * + * @deprecated */ label?: string | Record; + + /** + * The root configuration options for the default `main` root. + * + * This option is an alias for `config.roots.main`. + */ + root?: RootConfig; + + /** + * The root configuration options grouped by the root name. + * + * ```ts + * ClassicEditor + * .create( document.querySelector( '#editor' ), { + * roots: { + * main: { + * initialData: '

Hello world!

', + * placeholder: 'Type some text...', + * label: 'Main content' + * } + * } + * } ); + * ``` + */ + roots?: Record; +} + +/** + * Configuration for a single editor root. It is used in {@link module:core/editor/editorconfig~EditorConfig#root `EditorConfig#root`} and + * {@link module:core/editor/editorconfig~EditorConfig#roots `EditorConfig#roots.`}. + * + * **Note**: If your editor implementation uses only a single root, you can use `config.root` to set the root configuration instead of + * `config.roots.main`. + */ +export interface RootConfig { + + /** + * The initial editor data to be used instead of the provided element's HTML content. + * + * ```ts + * ClassicEditor + * .create( document.querySelector( '#editor' ), { + * root: { + * initialData: '

Initial data

Foo bar.

' + * } + * } ) + * .then( ... ) + * .catch( ... ); + * ``` + * + * By default, the editor is initialized with the content of the element on which this editor is initialized. + * This configuration option lets you override this behavior and pass different initial data. + * It is especially useful if it is difficult for your integration to put the data inside the HTML element. + * + * If your editor implementation uses multiple roots, you should provide config for roots individually: + * + * ```ts + * MultiRootEditor.create( + * // Roots for the editor: + * { + * header: document.querySelector( '#header' ), + * content: document.querySelector( '#content' ), + * leftSide: document.querySelector( '#left-side' ), + * rightSide: document.querySelector( '#right-side' ) + * }, + * // Config: + * { + * roots: { + * header: { + * initialData: '

Content for header part.

' + * }, + * content: { + * initialData: '

Content for main part.

' + * }, + * leftSide: { + * initialData: '

Content for left-side box.

' + * }, + * rightSide: { + * initialData: '

Content for right-side box.

' + * } + * } + * } + * ) + * .then( ... ) + * .catch( ... ); + * ``` + * See also {@link module:core/editor/editor~Editor.create Editor.create()} documentation for the editor implementation which you use. + * + * **Note:** If initial data is passed to `Editor.create()` in the first parameter (instead of a DOM element), and, + * at the same time, `config.initialData` is set, an error will be thrown as those two options exclude themselves. + * + * If `config.root.initialData` is not set when the editor is initialized, the data received in `Editor.create()` call + * will be used to set `config.roots.main.initialData`. As a result, `initialData` is always set in the editor's config and + * plugins can read and/or modify it during initialization. TODO breaking change - the updated initialData changes location + */ + initialData?: string; + + /** + * 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. + * + * ```ts + * ClassicEditor + * .create( document.querySelector( '#editor' ), { + * root: { + * placeholder: 'Type some text...' + * } + * } ) + * .then( ... ) + * .catch( ... ); + * ``` + * + * If your editor implementation uses multiple roots, you should provide config for roots individually: + * + * ```ts + * MultiRootEditor.create( + * // Roots for the editor: + * { + * header: document.querySelector( '#header' ), + * content: document.querySelector( '#content' ), + * leftSide: document.querySelector( '#left-side' ), + * rightSide: document.querySelector( '#right-side' ) + * }, + * // Config: + * { + * roots: { + * header: { + * placeholder: 'Type header...' + * }, + * content: { + * placeholder: 'Type content...' + * }, + * leftSide: { + * placeholder: 'Type left-side...' + * }, + * rightSide: { + * placeholder: 'Type right-side...' + * } + * } + * } + * ) + * .then( ... ) + * .catch( ... ); + * ``` + * + * 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. + * + * ```html + *

+ * ::before + *

+ * ``` + * + * **Note**: Placeholder text can also be set using the `placeholder` attribute if a `