|
|
@@ -46,7 +46,7 @@ You can see the demo of a WYSIWYG editor with the base image feature enabled bel
|
|
|
|
|
|
## Image contextual toolbar
|
|
|
|
|
|
-The {@link module:image/imagetoolbar~ImageToolbar} plugin 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 text alternative (which is introduced by the base image plugin) button and [image styles buttons](#image-styles).
|
|
|
+The {@link module:image/imagetoolbar~ImageToolbar} plugin 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 text alternative button (a feature introduced by the base image plugin) and [image styles buttons](#image-styles).
|
|
|
|
|
|
See a demo of a WYSIWYG editor with the contextual toolbar enabled:
|
|
|
|
|
|
@@ -74,7 +74,7 @@ The {@link module:image/imagecaption~ImageCaption} plugin adds support for image
|
|
|
</figure>
|
|
|
```
|
|
|
|
|
|
-By default, if the image caption is empty, the `<figcaption>` element is not visible to the user. You can click the image to reveal the caption. See the demo below:
|
|
|
+By default, if the image caption is empty, the `<figcaption>` element is not visible to the user. You can click the image to reveal the caption field and write one. See the demo below:
|
|
|
|
|
|
{@snippet features/image-caption}
|
|
|
|
|
|
@@ -84,23 +84,23 @@ See the {@link features/image-upload Image upload} guide.
|
|
|
|
|
|
## Responsive images
|
|
|
|
|
|
-Support for responsive images in CKEditor 5 is brought by the {@link features/easy-image Easy Image} feature without any additional configuration. Learn more how to use the feature in your project in the {@link features/easy-image#responsive-images Easy Image integration} guide.
|
|
|
+The responsive images support 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.
|
|
|
|
|
|
## Image styles
|
|
|
|
|
|
In simple integrations it is enough to let the user insert images, set their text alternative and the editor's job is done. An example of such a simple solution are e.g. [GitHub](https://github.com) comments. The styling of the images (for example, their maximum width and margins) is controlled by GitHub through stylesheets.
|
|
|
|
|
|
-In more advanced scenarios, the user may need to be able to decide whether the image should take the whole width (if it is the article's main photo) or it should take, for example, 50% of the width and be pulled out of the content (so called "pulled images"). Various integration scenarios require different types of images to be used.
|
|
|
+In more advanced scenarios, the user may need to be able to decide the image's width: should it take up the whole width (if it is the article's main photo) or it should take, for example, 50% of the width and be pulled out of the content (so called "pulled images"). Various integration scenarios require different types of images to be used.
|
|
|
|
|
|
-Finally, in certain situations, the user should be able to granularly control how an image is presented so they should be able to set the size and alignment separately.
|
|
|
+Finally, in certain situations, the user should be able to granularly control how an image is presented via the ability to set the size and alignment separately.
|
|
|
|
|
|
-The {@link module:image/imagestyle~ImageStyle} feature solves the last two scenarios. The former is handled by so-called ["semantical styles"](#semantical-styles) and the latter by ["presentational styles"](#presentational-styles) in combination with [image resize](#resizing-images).
|
|
|
+The {@link module:image/imagestyle~ImageStyle} feature solves the last two scenarios. The former is handled by so-called ["semantical styles"](#semantical-styles) and the latter by ["presentational styles"](#presentational-styles) in combination with the [image resize](#resizing-images) feature.
|
|
|
|
|
|
The available image styles can be configured using the {@link module:image/image~ImageConfig#styles `config.image.styles`} option. Respective buttons should also be added to the image toolbar via {@link module:image/image~ImageConfig#toolbar `config.image.toolbar`}.
|
|
|
|
|
|
### Semantical styles
|
|
|
|
|
|
-A semantical style let the user choose from a predefined "types" of images. The user is not able to set the image border, alignment, margins, width, etc. separately. Instead, they can pick one of the styles defined by the developer who prepared the WYSIWYG editor integration. This gives the developer control over how the users style images and makes the user's life easier by setting multiple properties at once.
|
|
|
+A semantical style lets the user choose from predefined "types" of images. The user is not able to set the image border, alignment, margins, width, etc. separately. Instead, they can pick one of the styles defined by the developer who prepared the WYSIWYG editor integration. This gives the developer control over how the users style their images and makes the user's life easier by setting multiple properties at once.
|
|
|
|
|
|
A style is applied to the image in form of a class. By default, CKEditor 5 is configured to support two default semantical styles: **"full width"** (which does not apply any class — it is the default style) and **"side image"** (which applies the `image-style-side` class).
|
|
|
|
|
|
@@ -117,14 +117,14 @@ A side image:
|
|
|
```
|
|
|
|
|
|
<info-box>
|
|
|
- The actual styling of the images is the integrator's job. CKEditor 5 WYSIWYG editor comes with some default styles, but they will only be applied to images inside the editor. The integrator needs to style them appropriately on the target pages.
|
|
|
+ The actual styling of the images is the integrator's job. CKEditor 5 WYSIWYG editor comes with some default styles, but they will only be applied to the images inside the editor. The integrator needs to style them appropriately on the target pages.
|
|
|
|
|
|
You can find the source of the default styles applied by the editor here: [`ckeditor5-image/theme/imagestyle.css`](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-image/theme/imagestyle.css).
|
|
|
|
|
|
Read more about {@link builds/guides/integration/content-styles styling the content of the editor}.
|
|
|
</info-box>
|
|
|
|
|
|
-Below you can see a demo of the WYSIWYG editor with the semantical image styles. The "full" and "side" styles are the default value of {@link module:image/image~ImageConfig#styles `config.image.styles`} so you do not need to set it.
|
|
|
+Here you can see a demo of the WYSIWYG editor with the semantical image styles. The "full" and "side" styles are the default value of {@link module:image/image~ImageConfig#styles `config.image.styles`} so you do not need to set it.
|
|
|
|
|
|
```js
|
|
|
ClassicEditor
|
|
|
@@ -214,19 +214,19 @@ you can also define your own styles or modify the existing ones.
|
|
|
|
|
|
You can find advanced examples in the {@link module:image/image~ImageConfig#styles `config.image.styles`} configuration option documentation.
|
|
|
|
|
|
-<!-- TODO (live example)... -->
|
|
|
+<!-- TODO (live example)... not today, yet -->
|
|
|
|
|
|
## Resizing images
|
|
|
|
|
|
-The [image styles](#image-styles) feature is meant to give the user the choice between a set of styling options provided by the system (so by the developer or administrator who created it). There are also scenarios where the user should be able to freely set the width of an image. And that is where the image resize feature comes to play.
|
|
|
+The [image styles](#image-styles) feature is meant to give the user a choice between a set of styling options provided by the system (i.e. by the developer or administrator who created it). There are also scenarios where the user should be able to freely set the width of an image. And that is where the image resize feature comes into play. It is implemented by the {@link module:image/imageresize~ImageResize} plugin.
|
|
|
|
|
|
-It is implemented by the {@link module:image/imageresize~ImageResize} plugin and enables four "resize handles" displayed over the selected image. The user can freely resize the image by dragging them. The feature can be configured to use either percentage (default) or pixel values.
|
|
|
+### Methods to resize images
|
|
|
|
|
|
-The plugin also gives you an ability to change the size of the image through the image toolbar. You can set an optional static configuration with {@link module:image/image~ImageConfig#resizeOptions} and choose whether you want to use a dropdown or set of the standalone buttons.
|
|
|
+The editor offers different ways to resize images either by using "resize handles" or by using dedicated UI components - either a dropdown menu or standalone buttons.
|
|
|
|
|
|
-### Methods to resize images
|
|
|
+The {@link module:image/imageresize~ImageResize} plugin enables the four resize handles displayed over the selected image. The user can freely resize the image by dragging them. The feature can be configured to use either percentage (default) or pixel values.
|
|
|
|
|
|
-The editor offers different ways to resize images either by using resize handles or by using dedicated UI components.
|
|
|
+The plugin also gives you an ability to change the size of the image through the on-click image toolbar. You can set an optional static configuration with {@link module:image/image~ImageConfig#resizeOptions} and choose whether you want to use a dropdown or a set of standalone buttons.
|
|
|
|
|
|
#### Using handles
|
|
|
|
|
|
@@ -234,9 +234,9 @@ In this case, the user is able to resize images via dragging square handles disp
|
|
|
|
|
|
{@snippet features/image-resize}
|
|
|
|
|
|
-You can configure the editor for resizing images by handles in two different ways:
|
|
|
+You can configure resizing images by handles in two different ways in the CKEditor5 WYSIWYG editor:
|
|
|
|
|
|
-- By installing the {@link module:image/imageresize~ImageResize} plugin, which contains **all** needed features (`ImageResizeEditing`, `ImageResizeHandles`, `ImageResizeButtons`).
|
|
|
+- Either by installing the {@link module:image/imageresize~ImageResize} plugin, which contains **all** needed features (`ImageResizeEditing`, `ImageResizeHandles`, `ImageResizeButtons`).
|
|
|
|
|
|
```js
|
|
|
import Image from '@ckeditor/ckeditor5-image/src/image';
|
|
|
@@ -271,7 +271,7 @@ Both ways enable resize handles by default.
|
|
|
|
|
|
#### Using the dropdown
|
|
|
|
|
|
-In this case, the user is able to choose from a set of predefined options. These options can be displayed in the image toolbar in form of a dropdown.
|
|
|
+In this case, the user is able to choose from a set of predefined options. These options can be displayed in the image toolbar in form of a dropdown displayed in the pop-up menu after the user clicks the image.
|
|
|
|
|
|
To use this option, you need to [enable image resizing](#enabling-image-resizing) and configure the available {@link module:image/image~ImageConfig#resizeOptions resize options}.
|
|
|
|
|
|
@@ -302,9 +302,9 @@ const imageConfiguration = {
|
|
|
|
|
|
#### Using standalone buttons
|
|
|
|
|
|
-In this case, the resize options are displayed in form of separate buttons. The benefit of this solution is the smoothest UX as the user needs just one click to resize an image.
|
|
|
+In this case, the resize options are displayed in the form of separate buttons. The benefit of this solution is the smoothest UX as the user needs just one click to resize an image.
|
|
|
|
|
|
-To use this option, you need to [enabling image resizing](#enabling-image-resizing) and configure the available {@link module:image/image~ImageConfig#resizeOptions resize options}.
|
|
|
+To use this option, you need to [enable image resizing](#enabling-image-resizing) and configure the available {@link module:image/image~ImageConfig#resizeOptions resize options}.
|
|
|
|
|
|
```js
|
|
|
const imageConfiguration = {
|
|
|
@@ -338,7 +338,7 @@ const imageConfiguration = {
|
|
|
|
|
|
### Disabling image resize handles
|
|
|
|
|
|
-If, for some reason, you want to configure the editor in such a way that images can be resized only by buttons you can do so by omitting the {@link module:image/imageresize/imageresizehandles~ImageResizeHandles `ImageResizeHandles`} plugin. As a result, plugins setup should look like this: `plugins: [ 'ImageResizeEditing', 'ImageResizeButtons', ... ]` as opposed to `plugins: [ 'ImageResize', ... ]`. It will enable resizing image feature only by means of the chosen UI ([dropdown](#using-the-dropdown) or [standalone buttons](#using-standalone-buttons)) in the image toolbar.
|
|
|
+If, for some reason, you want to configure the editor in such a way that images can be resized only by buttons you can do so by omitting the {@link module:image/imageresize/imageresizehandles~ImageResizeHandles `ImageResizeHandles`} plugin. As a result, plugins setup should look like this: `plugins: [ 'ImageResizeEditing', 'ImageResizeButtons', ... ]` as opposed to `plugins: [ 'ImageResize', ... ]`. It will enable resizing image feature only by means of the chosen UI (either a [dropdown](#using-the-dropdown) or [standalone buttons](#using-standalone-buttons)) in the image toolbar.
|
|
|
|
|
|
```js
|
|
|
import Image from '@ckeditor/ckeditor5-image/src/image';
|
|
|
@@ -430,7 +430,7 @@ Another concern when styling resized images is that by default, CKEditor 5 uses
|
|
|
|
|
|
### Using pixels instead of percentage width
|
|
|
|
|
|
-Using percentage widths ensures that content stays responsive when displayed in different places than in the WYSIWYG editor. If the user made an image take 60% of the content's width in the editor, if you ever change the width of the target page (where this content is displayed), the image will still take 60% of that space. The same is true if the page is responsive and adjusts to the viewport's width.
|
|
|
+Using percentage widths ensures that content stays responsive when displayed in places other than the WYSIWYG editor. If the user made an image take 60% of the content's width in the editor, if you ever change the width of the target page (where this content is displayed), the image will still take 60% of that space. The same is true if the page is responsive and adjusts to the viewport's width.
|
|
|
|
|
|
If you configured the editor to use pixel values, the image could take, for example, too much space after you introduced a new layout for your website.
|
|
|
|
|
|
@@ -457,6 +457,8 @@ The {@link module:link/linkimage~LinkImage} plugin adds support for linking imag
|
|
|
* Using images as thumbnails linking to an article or product page.
|
|
|
* Creating banners linking to other pages.
|
|
|
|
|
|
+The image link can be added or edited via the image menu. An icon in top right corner of the image indicates the presence of a link.
|
|
|
+
|
|
|
```html
|
|
|
<figure class="image">
|
|
|
<a href="...">
|
|
|
@@ -484,7 +486,7 @@ To add image features to your rich-text editor, install the [`@ckeditor/ckeditor
|
|
|
npm install --save @ckeditor/ckeditor5-image @ckeditor/ckeditor5-link
|
|
|
```
|
|
|
|
|
|
-And add the plugins that you need to your plugin list. You also need to set the image toolbar items.
|
|
|
+Next add the plugins that you need to your plugin list. You also need to set the desired image toolbar items.
|
|
|
|
|
|
```js
|
|
|
import Image from '@ckeditor/ckeditor5-image/src/image';
|