htmlembed.js 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module html-embed/htmlembed
  7. */
  8. import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
  9. import HtmlEmbedEditing from './htmlembedediting';
  10. import HtmlEmbedUI from './htmlembedui';
  11. /**
  12. * The HTML embed feature.
  13. *
  14. * It allows inserting HTML snippets directly into the editor.
  15. *
  16. * For a detailed overview, check the {@glink features/html-embed HTML embed feature} documentation.
  17. *
  18. * @extends module:core/plugin~Plugin
  19. */
  20. export default class HtmlEmbed extends Plugin {
  21. /**
  22. * @inheritDoc
  23. */
  24. static get requires() {
  25. return [ HtmlEmbedEditing, HtmlEmbedUI ];
  26. }
  27. /**
  28. * @inheritDoc
  29. */
  30. static get pluginName() {
  31. return 'HtmlEmbed';
  32. }
  33. }
  34. /**
  35. * The configuration of the HTML embed feature.
  36. *
  37. * ClassicEditor
  38. * .create( editorElement, {
  39. * htmlEmbed: ... // HTML embed feature options.
  40. * } )
  41. * .then( ... )
  42. * .catch( ... );
  43. *
  44. * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
  45. *
  46. * @interface HtmlEmbedConfig
  47. */
  48. /**
  49. * Whether the feature should render previews of the embedded HTML.
  50. *
  51. * When set to `true`, the feature will produce a preview of the inserted HTML based on a sanitized
  52. * version of the HTML provided by the user.
  53. *
  54. * The function responsible for sanitizing the HTML needs to be specified in
  55. * {@link module:html-embed/htmlembed~HtmlEmbedConfig#sanitizeHtml `config.htmlEmbed.sanitizeHtml()`}.
  56. *
  57. * Read more about the security aspect of this feature in the {@glink features/html-embed#security "Security"} section of
  58. * the {@glink features/html-embed HTML embed} feature guide.
  59. *
  60. * @member {Boolean} [module:html-embed/htmlembed~HtmlEmbedConfig#showPreviews=false]
  61. */
  62. /**
  63. * Callback used to sanitize the HTML provided by the user when generating previews of it in the editor.
  64. *
  65. * We strongly recommend overwriting the default function to avoid XSS vulnerabilities.
  66. *
  67. * Read more about the security aspect of this feature in the {@glink features/html-embed#security "Security"} section of
  68. * the {@glink features/html-embed HTML embed} feature guide.
  69. *
  70. * The function receives the input HTML (as a string), and should return an object
  71. * that matches the {@link module:html-embed/htmlembed~HtmlEmbedSanitizeOutput} interface.
  72. *
  73. * ClassicEditor
  74. * .create( editorElement, {
  75. * htmlEmbed: {
  76. * showPreviews: true,
  77. * sanitizeHtml( inputHtml ) {
  78. * // Strip unsafe elements and attributes, e.g.:
  79. * // the `<script>` elements and `on*` attributes.
  80. * const outputHtml = sanitize( inputHtml );
  81. *
  82. * return {
  83. * html: outputHtml,
  84. * // true or false depending on whether the sanitizer stripped anything.
  85. * hasChanged: ...
  86. * };
  87. * },
  88. * }
  89. * } )
  90. * .then( ... )
  91. * .catch( ... );
  92. *
  93. * **Note:** The function is used only when the feature
  94. * {@link module:html-embed/htmlembed~HtmlEmbedConfig#showPreviews is configured to render previews}.
  95. *
  96. * @member {Function} [module:html-embed/htmlembed~HtmlEmbedConfig#sanitizeHtml]
  97. */
  98. /**
  99. * An object returned by the {@link module:html-embed/htmlembed~HtmlEmbedConfig#sanitizeHtml} function.
  100. *
  101. * @interface HtmlEmbedSanitizeOutput
  102. */
  103. /**
  104. * An output (safe) HTML that will be inserted into the {@glink framework/guides/architecture/editing-engine editing view}.
  105. *
  106. * @member {String} module:html-embed/htmlembed~HtmlEmbedSanitizeOutput#html
  107. */
  108. /**
  109. * A flag that indicates whether the output HTML is different than the input value.
  110. *
  111. * @member {Boolean} [module:html-embed/htmlembed~HtmlEmbedSanitizeOutput#hasChanged]
  112. */