-
Notifications
You must be signed in to change notification settings - Fork 3.6k
/
htmlembedconfig.ts
93 lines (86 loc) · 2.99 KB
/
htmlembedconfig.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
/**
* @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
*/
/**
* @module html-embed/htmlembedconfig
*/
/**
* The configuration of the HTML embed feature.
*
* ```ts
* ClassicEditor
* .create( editorElement, {
* htmlEmbed: ... // HTML embed feature options.
* } )
* .then( ... )
* .catch( ... );
* ```
*
* See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
*/
export interface HtmlEmbedConfig {
/**
* Whether the feature should render previews of the embedded HTML.
*
* When set to `true`, the feature will produce a preview of the inserted HTML based on a sanitized
* version of the HTML provided by the user.
*
* The function responsible for sanitizing the HTML needs to be specified in
* {@link module:html-embed/htmlembedconfig~HtmlEmbedConfig#sanitizeHtml `config.htmlEmbed.sanitizeHtml()`}.
*
* Read more about the security aspect of this feature in the {@glink features/html/html-embed#security "Security"} section of
* the {@glink features/html/html-embed HTML embed} feature guide.
*/
showPreviews?: boolean;
/**
* Callback used to sanitize the HTML provided by the user when generating previews of it in the editor.
*
* We strongly recommend overwriting the default function to avoid XSS vulnerabilities.
*
* Read more about the security aspect of this feature in the {@glink features/html/html-embed#security "Security"} section of
* the {@glink features/html/html-embed HTML embed} feature guide.
*
* The function receives the input HTML (as a string), and should return an object
* that matches the {@link module:html-embed/htmlembedconfig~HtmlEmbedSanitizeOutput} interface.
*
* ```ts
* ClassicEditor
* .create( editorElement, {
* htmlEmbed: {
* showPreviews: true,
* sanitizeHtml( inputHtml ) {
* // Strip unsafe elements and attributes, e.g.:
* // the `<script>` elements and `on*` attributes.
* const outputHtml = sanitize( inputHtml );
*
* return {
* html: outputHtml,
* // true or false depending on whether the sanitizer stripped anything.
* hasChanged: ...
* };
* },
* }
* } )
* .then( ... )
* .catch( ... );
* ```
*
* **Note:** The function is used only when the feature
* {@link module:html-embed/htmlembedconfig~HtmlEmbedConfig#showPreviews is configured to render previews}.
*/
sanitizeHtml?: ( html: string ) => HtmlEmbedSanitizeOutput;
}
/**
* An object returned by the {@link module:html-embed/htmlembedconfig~HtmlEmbedConfig#sanitizeHtml} function.
*/
export interface HtmlEmbedSanitizeOutput {
/**
* An output (safe) HTML that will be inserted into the {@glink framework/architecture/editing-engine editing view}.
*/
html: string;
/**
* A flag that indicates whether the output HTML is different than the input value.
*/
hasChanged: boolean;
}