1 | /**
|
2 | * @license Copyright (c) 2003-2023, 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 heading/title
|
7 | */
|
8 | import { Plugin } from 'ckeditor5/src/core';
|
9 | /**
|
10 | * The Title plugin.
|
11 | *
|
12 | * It splits the document into `Title` and `Body` sections.
|
13 | */
|
14 | export default class Title extends Plugin {
|
15 | /**
|
16 | * A reference to an empty paragraph in the body
|
17 | * created when there is no element in the body for the placeholder purposes.
|
18 | */
|
19 | private _bodyPlaceholder?;
|
20 | /**
|
21 | * @inheritDoc
|
22 | */
|
23 | static get pluginName(): 'Title';
|
24 | /**
|
25 | * @inheritDoc
|
26 | */
|
27 | static get requires(): readonly ["Paragraph"];
|
28 | /**
|
29 | * @inheritDoc
|
30 | */
|
31 | init(): void;
|
32 | /**
|
33 | * Returns the title of the document. Note that because this plugin does not allow any formatting inside
|
34 | * the title element, the output of this method will be a plain text, with no HTML tags.
|
35 | *
|
36 | * It is not recommended to use this method together with features that insert markers to the
|
37 | * data output, like comments or track changes features. If such markers start in the title and end in the
|
38 | * body, the result of this method might be incorrect.
|
39 | *
|
40 | * @param options Additional configuration passed to the conversion process.
|
41 | * See {@link module:engine/controller/datacontroller~DataController#get `DataController#get`}.
|
42 | * @returns The title of the document.
|
43 | */
|
44 | getTitle(options?: Record<string, unknown>): string;
|
45 | /**
|
46 | * Returns the body of the document.
|
47 | *
|
48 | * Note that it is not recommended to use this method together with features that insert markers to the
|
49 | * data output, like comments or track changes features. If such markers start in the title and end in the
|
50 | * body, the result of this method might be incorrect.
|
51 | *
|
52 | * @param options Additional configuration passed to the conversion process.
|
53 | * See {@link module:engine/controller/datacontroller~DataController#get `DataController#get`}.
|
54 | * @returns The body of the document.
|
55 | */
|
56 | getBody(options?: Record<string, unknown>): string;
|
57 | /**
|
58 | * Returns the `title` element when it is in the document. Returns `undefined` otherwise.
|
59 | */
|
60 | private _getTitleElement;
|
61 | /**
|
62 | * Model post-fixer callback that ensures that `title` has only one `title-content` child.
|
63 | * All additional children should be moved after the `title` element and renamed to a paragraph.
|
64 | */
|
65 | private _fixTitleContent;
|
66 | /**
|
67 | * Model post-fixer callback that creates a title element when it is missing,
|
68 | * takes care of the correct position of it and removes additional title elements.
|
69 | */
|
70 | private _fixTitleElement;
|
71 | /**
|
72 | * Model post-fixer callback that adds an empty paragraph at the end of the document
|
73 | * when it is needed for the placeholder purposes.
|
74 | */
|
75 | private _fixBodyElement;
|
76 | /**
|
77 | * Model post-fixer callback that removes a paragraph from the end of the document
|
78 | * if it was created for the placeholder purposes and is not needed anymore.
|
79 | */
|
80 | private _fixExtraParagraph;
|
81 | /**
|
82 | * Attaches the `Title` and `Body` placeholders to the title and/or content.
|
83 | */
|
84 | private _attachPlaceholders;
|
85 | /**
|
86 | * Creates navigation between the title and body sections using <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys.
|
87 | */
|
88 | private _attachTabPressHandling;
|
89 | }
|
90 | /**
|
91 | * The configuration of the {@link module:heading/title~Title title feature}.
|
92 | *
|
93 | * ```ts
|
94 | * ClassicEditor
|
95 | * .create( document.querySelector( '#editor' ), {
|
96 | * plugins: [ Title, ... ],
|
97 | * title: {
|
98 | * placeholder: 'My custom placeholder for the title'
|
99 | * },
|
100 | * placeholder: 'My custom placeholder for the body'
|
101 | * } )
|
102 | * .then( ... )
|
103 | * .catch( ... );
|
104 | * ```
|
105 | *
|
106 | * See {@link module:core/editor/editorconfig~EditorConfig all editor configuration options}.
|
107 | */
|
108 | export interface TitleConfig {
|
109 | /**
|
110 | * Defines a custom value of the placeholder for the title field.
|
111 | *
|
112 | * Read more in {@link module:heading/title~TitleConfig}.
|
113 | */
|
114 | placeholder?: string;
|
115 | }
|