Parcourir la source

Update feature docs and API.

panr il y a 5 ans
Parent
commit
fc29bb19d8

+ 9 - 0
packages/ckeditor5-image/docs/_snippets/features/image-insert-via-url-integrations.html

@@ -0,0 +1,9 @@
+<script src="https://ckeditor.com/apps/ckfinder/3.5.0/ckfinder.js"></script>
+
+<div id="snippet-image-insert-via-url-with-integrations">
+	<p>This is <a href="https://ckeditor.com/ckfinder/">CKEditor&nbsp;5 with CKFinder</a>.</p>
+
+	<figure class="image">
+		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
+	</figure>
+</div>

+ 38 - 0
packages/ckeditor5-image/docs/_snippets/features/image-insert-via-url-integrations.js

@@ -0,0 +1,38 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config.js';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-image-insert-via-url-with-integrations' ), {
+		removePlugins: [ 'ImageToolbar', 'ImageCaption', 'ImageStyle', 'ImageResize', 'LinkImage' ],
+		toolbar: {
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		},
+		image: {
+			toolbar: [ 'imageStyle:full', 'imageStyle:side', '|', 'imageTextAlternative' ],
+			upload: {
+				panel: {
+					items: [
+						'insertImageViaUrl',
+						'openCKFinder'
+					]
+				}
+			}
+		},
+		ckfinder: {
+			// eslint-disable-next-line max-len
+			uploadUrl: 'https://ckeditor.com/apps/ckfinder/3.5.0/core/connector/php/connector.php?command=QuickUpload&type=Files&responseType=json'
+		},
+		cloudServices: CS_CONFIG
+	} )
+	.then( editor => {
+		window.imageViaUrlWithIntegrations = editor;
+	} )
+	.catch( err => {
+		console.error( err );
+	} );

+ 7 - 0
packages/ckeditor5-image/docs/_snippets/features/image-insert-via-url.html

@@ -0,0 +1,7 @@
+<div id="snippet-image-insert-via-url">
+	<p>This is <a href="https://ckeditor.com">CKEditor&nbsp;5</a>.</p>
+
+	<figure class="image">
+		<img src="%BASE_PATH%/assets/img/fields.jpg" alt="Autumn fields">
+	</figure>
+</div>

+ 26 - 0
packages/ckeditor5-image/docs/_snippets/features/image-insert-via-url.js

@@ -0,0 +1,26 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals ClassicEditor, console, window, document */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config.js';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-image-insert-via-url' ), {
+		removePlugins: [ 'ImageToolbar', 'ImageCaption', 'ImageStyle', 'ImageResize', 'LinkImage' ],
+		toolbar: {
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		},
+		image: {
+			toolbar: [ 'imageStyle:full', 'imageStyle:side', '|', 'imageTextAlternative' ]
+		},
+		cloudServices: CS_CONFIG
+	} )
+	.then( editor => {
+		window.imageViaUrl = editor;
+	} )
+	.catch( err => {
+		console.error( err );
+	} );

+ 91 - 0
packages/ckeditor5-image/docs/features/image.md

@@ -82,6 +82,97 @@ By default, if the image caption is empty, the `<figcaption>` element is not vis
 
 See the {@link features/image-upload Image upload} guide.
 
+## Insert image via URL
+
+Another great feature is an ability to insert an image via URL address. The feature is available under the dropdown of the **Image Upload** feature. When you click on the arrow button, you will see a small panel view containing the form for an image source URL. Once you fill it, you will be able to insert the image into the editor's content.
+
+### Replace image via URL
+
+Yet, another cool thing that the feature introduces is an ability to replace previously inserted image without loosing its styling and custom attributes (if it has ones). When you click on image and open the `{@link module:image/imageupload/ui/imageuploadpanelview~ImageUploadPanelView#dropdownView ImageUpload dropdown}` you will see that the **Insert image via url** form is already filled. This is the value of the selected image. You can easily edit it and update through the form.
+
+<info-box>
+<strong>Bonus tip</strong>: You can even edit the URL of an image inserted from the native file system or from — for example — `{@link module:ckfinder/ckfinder~CKFinder}`.
+</info-box>
+
+Here's the short demo:
+
+{@snippet features/image-insert-via-url}
+
+### How to add integrations
+
+By default, this feature doesn't need any configuration. You will get a dropdown button, where the main action (icon button) will open a native file dialog and the arrow button will open a dropdown with **Insert image via url** feature.
+
+#### CKFinder
+
+We also support the integration with {@link module:ckfinder/ckfinder~CKFinder} in that dropdown, but that's something that needs to be configured.
+
+Here's how you can do this:
+
+```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		// ...
+		image: {
+			// ...
+			upload: {
+				panel: {
+					items: [
+						'insertImageViaUrl',
+						// Add CKFinder predefined token.
+						'openCKFinder'
+					]
+				}
+			}
+		},
+		ckfinder: {
+			uploadUrl: ... // CKFinder upload URL.
+		}
+	})
+```
+
+As you can see, we added here a new `{@link module:image/imageupload~ImageUploadPanelConfig#items image.upload.panel.items}` configuration, where we defined our desired built-in integrations. Both strings (`insertImageViaUrl` and `openCKFinder`) are special tokens that `{@link module:image/imageupload~ImageUpload}` plugin understands.
+
+Below you can see the demo with built-in CKFinder integration:
+
+{@snippet features/image-insert-via-url-integrations}
+
+#### Custom integrations
+
+If you would want to add your own integration, based on your own plugin ({@link framework/guides/creating-simple-plugin see how to create one}), you have to add that plugin to the editor first and then — like in the configuration from the previous section — you should add your integration component's name (the same you used in the `{@link module:ui/componentfactory~ComponentFactory#add}` when you registered the button) to the `{@link module:image/imageupload~ImageUploadPanelConfig#items}` array.
+
+Here's an example:
+
+```js
+// Import your custom plugin.
+import PluginX from 'pluginX'
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		// Add your custom plugin to the editor's plugins.
+		plugins: [ Image, ImageToolbar, ImageUpload, PluginX ],
+		image: {
+			upload: {
+				panel: {
+					items: [
+						'insertImageViaUrl',
+						'openCKFinder',
+						// Use the plugin's registered component.
+						'pluginXButton'
+					]
+				}
+			}
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box>
+Keep in mind that the order of the integrations in configuration equals the order of those views in the `{@link module:image/imageupload/ui/imageuploadpanelview~ImageUploadPanelView#dropdownView}`. So in the dropdown panel view you will have: **Insert image via URL** form, next **CKFinder** button and then your custom component for **PluginX**.
+
+You can always change that order if you need.
+</info-box>
+
 ## Responsive images
 
 Support for responsive images in CKEditor 5 is brought by the {@link features/easy-image Easy Image} feature without any additional configuration. Refer to the {@link features/easy-image#responsive-images Easy Image integration} guide to learn how to use the feature in your project.

+ 52 - 0
packages/ckeditor5-image/src/imageupload.js

@@ -83,3 +83,55 @@ export default class ImageUpload extends Plugin {
  * @member {Array.<String>} module:image/imageupload~ImageUploadConfig#types
  * @default [ 'jpeg', 'png', 'gif', 'bmp', 'webp', 'tiff' ]
  */
+
+/**
+ * Image upload panel view configuration.
+ *
+ * @member {module:image/imageupload~ImageUploadPanelConfig} module:image/imageupload~ImageUploadConfig#panel
+ */
+
+/**
+ * The configuration of the image upload dropdown panel view. Used by the image upload feature in the `@ckeditor/ckeditor5-image` package.
+ *
+ *		ClassicEditor
+ *			.create( editorElement, {
+ * 				image: {
+ * 					upload: {
+ * 						panel: ... // panel settings goes here
+ * 					}
+ * 				}
+ *			} )
+ *			.then( ... )
+ *			.catch( ... );
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ *
+ * @interface module:image/imageupload~ImageUploadPanelConfig
+ */
+
+/**
+ * The list of {@link module:image/imageupload~ImageUpload} integrations.
+ *
+ * The option accepts string tokens.
+ * * for predefined integrations, we have two special strings: `insertImageViaUrl` and `openCKFinder`.
+ * The former adds **Insert image via URL** feature, but the latter adds built-in **CKFinder** integration.
+ * * for custom integrations, each string should be a name of the already registered component.
+ * If you have a plugin `PluginX` that registers `pluginXButton` component, then the integration token
+ * in that case should be `pluginXButton`.
+ *
+ *		// Add `insertImageViaUrl`, `openCKFinder` and custom `pluginXButton` integrations.
+ *		const imageUploadConfig = {
+ *			upload: {
+ *				panel: {
+ *					items: [
+ *						'insertImageViaUrl',
+ *						'openCKFinder',
+ *						'pluginXButton'
+ *					]
+ *				}
+ *			}
+ *		};
+ *
+ * @member {Array.<String>} module:image/imageupload~ImageUploadPanelConfig#items
+ * @default [ 'insertImageViaUrl' ]
+ */

+ 7 - 0
packages/ckeditor5-image/src/imageupload/ui/imageuploadpanelview.js

@@ -30,6 +30,13 @@ import cancelIcon from '@ckeditor/ckeditor5-core/theme/icons/cancel.svg';
 
 import '../../../theme/imageupload.css';
 
+/**
+ * The insert an image via URL view controller class.
+ *
+ * See {@link module:image/imageupload/ui/imageuploadpanelview~ImageUploadPanelView}.
+ *
+ * @extends module:ui/view~View
+ */
 export default class ImageUploadPanelView extends View {
 	/**
 	 * Creates a view for the dropdown panel of {@link module:image/imageupload/imageuploadui~ImageUploadUI}.