8
0
Просмотр исходного кода

Improved docs and manual test.

Kamil Piechaczek 5 лет назад
Родитель
Сommit
323b06ac40

+ 18 - 2
packages/ckeditor5-html-embed/README.md

@@ -1,4 +1,20 @@
 CKEditor 5 HTML embed feature
 CKEditor 5 HTML embed feature
-===========================
+=============================
 
 
-This is an initial package for development purposes. It does not contain code yet.
+[![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-html-embed.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-html-embed)
+[![Dependency Status](https://david-dm.org/ckeditor/ckeditor5-html-embed/status.svg)](https://david-dm.org/ckeditor/ckeditor5-html-embed)
+[![devDependency Status](https://david-dm.org/ckeditor/ckeditor5-html-embed/dev-status.svg)](https://david-dm.org/ckeditor/ckeditor5-html-embed?type=dev)
+
+This package implements the HTML embed feature for CKEditor 5.
+
+## Demo
+
+Check out the demo in the [HTML embed feature](https://ckeditor.com/docs/ckeditor5/latest/features/html-embed.html) guide.
+
+## Documentation
+
+See the [`@ckeditor/ckeditor5-html-embed` package](https://ckeditor.com/docs/ckeditor5/latest/api/html-embed.html) page as well as the [HTML embed feature guide](https://ckeditor.com/docs/ckeditor5/latest/features/html-embed.html) in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/).
+
+## License
+
+Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html). For full details about the license, please check the `LICENSE.md` file or [https://ckeditor.com/legal/ckeditor-oss-license](https://ckeditor.com/legal/ckeditor-oss-license).

+ 7 - 2
packages/ckeditor5-html-embed/package.json

@@ -13,11 +13,16 @@
     "@ckeditor/ckeditor5-core": "^23.0.0",
     "@ckeditor/ckeditor5-core": "^23.0.0",
     "@ckeditor/ckeditor5-engine": "^23.0.0",
     "@ckeditor/ckeditor5-engine": "^23.0.0",
     "@ckeditor/ckeditor5-ui": "^23.0.0",
     "@ckeditor/ckeditor5-ui": "^23.0.0",
-    "@ckeditor/ckeditor5-widget": "^23.0.0",
+    "@ckeditor/ckeditor5-utils": "^23.0.0",
+    "@ckeditor/ckeditor5-widget": "^23.0.0"
+  },
+  "devDependencies": {
+    "@ckeditor/ckeditor5-basic-styles": "^23.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^23.0.0",
+    "@ckeditor/ckeditor5-paragraph": "^23.0.0",
     "lodash-es": "^4.17.15",
     "lodash-es": "^4.17.15",
     "sanitize-html": "^2.1.0"
     "sanitize-html": "^2.1.0"
   },
   },
-  "devDependencies": {},
   "engines": {
   "engines": {
     "node": ">=12.0.0",
     "node": ">=12.0.0",
     "npm": ">=5.7.1"
     "npm": ">=5.7.1"

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

@@ -14,7 +14,7 @@ import HtmlEmbedUI from './htmlembedui';
 /**
 /**
  * The HTML embed feature.
  * The HTML embed feature.
  *
  *
- * @TODO: What does it allow doing?
+ * It allows inserting HTML snippets directly to the editor.
  *
  *
  * For a detailed overview, check the {@glink features/html-embed HTML embed feature} documentation.
  * For a detailed overview, check the {@glink features/html-embed HTML embed feature} documentation.
  *
  *

+ 7 - 6
packages/ckeditor5-html-embed/src/htmlembedediting.js

@@ -45,8 +45,9 @@ export default class HtmlEmbedEditing extends Plugin {
 			sanitizeHtml: rawHtml => {
 			sanitizeHtml: rawHtml => {
 				/**
 				/**
 				 * When using the HTML embed feature with `htmlEmbed.previewsInData=true` option, it's strongly recommended to
 				 * When using the HTML embed feature with `htmlEmbed.previewsInData=true` option, it's strongly recommended to
-				 * define a sanitize function that will clean an input HTML in order to avoid XSS vulnerability.
-				 * TODO: Add a link to the feature documentation.
+				 * define a sanitize function that will clean up an input HTML in order to avoid XSS vulnerability.
+				 *
+				 * For a detailed overview, check the {@glink features/html-embed HTML embed feature} documentation.
 				 *
 				 *
 				 * @error html-embed-provide-sanitize-function
 				 * @error html-embed-provide-sanitize-function
 				 * @param {String} name The name of the component.
 				 * @param {String} name The name of the component.
@@ -84,7 +85,7 @@ export default class HtmlEmbedEditing extends Plugin {
 	}
 	}
 
 
 	/**
 	/**
-	 * Set-ups converters for the feature.
+	 * Prepares converters for the feature.
 	 *
 	 *
 	 * @private
 	 * @private
 	 */
 	 */
@@ -213,7 +214,7 @@ export default class HtmlEmbedEditing extends Plugin {
 
 
 // Returns a converter that handles the `value` attribute of the `rawHtml` element.
 // Returns a converter that handles the `value` attribute of the `rawHtml` element.
 //
 //
-// It updates the source (`textarea`) value and passes an HTML to the preview element in `htmlEmbed.previewsInData=true` mode.
+// It updates the source (`textarea`) value and passes an HTML to the preview element if `htmlEmbed.previewsInData=true`.
 //
 //
 // @params {module:html-embed/htmlembed~MediaEmbedConfig} htmlEmbedConfig
 // @params {module:html-embed/htmlembed~MediaEmbedConfig} htmlEmbedConfig
 // @returns {Function}
 // @returns {Function}
@@ -241,8 +242,8 @@ function downcastRawHtmlValueAttribute( htmlEmbedConfig ) {
 	};
 	};
 }
 }
 
 
-// Converts a given {@link module:engine/view/element~Element} to a html widget:
-// * Adds a {@link module:engine/view/element~Element#_setCustomProperty custom property} allowing to recognize the html widget element.
+// Converts a given {@link module:engine/view/element~Element} to a raw html widget:
+// * Adds a {@link module:engine/view/element~Element#_setCustomProperty custom property} allowing to recognize the raw html widget element.
 // * Calls the {@link module:widget/utils~toWidget} function with the proper element's label creator.
 // * Calls the {@link module:widget/utils~toWidget} function with the proper element's label creator.
 //
 //
 //  @param {module:engine/view/element~Element} viewElement
 //  @param {module:engine/view/element~Element} viewElement

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

@@ -15,7 +15,7 @@ import { findOptimalInsertionPosition } from '@ckeditor/ckeditor5-widget/src/uti
  *
  *
  * The command is registered by {@link module:html-embed/htmlembedediting~HtmlEmbedEditing} as `'htmlEmbedInsert'`.
  * The command is registered by {@link module:html-embed/htmlembedediting~HtmlEmbedEditing} as `'htmlEmbedInsert'`.
  *
  *
- * To insert a page break at the current selection, execute the command:
+ * To insert the raw html element at the current selection, execute the command:
  *
  *
  *		editor.execute( 'htmlEmbedInsert' );
  *		editor.execute( 'htmlEmbedInsert' );
  *
  *

+ 138 - 59
packages/ckeditor5-html-embed/tests/manual/htmlembed.html

@@ -1,3 +1,7 @@
+<head>
+    <meta http-equiv="Content-Security-Policy" content="default-src 'none'; media-src http://techslides.com/; connect-src 'self' https://cksource.com http://*.cke-cs.com; script-src 'self' https://cksource.com; img-src * data:; style-src 'self' 'unsafe-inline'; frame-src *">
+</head>
+
 <p>
 <p>
     <b>Mode of HTML previews</b>:
     <b>Mode of HTML previews</b>:
     <input type="radio" id="mode-enabled" name="mode" value="enabled" checked><label for="mode-enabled">Enabled</label>
     <input type="radio" id="mode-enabled" name="mode" value="enabled" checked><label for="mode-enabled">Enabled</label>
@@ -5,74 +9,149 @@
 </p>
 </p>
 
 
 <div id="editor">
 <div id="editor">
-<!--    <div class="raw-html-embed">-->
-<!--        <video width="320" height="240" controls>-->
-<!--            <source src="http://techslides.com/demos/sample-videos/small.mp4" type="video/mp4">-->
-<!--            <source src="http://techslides.com/demos/sample-videos/small.ogv" type="video/ogg">-->
-<!--            Your browser does not support the video tag.-->
-<!--        </video>-->
-<!--    </div>-->
+    <h3><code>&lt;video&gt;</code> tag as HTML snippet</h3>
+        <div class="raw-html-embed">
+            <video width="320" height="240" controls>
+                <source src="http://techslides.com/demos/sample-videos/small.mp4" type="video/mp4">
+                <source src="http://techslides.com/demos/sample-videos/small.ogv" type="video/ogg">
+                Your browser does not support the video tag.
+            </video>
+        </div>
+
 
 
+    <h3><code>&lt;audio&gt;</code> tag as HTML snippet</h3>
+        <div class="raw-html-embed">
+            <audio controls>
+                <source src="http://techslides.com/demos/samples/sample.ogg" type="audio/ogg">
+                <source src="http://techslides.com/demos/samples/sample.mp3" type="audio/mpeg">
+                Your browser does not support the audio tag.
+            </audio>
+        </div>
 
 
-<!--    <div class="raw-html-embed">-->
-<!--        <audio controls>-->
-<!--            <source src="http://techslides.com/demos/samples/sample.ogg" type="audio/ogg">-->
-<!--            <source src="http://techslides.com/demos/samples/sample.mp3" type="audio/mpeg">-->
-<!--            Your browser does not support the audio tag.-->
-<!--        </audio>-->
-<!--    </div>-->
 
 
+    <h3><code>&lt;picture&gt;</code> tag as HTML snippet</h3>
+        <div class="raw-html-embed">
+            <picture>
+                <source media="(min-width: 1200px)" srcset="http://techslides.com/demos/samples/sample.jpg">
+                <source media="(min-width: 650px)" srcset="http://techslides.com/demos/samples/sample.png">
+                <img src="http://techslides.com/demos/samples/sample.gif">
+            </picture>
+        </div>
 
 
-<!--    <div class="raw-html-embed">-->
-<!--        <picture>-->
-<!--            <source media="(min-width: 650px)" srcset="http://techslides.com/demos/samples/sample.jpg">-->
-<!--            <source media="(min-width: 465px)" srcset="http://techslides.com/demos/samples/sample.png">-->
-<!--            <img src="http://techslides.com/demos/samples/sample.gif">-->
-<!--        </picture>-->
-<!--    </div>-->
+    <h3><code>&lt;iframe&gt;</code> tag as HTML snippet</h3>
+        <div class="raw-html-embed">
+            <iframe src="http://techslides.com/demos/samples/sample.txt"></iframe>
+        </div>
 
 
 
 
-<!--    <div class="raw-html-embed">-->
-<!--        <form action="/my-handling-form-page" method="post">-->
-<!--            <ul>-->
-<!--                <li>-->
-<!--                    <label for="name">Name:</label>-->
-<!--                    <input type="text" id="name" name="user_name">-->
-<!--                </li>-->
-<!--                <li>-->
-<!--                    <label for="mail">E-mail:</label>-->
-<!--                    <input type="email" id="mail" name="user_email">-->
-<!--                </li>-->
-<!--                <li>-->
-<!--                    <label for="msg">Message:</label>-->
-<!--                    <textarea id="msg" name="user_message"></textarea>-->
-<!--                </li>-->
-<!--            </ul>-->
-<!--        </form>-->
-<!--    </div>-->
+    <h3><code>&lt;table&gt;</code> tag as HTML snippet (code coverage report)</h3>
+    <div class="raw-html-embed">
+        <table class="coverage-summary">
+            <thead>
+            <tr>
+                <th data-col="file" data-fmt="html" data-html="true" class="file">File</th>
+                <th data-col="pic" data-type="number" data-fmt="html" data-html="true" class="pic"></th>
+                <th data-col="statements" data-type="number" data-fmt="pct" class="pct">Statements</th>
+                <th data-col="statements_raw" data-type="number" data-fmt="html" class="abs"></th>
+                <th data-col="branches" data-type="number" data-fmt="pct" class="pct">Branches</th>
+                <th data-col="branches_raw" data-type="number" data-fmt="html" class="abs"></th>
+                <th data-col="functions" data-type="number" data-fmt="pct" class="pct">Functions</th>
+                <th data-col="functions_raw" data-type="number" data-fmt="html" class="abs"></th>
+                <th data-col="lines" data-type="number" data-fmt="pct" class="pct">Lines</th>
+                <th data-col="lines_raw" data-type="number" data-fmt="html" class="abs"></th>
+            </tr>
+            </thead>
+            <tbody>
+            <tr>
+                <td class="file high" data-value="htmlembed.js">htmlembed.js</td>
+                <td data-value="100" class="pic high">
+                    <div class="chart">
+                        <div class="cover-fill cover-full" style="width: 100%"></div>
+                        <div class="cover-empty" style="width: 0%"></div>
+                    </div>
+                </td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="2" class="abs high">2/2</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="0" class="abs high">0/0</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="2" class="abs high">2/2</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="2" class="abs high">2/2</td>
+            </tr>
 
 
+            <tr>
+                <td class="file high" data-value="htmlembedediting.js">htmlembedediting.js</td>
+                <td data-value="100" class="pic high">
+                    <div class="chart">
+                        <div class="cover-fill cover-full" style="width: 100%"></div>
+                        <div class="cover-empty" style="width: 0%"></div>
+                    </div>
+                </td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="81" class="abs high">81/81</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="18" class="abs high">18/18</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="19" class="abs high">19/19</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="81" class="abs high">81/81</td>
+            </tr>
 
 
-<!--    <div class="raw-html-embed">-->
-<!--        <iframe src="http://techslides.com/demos/samples/sample.txt"></iframe>-->
-<!--    </div>-->
+            <tr>
+                <td class="file high" data-value="htmlembedinsertcommand.js">htmlembedinsertcommand.js</td>
+                <td data-value="100" class="pic high">
+                    <div class="chart">
+                        <div class="cover-fill cover-full" style="width: 100%"></div>
+                        <div class="cover-empty" style="width: 0%"></div>
+                    </div>
+                </td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="18" class="abs high">18/18</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="8" class="abs high">8/8</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="7" class="abs high">7/7</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="18" class="abs high">18/18</td>
+            </tr>
 
 
+            <tr>
+                <td class="file high" data-value="htmlembedui.js">htmlembedui.js</td>
+                <td data-value="100" class="pic high">
+                    <div class="chart">
+                        <div class="cover-fill cover-full" style="width: 100%"></div>
+                        <div class="cover-empty" style="width: 0%"></div>
+                    </div>
+                </td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="15" class="abs high">15/15</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="0" class="abs high">0/0</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="3" class="abs high">3/3</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="15" class="abs high">15/15</td>
+            </tr>
 
 
-    <div class="raw-html-embed">
-        <h2>Ingredients</h2>
-        <p>Ingredients required for making a coffee:</p>
-        <ul style="list-style-type:circle;">
-            <li>15g ground coffee</li>
-            <li>water</li>
-            <li>milk <i>(optional)</i></li>
-        </ul>
-        <h2>Instructions</h2>
-        <p>How to prepare a cup of coffee:</p>
-        <ol style="list-style-type:decimal-leading-zero;">
-            <li>Gather the ingredients.</li>
-            <li>Put 15g of ground coffee in the cup.</li>
-            <li>Boil 200ml of water.</li>
-            <li>Pour the water into the cup.</li>
-            <li>Optional: Add milk.</li>
-        </ol>
+            <tr>
+                <td class="file high" data-value="htmlembedupdatecommand.js">htmlembedupdatecommand.js</td>
+                <td data-value="100" class="pic high">
+                    <div class="chart">
+                        <div class="cover-fill cover-full" style="width: 100%"></div>
+                        <div class="cover-empty" style="width: 0%"></div>
+                    </div>
+                </td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="13" class="abs high">13/13</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="4" class="abs high">4/4</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="4" class="abs high">4/4</td>
+                <td data-value="100" class="pct high">100%</td>
+                <td data-value="13" class="abs high">13/13</td>
+            </tr>
+            </tbody>
+        </table>
     </div>
     </div>
 </div>
 </div>

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

@@ -5,10 +5,11 @@
 
 
 /* globals window, document */
 /* globals window, document */
 
 
-import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
-import ArticlePluginSet from '@ckeditor/ckeditor5-core/tests/_utils/articlepluginset';
 import sanitizeHtml from 'sanitize-html';
 import sanitizeHtml from 'sanitize-html';
 import { clone } from 'lodash-es';
 import { clone } from 'lodash-es';
+import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
+import ArticlePluginSet from '@ckeditor/ckeditor5-core/tests/_utils/articlepluginset';
+import Code from '@ckeditor/ckeditor5-basic-styles/src/code';
 import HtmlEmbed from '../../src/htmlembed';
 import HtmlEmbed from '../../src/htmlembed';
 
 
 const restrictedModeButton = document.getElementById( 'mode-enabled' );
 const restrictedModeButton = document.getElementById( 'mode-enabled' );
@@ -58,7 +59,7 @@ async function reloadEditor( config = {} ) {
 	}
 	}
 
 
 	config = Object.assign( config, {
 	config = Object.assign( config, {
-		plugins: [ ArticlePluginSet, HtmlEmbed ],
+		plugins: [ ArticlePluginSet, HtmlEmbed, Code ],
 		toolbar: [
 		toolbar: [
 			'heading', '|', 'bold', 'italic', 'link', '|',
 			'heading', '|', 'bold', 'italic', 'link', '|',
 			'bulletedList', 'numberedList', 'blockQuote', 'insertTable', '|',
 			'bulletedList', 'numberedList', 'blockQuote', 'insertTable', '|',
@@ -106,9 +107,8 @@ function getSanitizeHtmlConfig( defaultConfig ) {
 		config.allowedAttributes[ htmlTag ].push( 'style' );
 		config.allowedAttributes[ htmlTag ].push( 'style' );
 	}
 	}
 
 
-	// Should we allow the `controls` attribute?
-	config.allowedAttributes.video.push( 'width', 'height', 'controls' );
 	config.allowedAttributes.audio.push( 'controls' );
 	config.allowedAttributes.audio.push( 'controls' );
+	config.allowedAttributes.video.push( 'width', 'height', 'controls' );
 
 
 	config.allowedAttributes.iframe.push( 'src' );
 	config.allowedAttributes.iframe.push( 'src' );
 	config.allowedAttributes.img.push( 'srcset', 'sizes', 'src' );
 	config.allowedAttributes.img.push( 'srcset', 'sizes', 'src' );

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

@@ -1 +1,38 @@
-HTML embed.
+## HTML embed feature
+
+--- 
+
+**This test has changed the CSP definitions:**
+
+```html
+<meta http-equiv="Content-Security-Policy" content="
+    default-src 'none'; 
+    media-src http://techslides.com/; 
+    connect-src 'self' https://cksource.com http://*.cke-cs.com; 
+    script-src 'self' https://cksource.com; 
+    img-src * data:; 
+    style-src 'self' 'unsafe-inline'; 
+    frame-src *"
+>
+```
+
+---
+
+After the editor initialization, it should contain 5 widgets with embedded HTML:
+
+- `video`
+- `audio`
+- `picture` (resize the window to see other images, limits: 1200px, 650px)
+- `iframe`
+- `table`
+
+All resources are provided by the ["Sample Files for Development"](http://techslides.com/sample-files-for-development) article. Thanks!
+
+By default, the previews in data mode is enabled. It means that previews should be visible. 
+
+We use the [`sanitize-html`](https://www.npmjs.com/package/sanitize-html) package to clean up the input HTML. It means that some of the 
+elements or attributes may be not rendered in the editing view. However, they still will be returned in the editor's data.
+
+You can disable the preview mode and have the `textarea` element that will be blocked or enabled (depends on feature state).
+
+For toggling the state (edit source / see preview), click the icon in the right-top corner.