From 8496a2642903ebdda9932e7512155beb194aa37e Mon Sep 17 00:00:00 2001 From: godai78 Date: Fri, 6 Oct 2023 07:59:29 +0200 Subject: [PATCH 1/4] Docs: expanding the image guide. [short flow] --- docs/updating/update-to-40.md | 2 +- .../docs/features/images-overview.md | 16 ++++++++++++---- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/docs/updating/update-to-40.md b/docs/updating/update-to-40.md index d6643270379..c6ff6320198 100644 --- a/docs/updating/update-to-40.md +++ b/docs/updating/update-to-40.md @@ -22,7 +22,7 @@ Listed below are the most important changes that require your attention when upg ### Changes to the image feature -This release introduces changes connected with the image `width` and `height` attributes. These are now preserved while loading editor content. Images without their size specified will automatically gain natural image size on any interaction with the image within the editor. Due to this new behavior, the `width` and `height` attributes are now used to preserve the image's natural width and height and the model attribute name of a resized image is now changed to `resizedWidth`. +This release introduces changes connected with the image `width` and `height` attributes. These are now preserved while loading editor content. Images without their size specified will automatically gain natural image size on any interaction with the image within the editor. Due to this new behavior, the `width` and `height` attributes are now used to preserve the image's natural width and height. The model attribute name of a resized image is now changed to `resizedWidth` and a new `resizeHeight` attribute has been added. The `srcset` model attribute which provides parameters for responsive images, has been simplified. It is no longer an object `{ data: "...", width: "..." }`, but the value that was previously stored in the `data` part. diff --git a/packages/ckeditor5-image/docs/features/images-overview.md b/packages/ckeditor5-image/docs/features/images-overview.md index 3a23b222001..943d2e4e293 100644 --- a/packages/ckeditor5-image/docs/features/images-overview.md +++ b/packages/ckeditor5-image/docs/features/images-overview.md @@ -206,13 +206,21 @@ See the common API of image-related features such as {@link module:image/imagest ## Image `width` and `height` attributes -Starting with v40.0.0, the image's `width` and `height` attributes are retained by the editor when it is loaded. Upon {@link features/image-upload uploading an image file} or {@link features/images-inserting inserting it} into the editor content, the CKEditor 5 image feature fetches these dimensions from the file. It will also happen on any interaction with the image if the content is preloaded. The editor then adds these properties to the markup, just like the {@link features/images-text-alternative text alternative tag}. +Starting with v40.0.0, the image's `width` and `height` attributes are retained by the editor when it is loaded. The attributes are now handled as follows: -However, if the user uses an upload adapter and the server sends back the uploaded image with the `width` or `height` parameters already set, these existing values are not overwritten. +* Upon {@link features/image-upload uploading an image file} or {@link features/images-inserting inserting it} into the editor content, the CKEditor 5 image feature fetches these dimensions from the file. The editor then adds these properties to the markup, just like the {@link features/images-text-alternative text alternative tag}. + * If the user uses an upload adapter and the server sends back the uploaded image with the `width` or `height` parameters already set, these existing values are not overwritten. +* The editor will not change already existing content. It means, loading HTML (i.e., `setData`) with images does not set up these attributes. +* Changes to an image (such as resize, etc.) will trigger the creation of those attributes. These attributes are crucial to proper content handling, and actions on a current image that does not have these improve this image's markup. +* The `aspect-ratio` attribute has been added to the image's properties to handle situations when the file is resized or scaled with a tweaked aspect ratio. -Adding the image's `width` and `height` attributes is done to ensure that the image dimensions ratio is properly kept when it is styled or aligned and that the image always looks like it should, rather than forcing the image size within the content. +These image properties can be further controlled via CSS styles. If you need to crop, resize, rotate, or mirror flip your images, you can use the {@link features/ckbox CKBox asset manager} to achieve that. -These image properties can be further controlled via CSS styles. If you need to crop, resize, or mirror flip your images, you can use the {@link features/ckbox CKBox asset manager} to achieve that. +Adding the image's `width` and `height` attributes is done to ensure that the image dimensions ratio is properly kept when it is styled or aligned and that the image always looks like it should, rather than forcing the image size within the content. This ensures high-quality output. + + + Due to the introduction of this new behavior in CKEditor v40.0.0, the `width` and `height` attributes are now used to preserve the image’s natural width and height. The information about a resized image is stored in the `resizedWidth` and `resizeHeight` attributes. + ## Typing around images From 405c2993b200877cf1b1a278f4bff7b7e9146151 Mon Sep 17 00:00:00 2001 From: godai78 Date: Fri, 6 Oct 2023 08:19:11 +0200 Subject: [PATCH 2/4] Docs: rewording. [short flow] --- packages/ckeditor5-image/docs/features/images-overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/ckeditor5-image/docs/features/images-overview.md b/packages/ckeditor5-image/docs/features/images-overview.md index 943d2e4e293..3d09034379c 100644 --- a/packages/ckeditor5-image/docs/features/images-overview.md +++ b/packages/ckeditor5-image/docs/features/images-overview.md @@ -206,7 +206,9 @@ See the common API of image-related features such as {@link module:image/imagest ## Image `width` and `height` attributes -Starting with v40.0.0, the image's `width` and `height` attributes are retained by the editor when it is loaded. The attributes are now handled as follows: +Starting with v40.0.0, the image's `width` and `height` attributes are retained by the editor when it is loaded. Adding them is done to ensure that the image dimensions ratio is properly kept when an image is styled or aligned and that it always looks like it should, rather than forcing the image size within the content. This ensures high-quality output. + +The attributes are now handled as follows: * Upon {@link features/image-upload uploading an image file} or {@link features/images-inserting inserting it} into the editor content, the CKEditor 5 image feature fetches these dimensions from the file. The editor then adds these properties to the markup, just like the {@link features/images-text-alternative text alternative tag}. * If the user uses an upload adapter and the server sends back the uploaded image with the `width` or `height` parameters already set, these existing values are not overwritten. @@ -216,8 +218,6 @@ Starting with v40.0.0, the image's `width` and `height` attributes are retained These image properties can be further controlled via CSS styles. If you need to crop, resize, rotate, or mirror flip your images, you can use the {@link features/ckbox CKBox asset manager} to achieve that. -Adding the image's `width` and `height` attributes is done to ensure that the image dimensions ratio is properly kept when it is styled or aligned and that the image always looks like it should, rather than forcing the image size within the content. This ensures high-quality output. - Due to the introduction of this new behavior in CKEditor v40.0.0, the `width` and `height` attributes are now used to preserve the image’s natural width and height. The information about a resized image is stored in the `resizedWidth` and `resizeHeight` attributes. From b2dfcece3716345c36a2340eff735b31c2b09f65 Mon Sep 17 00:00:00 2001 From: godai78 Date: Fri, 6 Oct 2023 08:22:34 +0200 Subject: [PATCH 3/4] Docs: typo. [short flow] --- packages/ckeditor5-image/docs/features/images-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/ckeditor5-image/docs/features/images-overview.md b/packages/ckeditor5-image/docs/features/images-overview.md index 3d09034379c..8476af8d179 100644 --- a/packages/ckeditor5-image/docs/features/images-overview.md +++ b/packages/ckeditor5-image/docs/features/images-overview.md @@ -219,7 +219,7 @@ The attributes are now handled as follows: These image properties can be further controlled via CSS styles. If you need to crop, resize, rotate, or mirror flip your images, you can use the {@link features/ckbox CKBox asset manager} to achieve that. - Due to the introduction of this new behavior in CKEditor v40.0.0, the `width` and `height` attributes are now used to preserve the image’s natural width and height. The information about a resized image is stored in the `resizedWidth` and `resizeHeight` attributes. + Due to the introduction of this new behavior in CKEditor 5 v40.0.0, the `width` and `height` attributes are now used to preserve the image’s natural width and height. The information about a resized image is stored in the `resizedWidth` and `resizeHeight` attributes. ## Typing around images From 3cf52f5235f01a930ab2a7ce69b365a5059a92fe Mon Sep 17 00:00:00 2001 From: godai78 Date: Fri, 6 Oct 2023 08:57:17 +0200 Subject: [PATCH 4/4] Docs: portoing changes to the migration guide. [short flow] --- docs/updating/update-to-40.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/docs/updating/update-to-40.md b/docs/updating/update-to-40.md index c6ff6320198..ec723c96ad4 100644 --- a/docs/updating/update-to-40.md +++ b/docs/updating/update-to-40.md @@ -22,10 +22,36 @@ Listed below are the most important changes that require your attention when upg ### Changes to the image feature -This release introduces changes connected with the image `width` and `height` attributes. These are now preserved while loading editor content. Images without their size specified will automatically gain natural image size on any interaction with the image within the editor. Due to this new behavior, the `width` and `height` attributes are now used to preserve the image's natural width and height. The model attribute name of a resized image is now changed to `resizedWidth` and a new `resizeHeight` attribute has been added. +#### Width and height attributes + +This release introduces changes to the {@link features/images-overview image feature} connected with the image `width` and `height` attributes. The changes include: + +* Upon {@link features/image-upload uploading an image file} or {@link features/images-inserting inserting it} into the editor content, the CKEditor 5 image feature fetches these dimensions from the file. The editor then adds these properties to the markup, just like the {@link features/images-text-alternative text alternative tag}. + * The editor **will not change already existing content**. It means, loading HTML (i.e., `setData`) with images does not set up these attributes. + * If the user uses an upload adapter and the server sends back the uploaded image with the `width` or `height` parameters already set, these existing values are not overwritten. +* Changes to an image (such as resize, etc.) will trigger the creation of those attributes. These attributes are crucial to proper content handling, and actions on a current image that does not have these improve this image's markup. +* The `aspect-ratio` attribute has been added to the image's properties to handle situations when the file is resized or scaled with a tweaked aspect ratio. + +#### Changes to the model + +Due to the introduction of this new behavior, the following changes to model attributes have been introduced: + +* The `width` and `height` attributes are now used to preserve the **image’s natural width and height**. +* The information about a **resized image** is stored in the `resizedWidth` attribute (renamed from `width`) and a newly added `resizeHeight` attribute. + +Therefore, the relation between styles and attributes toward model attributes looks as follows: + +* Style `width` → model `resizedWidth` (changed from `width`). +* Style `height` → model `resizedHeight` (new). +* Attribute `width` → model `width` (new). +* Attribute `height` → model `height` (new). + +#### Changes to the `srcset` attribute The `srcset` model attribute which provides parameters for responsive images, has been simplified. It is no longer an object `{ data: "...", width: "..." }`, but the value that was previously stored in the `data` part. +#### Changes to content styles + Last but not least, content styles have been updated with this release, which means you need to update them in your editor implementation to avoid any discrepancies. Please refer to the {@link installation/advanced/content-styles Content styles} guide to learn how to generate the stylesheet. ### Changes to the comments feature