| 1 | /**
|
| 2 | * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
|
| 3 | * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
|
| 4 | */
|
| 5 | /**
|
| 6 | * @module core/editor/utils/dataapimixin
|
| 7 | */
|
| 8 | import type Editor from '../editor.js';
|
| 9 | import type { Constructor } from '@ckeditor/ckeditor5-utils';
|
| 10 | /**
|
| 11 | * Implementation of the {@link module:core/editor/utils/dataapimixin~DataApi}.
|
| 12 | *
|
| 13 | * @deprecated This functionality is already implemented by the `Editor` class.
|
| 14 | */
|
| 15 | export default function DataApiMixin<Base extends Constructor<Editor>>(base: Base): Base;
|
| 16 | /**
|
| 17 | * Interface defining editor methods for setting and getting data to and from the editor's main root element
|
| 18 | * using the {@link module:core/editor/editor~Editor#data data pipeline}.
|
| 19 | *
|
| 20 | * This interface is not a part of the {@link module:core/editor/editor~Editor} class because one may want to implement
|
| 21 | * an editor with multiple root elements, in which case the methods for setting and getting data will need to be implemented
|
| 22 | * differently.
|
| 23 | *
|
| 24 | * @deprecated This interface is implemented by all `Editor` instances by default.
|
| 25 | */
|
| 26 | export interface DataApi {
|
| 27 | /**
|
| 28 | * Sets the data in the editor.
|
| 29 | *
|
| 30 | * ```ts
|
| 31 | * editor.setData( '<p>This is editor!</p>' );
|
| 32 | * ```
|
| 33 | *
|
| 34 | * If your editor implementation uses multiple roots, you should pass an object with keys corresponding
|
| 35 | * to the editor root names and values equal to the data that should be set in each root:
|
| 36 | *
|
| 37 | * ```ts
|
| 38 | * editor.setData( {
|
| 39 | * header: '<p>Content for header part.</p>',
|
| 40 | * content: '<p>Content for main part.</p>',
|
| 41 | * footer: '<p>Content for footer part.</p>'
|
| 42 | * } );
|
| 43 | * ```
|
| 44 | *
|
| 45 | * By default the editor accepts HTML. This can be controlled by injecting a different data processor.
|
| 46 | * See the {@glink features/markdown Markdown output} guide for more details.
|
| 47 | *
|
| 48 | * @param data Input data.
|
| 49 | */
|
| 50 | setData(data: string | Record<string, string>): void;
|
| 51 | /**
|
| 52 | * Gets the data from the editor.
|
| 53 | *
|
| 54 | * ```ts
|
| 55 | * editor.getData(); // -> '<p>This is editor!</p>'
|
| 56 | * ```
|
| 57 | *
|
| 58 | * If your editor implementation uses multiple roots, you should pass root name as one of the options:
|
| 59 | *
|
| 60 | * ```ts
|
| 61 | * editor.getData( { rootName: 'header' } ); // -> '<p>Content for header part.</p>'
|
| 62 | * ```
|
| 63 | *
|
| 64 | * By default, the editor outputs HTML. This can be controlled by injecting a different data processor.
|
| 65 | * See the {@glink features/markdown Markdown output} guide for more details.
|
| 66 | *
|
| 67 | * A warning is logged when you try to retrieve data for a detached root, as most probably this is a mistake. A detached root should
|
| 68 | * be treated like it is removed, and you should not save its data. Note, that the detached root data is always an empty string.
|
| 69 | *
|
| 70 | * @param options Additional configuration for the retrieved data.
|
| 71 | * Editor features may introduce more configuration options that can be set through this parameter.
|
| 72 | * @param options.rootName Root name. Default to `'main'`.
|
| 73 | * @param options.trim Whether returned data should be trimmed. This option is set to `'empty'` by default,
|
| 74 | * which means that whenever editor content is considered empty, an empty string is returned. To turn off trimming
|
| 75 | * use `'none'`. In such cases exact content will be returned (for example `'<p> </p>'` for an empty editor).
|
| 76 | * @returns Output data.
|
| 77 | */
|
| 78 | getData(options?: Record<string, unknown>): string;
|
| 79 | }
|