Merge pull request #15409 from ckeditor/ck/15304-insertImage-docs

Docs: documenting insertImage changes. Closes #15304

docs/features/image-upload.md

@@ -18,7 +18,7 @@ Inserting {@link features/images-overview images} into content created with CKEd
 
 ## Demo
 
-This demo is configured to use {@link features/ckbox CKBox} for image upload and management. Use the image upload button {@icon @ckeditor/ckeditor5-core/theme/icons/image.svg Image} to upload images or the CKBox button {@icon @ckeditor/ckeditor5-ckbox/theme/icons/browse-files.svg Open file manager} to browse and select existing images from the file manager. It also includes the `AutoImage` plugin, which lets you {@link features/images-inserting#inserting-images-via-pasting-a-url-into-the-editor paste image URLs directly}.
+This demo is configured to use {@link features/ckbox CKBox} for image upload and management. Use the image upload button {@icon @ckeditor/ckeditor5-core/theme/icons/image-upload.svg Image} to upload images or the CKBox button {@icon @ckeditor/ckeditor5-ckbox/theme/icons/browse-files.svg Open file manager} to browse and select existing images from the file manager. It also includes the `AutoImage` plugin, which lets you {@link features/images-inserting#inserting-images-via-pasting-a-url-into-the-editor paste image URLs directly}.
 
 {@snippet features/image-upload}
 

docs/features/index.md

@@ -37,7 +37,7 @@ Most of these formatting options can be applied from the {@link features/toolbar
 
 ### Advanced content editing
 
-Rich text would not be rich without images. You can upload them, caption them, style them, you can even paste them straight from the URL with the help of the {@link features/images-overview image feature} {@icon @ckeditor/ckeditor5-core/theme/icons/image.svg Image} and create a responsive design. If that is not enough, {@link features/media-embed embed media} {@icon @ckeditor/ckeditor5-media-embed/theme/icons/media.svg Media} into your content.
+Rich text would not be rich without images. You can upload them, caption them, style them, you can even paste them straight from the URL with the help of the {@link features/images-overview image feature} {@icon @ckeditor/ckeditor5-core/theme/icons/image-upload.svg Image} and create a responsive design. If that is not enough, {@link features/media-embed embed media} {@icon @ckeditor/ckeditor5-media-embed/theme/icons/media.svg Media} into your content.
 
 An essential feature for online content are {@link features/link links} {@icon @ckeditor/ckeditor5-link/theme/icons/link.svg Link} - these can be easily pasted, changed and attributed.
 

packages/ckeditor5-ckbox/docs/features/ckbox.md

@@ -178,7 +178,7 @@ Please keep in mind that if you define your own upload category mappings for a p
 
 The [CKBox workspaces](https://ckeditor.com/docs/ckbox/latest/features/file-management/workspaces.html) provide a convenient solution for achieving data isolation and user separation within CKBox. With workspaces, you can easily create separate storage and data spaces, giving you precise control over assigning specific users, user groups, or tenants to each workspace.
 
-If the user is assigned to more than one workspace, by default all the files uploaded directly from CKEditor are located in the first workspace in the list of workspaces allowed in the user's JWT token. This corresponds to uploads through drag and drop into the editor area, pasting images from the clipboard, or images uploaded using the Image {@icon @ckeditor/ckeditor5-core/theme/icons/image.svg Image} feature. If you would like to define a specific workspace for files uploaded this way, you can define its ID in the `defaultUploadWorkspaceId` option. After that, all the files uploaded directly from CKEditor will be placed in the specified workspace.
+If the user is assigned to more than one workspace, by default all the files uploaded directly from CKEditor are located in the first workspace in the list of workspaces allowed in the user's JWT token. This corresponds to uploads through drag and drop into the editor area, pasting images from the clipboard, or images uploaded using the Image {@icon @ckeditor/ckeditor5-core/theme/icons/image-upload.svg Image} feature. If you would like to define a specific workspace for files uploaded this way, you can define its ID in the `defaultUploadWorkspaceId` option. After that, all the files uploaded directly from CKEditor will be placed in the specified workspace.
 
 ```js
 import { CKBox } from '@ckeditor/ckeditor5-ckbox';

packages/ckeditor5-ckfinder/docs/features/ckfinder.md

@@ -28,7 +28,7 @@ The CKFinder feature lets you insert images and links to files into your content
 This demo shows the integration where the file manager's server connector handles [image upload](#configuring-the-image-upload-only) only:
 
 * Paste an image directly into the editor, and it will be automatically uploaded using the server-side connector.
-* Use the insert image button {@icon @ckeditor/ckeditor5-core/theme/icons/image.svg Image} in the toolbar to insert an image.
+* Use the insert image button {@icon @ckeditor/ckeditor5-core/theme/icons/image-upload.svg Image} in the toolbar to insert an image.
 
 {@snippet features/ckfinder-upload-only}
 

packages/ckeditor5-image/docs/features/images-inserting.md

@@ -15,7 +15,7 @@ You can insert images by uploading them directly from your disk, but you can als
 
 ### Demo
 
-To upload an image, use the image toolbar button {@icon @ckeditor/ckeditor5-core/theme/icons/image.svg Image}. If you want to add an image through a URL, click the arrow next to the image button and paste the URL in the dropdown panel. To update an existing image, select it and paste a new URL in the dropdown panel.
+To upload an image, use the image toolbar button {@icon @ckeditor/ckeditor5-core/theme/icons/image-upload.svg Image}. If you want to add an image through a URL, click the arrow next to the image button and paste the URL in the dropdown panel. To update an existing image, select it and paste a new URL in the dropdown panel.
 
 {@snippet features/image-insert-via-url}
 
@@ -76,7 +76,7 @@ If the automatic embedding was unexpected, for instance when the link was meant
 
 The {@link module:image/image~Image} plugin registers:
 
-* The {@link module:image/image/insertimagecommand~InsertImageCommand `'insertImage'` command} that accepts a source (e.g. a URL) of an image to insert.
+* The {@link module:image/image/insertimagecommand~InsertImageCommand `'insertImage'` command} that accepts a source (for example a URL) of an image to insert.
 
 The {@link module:image/imageupload~ImageUpload} plugin registers:
 

packages/ckeditor5-image/docs/features/images-installation.md

@@ -17,7 +17,7 @@ npm install --save @ckeditor/ckeditor5-image
 	You may want to install the [`@ckeditor/ckeditor5-link`](https://www.npmjs.com/package/@ckeditor/ckeditor5-link) package if you want to use the {@link features/images-linking `LinkImage`} plugin in your editor.
 </info-box>
 
-Next, add the {@link features/images-overview#image-features plugins that you need} to your plugin list. You also need to set the desired image toolbar items. Notice the {@link features/toolbar#separating-toolbar-items separators} used to organize the toolbar.
+Next, add the {@link features/images-overview#image-features plugins that you need} to your plugin list and to the editor toolbar.
 
 ```js
 import { Image, ImageCaption, ImageResize, ImageStyle, ImageToolbar } from '@ckeditor/ckeditor5-image';
@@ -26,6 +26,69 @@ import { LinkImage } from '@ckeditor/ckeditor5-link';
 ClassicEditor
 	.create( document.querySelector( '#editor' ), {
 		plugins: [ Image, ImageToolbar, ImageCaption, ImageStyle, ImageResize, LinkImage ],
+		toolbar: [ 'insertImage', /* ... */ ],
+	} )
+	.then( /* ... */ )
+	.catch( /* ... */ );
+```
+
+## Configuring the toolbar dropdown
+
+The Image feature comes with the unified image insert dropdown component. It automatically collects installed image insert methods. For example, if you install the `ImageUpload` plugin, the corresponding button will automatically appear in the dropdown. You only need to add a button to the toolbar:
+
+```js
+import { Image } from '@ckeditor/ckeditor5-image';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Image ],
+		toolbar: [ 'insertImage', /* ... */ ]
+	} )
+	.then( /* ... */ )
+	.catch( /* ... */ );
+```
+
+The feature is pre-configured to include the following image insertion methods:
+
+* `upload` - Upload image from computer. It uses the configured image upload adapter.
+* `assetManager` - Opens the installed asset manager (for example the CKBox).
+* `url` - Allows inserting an image by directly specifying its URL. Integration provided by `ImageInsertViaUrl` feature.
+
+Note that the insert methods mentioned above will only be added if you install dedicated features. However, not all features are required.
+
+If you need to limit the methods included in the dropdown (apart from not installing a specific feature) or change their order you can use the `image.insert.integration` configuration option:
+
+```js
+import { Image } from '@ckeditor/ckeditor5-image';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Image ],
+		toolbar: [ 'insertImage', /* ... */ ],
+		image: {
+			insert: {
+				// This is the default configuration, you do not need to provide 
+				// this configuration key if the list content and order reflects your needs. 
+				integrations: [ 'upload', 'assetManager', 'url' ]
+			}
+		}
+	} )
+	.then( /* ... */ )
+	.catch( /* ... */ );
+```
+
+## Configuring the contextual image toolbar
+
+You also need to configure the desired contextual image toolbar items. Notice the {@link features/toolbar#separating-toolbar-items separators} used to organize the toolbar.
+
+```js
+import { Image, ImageCaption, ImageResize, ImageStyle, ImageToolbar } from '@ckeditor/ckeditor5-image';
+import { LinkImage } from '@ckeditor/ckeditor5-link';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ Image, ImageToolbar, ImageCaption, ImageStyle, ImageResize, LinkImage ],
+		toolbar: [ 'insertImage', /* ... */ ],
 		image: {
 			toolbar: [
 				'imageStyle:block',
@@ -111,7 +174,7 @@ The `type` setting accepts the following three values:
 
 If the `type` setting is omitted from the configuration, the behavior defaults to inserting images as a block.
 
-**Important**: If only one type of image plugin is enabled (e.g., `ImageInline` is enabled but `ImageBlock` is not), the `image.insert.type` configuration will be effectively ignored and the supported image type will be used.
+**Important**: If only one type of image plugin is enabled (for example, `ImageInline` is enabled but `ImageBlock` is not), the `image.insert.type` configuration will be effectively ignored and the supported image type will be used.
 
 ## Contribute
 

packages/ckeditor5-image/docs/features/images-overview.md

@@ -185,6 +185,14 @@ The availability of these plugins varies in different {@link installation/gettin
 	You can add more image features to your editor using the [online builder](https://ckeditor.com/ckeditor-5/online-builder/) or {@link features/images-installation manually by customizing your editor build}.
 </info-box>
 
+## Image insert dropdown
+
+The toolbar button for the image feature is configurable and provides access to selected methods of inserting images into content, such as {@link features/image-upload uploading images from your computer}, adding images from {@link features/using-file-managers file managers} or {@link features/images-inserting inserting images via URL}.
+
+{@img assets/img/image_insert_dropdown.png 772 Image insert dropdown in the main editor toolbar.}
+
+You can learn more about the toolbar dropdown configuration in the {@link features/images-installation#configuring-the-toolbar-dropdown installation guide}.
+
 ## Image contextual toolbar
 
 The {@link module:image/imagetoolbar~ImageToolbar} plugin available in all editor builds introduces a contextual toolbar for images. The toolbar appears when an image is selected and can be configured to contain any buttons you want. Usually, these will be image-related options such as the {@link features/images-text-alternative text alternative} button, the {@link features/images-captions image caption} button, and {@link features/images-styles image styles} buttons. The toolbar can also host the image editing button introduced by the {@link features/ckbox CKBox asset manager}. Shown below is an example contextual toolbar with an extended set of buttons.