Explorar el Código

Wording in API docs.

Piotrek Koszuliński hace 5 años
padre
commit
bf36bf0f73

+ 5 - 0
packages/ckeditor5-html-embed/docs/features/html-embed.md

@@ -39,6 +39,11 @@ ClassicEditor
 	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
 </info-box>
 
+### Security
+
+TODO
+Note: it's mentioned in the config.htmlEmbed.* options so if we'll decide to rename this section we'll need to change it there.
+
 ## Common API
 
 The {@link module:html-embed/htmlembed~HtmlEmbed} plugin registers:

+ 35 - 30
packages/ckeditor5-html-embed/src/htmlembed.js

@@ -52,65 +52,70 @@ export default class HtmlEmbed extends Plugin {
  */
 
 /**
- * Controls the view produced by the feature.
+ * Whether the feature should render previews of the the embedded HTML.
  *
- * When `false` (default), the feature produces the `<textarea>` element in the view.
+ * 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.
  *
- * When `true`, the inserted HTML will be injected directly to the editor.
+ * The function responsible for sanitizing the HTML needs to be specified in
+ * {@link module:html-embed/htmlembed~HtmlEmbedConfig#sanitizeHtml `config.htmlEmbed.sanitizeHtml()`}.
  *
- * **Note:** If the option was set to `true`, do not forget about implementing
- * the {@link module:html-embed/htmlembed~HtmlEmbedConfig#sanitizeHtml `htmlEmbed.sanitizeHtml()`} function that will control
- * the output HTML.
+ * 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]
  */
 
 /**
- * Allows modifying an input HTML before injecting it directly to the editor's view.
+ * Callback used to sanitize HTML provided by the user when generating previews of it in the editor.
  *
- * We strongly recommend to overwrite the default function to avoid XSS vulnerability.
+ * We strongly recommend to overwrite the default function to avoid XSS vulnerabilities.
  *
- * The function receives an input HTML (`String`), and should return an object
- * that match to the {@link module:html-embed/htmlembed~HtmlEmbedSanitizeOutput} interface.
+ * 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, {
+ * 			.create( editorElement, {
  * 				htmlEmbed: {
- * 				    showPreviews: true,
- * 				    sanitizeHtml( inputHtml ) {
- * 				        // Strip dangerous elements and attributes, e.g.:
- * 				        // the `<script>` elements or `[on*]` attributes.
- *
- * 				        return {
- * 				            html: ...,
- * 				            hasModified: ...
- * 				        }
- * 				    },
+ * 					showPreviews: true,
+ * 					sanitizeHtml( inputHtml ) {
+ * 						// Strip unsafe elements and attributes, e.g.:
+ * 						// the `<script>` elements and `on*` attributes.
+ * 						const outputHtml = sanitize( inputHtml );
+ *
+ * 						return {
+ * 							html: outputHtml,
+ * 							hasChanged: ...
+ * 						}
+ * 					},
  * 				}
- *			} )
- *			.then( ... )
- *			.catch( ... );
+ * 			} )
+ * 			.then( ... )
+ * 			.catch( ... );
  *
- *	**Note:** The function is used only if the feature has enabled previews in the view
- *	({@link module:html-embed/htmlembed~HtmlEmbedConfig#showPreviews} is set to `true`).
+ * **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 should match to this interface.
+ * An object returned by the {@link module:html-embed/htmlembed~HtmlEmbedConfig#sanitizeHtml} function.
  *
  * @interface HtmlEmbedSanitizeOutput
  */
 
 /**
- * An output HTML that will be inserted into the {@glink framework/guides/architecture/editing-engine editing view}.
+ * 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 describes whether the output HTML is different that an input value.
+ * A flag that indicates whether the output HTML is different than the input value.
  *
- * @member {Boolean} [module:html-embed/htmlembed~HtmlEmbedSanitizeOutput#hasModified]
+ * @member {Boolean} [module:html-embed/htmlembed~HtmlEmbedSanitizeOutput#hasChanged]
  */

+ 1 - 1
packages/ckeditor5-html-embed/src/htmlembedediting.js

@@ -58,7 +58,7 @@ export default class HtmlEmbedEditing extends Plugin {
 
 				return {
 					html: rawHtml,
-					hasModified: false
+					hasChanged: false
 				};
 			}
 		} );

+ 1 - 1
packages/ckeditor5-html-embed/tests/htmlembedediting.js

@@ -90,7 +90,7 @@ describe( 'HtmlEmbedEditing', () => {
 			it( 'should return an object with cleaned html and a note whether something has changed', () => {
 				expect( htmlEmbed.sanitizeHtml( 'foo' ) ).to.deep.equal( {
 					html: 'foo',
-					hasModified: false
+					hasChanged: false
 				} );
 			} );
 

+ 1 - 1
packages/ckeditor5-html-embed/tests/manual/htmlembed.js

@@ -42,7 +42,7 @@ async function startEnabledPreviewsMode() {
 
 				return {
 					html: cleanHtml,
-					hasModified: rawHtml !== cleanHtml
+					hasChanged: rawHtml !== cleanHtml
 				};
 			}
 		}