/
htmlembed.js
122 lines (112 loc) · 3.67 KB
/
htmlembed.js
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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
/**
* @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
*/
/**
* @module html-embed/htmlembed
*/
import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
import HtmlEmbedEditing from './htmlembedediting';
import HtmlEmbedUI from './htmlembedui';
/**
* The HTML embed feature.
*
* It allows inserting HTML snippets directly into the editor.
*
* For a detailed overview, check the {@glink features/html-embed HTML embed feature} documentation.
*
* @extends module:core/plugin~Plugin
*/
export default class HtmlEmbed extends Plugin {
/**
* @inheritDoc
*/
static get requires() {
return [ HtmlEmbedEditing, HtmlEmbedUI ];
}
/**
* @inheritDoc
*/
static get pluginName() {
return 'HtmlEmbed';
}
}
/**
* The configuration of the HTML embed feature.
*
* ClassicEditor
* .create( editorElement, {
* htmlEmbed: ... // HTML embed feature options.
* } )
* .then( ... )
* .catch( ... );
*
* See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
*
* @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/htmlembed~HtmlEmbedConfig#sanitizeHtml `config.htmlEmbed.sanitizeHtml()`}.
*
* Read more about the security aspect of this feature in the {@glink features/html-embed#security "Security"} section of
* the {@glink features/html-embed HTML embed} feature guide.
*
* @member {Boolean} [module:html-embed/htmlembed~HtmlEmbedConfig#showPreviews=false]
*/
/**
* 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-embed#security "Security"} section of
* the {@glink features/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/htmlembed~HtmlEmbedSanitizeOutput} interface.
*
* 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/htmlembed~HtmlEmbedConfig#showPreviews is configured to render previews}.
*
* @member {Function} [module:html-embed/htmlembed~HtmlEmbedConfig#sanitizeHtml]
*/
/**
* An object returned by the {@link module:html-embed/htmlembed~HtmlEmbedConfig#sanitizeHtml} function.
*
* @interface HtmlEmbedSanitizeOutput
*/
/**
* An output (safe) HTML that will be inserted into the {@glink framework/guides/architecture/editing-engine editing view}.
*
* @member {String} module:html-embed/htmlembed~HtmlEmbedSanitizeOutput#html
*/
/**
* A flag that indicates whether the output HTML is different than the input value.
*
* @member {Boolean} [module:html-embed/htmlembed~HtmlEmbedSanitizeOutput#hasChanged]
*/