DOC-2581: Added improvements to srcset, svg file name changes, general copy edits.

kemister85 · kemister85 · commit c958f5f15b8e · 2024-12-05T15:57:33.000+10:00
diff --git a/modules/ROOT/images/icons/revert.svg b/modules/ROOT/images/icons/revert.svg
diff --git a/modules/ROOT/pages/uploadcare.adoc b/modules/ROOT/pages/uploadcare.adoc
@@ -83,14 +83,14 @@ Below is an overview of the features of the {pluginname} plugin includes for ima
 | Allows users to apply transformations to the image:
 
 |
-| Rotate Counterclockwise
+| Rotate Left
 | image:icons/rotate-left.svg[rotate-left.svg]
-| Rotates the image counterclockwise.
+| Rotates the image counterclockwise (left).
 
 |
-| Rotate Clockwise
+| Rotate Right
 | image:icons/rotate-right.svg[rotate-right.svg]
-| Rotates the image clockwise.
+| Rotates the image clockwise (right).
 
 |
 | Flip Vertically
@@ -177,9 +177,9 @@ Below is an overview of the features of the {pluginname} plugin includes for ima
 | image:icons/blur.svg[blur.svg]
 | Blurs the image.
 
-| Revert Changes
+| Revert
 |
-| image:icons/revert-changes.svg[revert-changes.svg]
+| image:icons/revert.svg[revert.svg]
 | Restores the image to its original state by undoing all edits.
 |===
 
diff --git a/modules/ROOT/partials/configuration/icon_list.adoc b/modules/ROOT/partials/configuration/icon_list.adoc
@@ -157,7 +157,7 @@
 | `+resize-handle+` | image:icons/resize-handle.svg[resize-handle.svg] | `+resize-handle.svg+`
 | `+resize+` | image:icons/resize.svg[resize.svg] | `+resize.svg+`
 | `+restore-draft+` | image:icons/restore-draft.svg[restore-draft.svg] | `+restore-draft.svg+`
-| `+revert-changes+` | image:icons/revert-changes.svg[revert-changes.svg] | `+revert-changes.svg+`
+| `+revert+` | image:icons/revert.svg[revert.svg] | `+revert.svg+`
 | `+revision-history+` | image:icons/revision-history.svg[revision-history.svg] | `+revision-history.svg+`
 | `+rotate-left+` | image:icons/rotate-left.svg[rotate-left.svg] | `+rotate-left.svg+`
 | `+rotate-right+` | image:icons/rotate-right.svg[rotate-right.svg] | `+rotate-right.svg+`
diff --git a/modules/ROOT/partials/configuration/uploadcare_signed_upload_auth_provider.adoc b/modules/ROOT/partials/configuration/uploadcare_signed_upload_auth_provider.adoc
@@ -1,9 +1,9 @@
 [[uploadcare-signed-upload-auth-provider]]
 == `uploadcare_signed_upload_auth_provider`
 
-Specifies a function used to generate secure signatures for authenticated requests to Uploadcare. This is necessary when using secure Uploadcare features, such as signed uploads. The function should return a `Promise` that resolves with an object containing the signature and expiration timestamp.
+Specifies a function used to generate secure signatures for authenticated requests to Uploadcare. This function is required when enabling Uploadcare's signed uploads feature, which ensures that only authorized users can upload files using your `uploadcare_public_key`. The function should return a `Promise` that resolves with an object containing the signature and expiration timestamp.
 
-Use this option if you want to ensure secure uploads or restrict file access using Uploadcare's signed uploads feature.
+Use this option to enforce secure uploads, preventing unauthorized users from uploading files via your application.
 
 *Type:* `+Function+`
 
@@ -25,12 +25,13 @@ tinymce.init({
 
 [IMPORTANT]
 ====
-{companyname} recommends configuring the `uploadcare_signed_upload_auth_provider` option to enable signed uploads and enhance security when integrating with Uploadcare. This option is essential for applications requiring:
+{companyname} recommends configuring the `uploadcare_signed_upload_auth_provider` option to secure uploads and prevent misuse of your Uploadcare `uploadcare_public_key`. This option is essential for applications requiring:
 
-* Secure file uploads by preventing unauthorized access.
-* Restriction of file access to specific users or sessions.
+* Prevention of unauthorized file uploads via your `uploadcare_public_key`.
+* Enforcement of secure upload practices for application integrity.
 
-The `uploadcare_signed_upload_auth_provider` ensures that every request is authenticated with a generated signature and expiration timestamp, providing an additional layer of security for sensitive data.
+[NOTE]
+This option **only** secures unauthorized access to upload files to the uploadcare storage by verifying signatures during uploads.
 
-Using this option will help safeguard your application by ensuring secure file uploads, protecting sensitive data, and maintaining system integrity. {companyname} strongly advises including this configuration as a fundamental part of your Uploadcare integration setup.
-====
+For most integrations, enabling signed uploads by configuring this option ensures that only authorized uploads occur, reducing the risk of abuse and maintaining secure usage of your `uploadcare_public_key`.
+====
diff --git a/modules/ROOT/partials/configuration/uploadcare_srcset_steps.adoc b/modules/ROOT/partials/configuration/uploadcare_srcset_steps.adoc
@@ -1,23 +1,48 @@
 [[uploadcare-srcset-steps]]
 == `uploadcare_srcset_steps`
 
-Defines an array of numeric values representing the widths for responsive images. These widths are used to generate the `srcset` attribute for images, allowing browsers to select the most appropriate resolution based on the device's display and network conditions.
+Specifies an array of numeric values representing the widths used to generate the `srcset` attribute for responsive images. This enables browsers to select the most suitable resolution based on the device’s display and network conditions.
 
-Customize this array to include only the widths you need for your application. For example, you can reduce the number of resolutions for faster processing or add specific sizes required for your layout.
+Customize this array to include **only** the widths required for your application. Reducing the number of resolutions can improve processing speed, while adding specific sizes can accommodate unique layout needs.
 
 *Type:* `+Array+`
 
 *Default:* `+[100, 200, 300, 500, 750, 1000, 1250, 1500, 2000, 2500, 3000]+`
 
+=== Example: Generated `srcset` Attribute with Custom Widths
+
+When an image is uploaded, its original width is used to create a `srcset` attribute with downscaled images for the defined widths. For instance, if the image width is 780 pixels and `uploadcare_srcset_steps` is set to `[100, 200, 300, 500, 750]`, the resulting `srcset` will look like this:
+
+.Example: Responsive 780px Image with Custom Widths in `srcset`
+[source,html]
+----
+<img 
+  style="width: min(780px, 100%); aspect-ratio: 780 / 780;" 
+  src="https://ucarecdn.com/de937e77-2fec-4781-91c1-55dae67803cd/-/preview/" 
+  sizes="(min-width: 780px) 780px, 100vw" 
+  srcset="
+      https://ucarecdn.com/de937e77-2fec-4781-91c1-55dae67803cd/-/resize/100x/ 100w,
+      https://ucarecdn.com/de937e77-2fec-4781-91c1-55dae67803cd/-/resize/200x/ 200w,
+      https://ucarecdn.com/de937e77-2fec-4781-91c1-55dae67803cd/-/resize/300x/ 300w,
+      https://ucarecdn.com/de937e77-2fec-4781-91c1-55dae67803cd/-/resize/500x/ 500w,
+      https://ucarecdn.com/de937e77-2fec-4781-91c1-55dae67803cd/-/resize/750x/ 750w,
+      https://ucarecdn.com/de937e77-2fec-4781-91c1-55dae67803cd/-/preview/ 780w
+  ">
+----
+
+This ensures the browser selects the optimal image size based on the viewport and device characteristics, enhancing performance and user experience. On devices with narrower viewports, smaller images (e.g., 100w or 200w) will be prioritized, reducing bandwidth usage.
+
 === Example: Customizing `uploadcare_srcset_steps`
 
+To customize the array, update the configuration as shown below:
+
 [source,js]
 ----
 tinymce.init({
   selector: 'textarea',
   plugins: 'uploadcare',
   toolbar: 'uploadcare',
   uploadcare_public_key: '<your-public-key>',
-  uploadcare_srcset_steps: [100, 200, 300, 500],
+  uploadcare_srcset_steps: [100, 200, 300, 500, 750],
 });
-----
+----
diff --git a/modules/ROOT/partials/menu-item-ids/uploadcare-menu-items.adoc b/modules/ROOT/partials/menu-item-ids/uploadcare-menu-items.adoc
@@ -1,5 +1,5 @@
 [cols="1,3",options="header"]
 |===
 |Identifier |Description
-| `+uploadcare+` | Inserts a `<p>` tag with the `+contenteditable="false"+` attribute, containing a placeholder image. This placeholder supports image uploads via drag-and-drop, file selection, or by providing a URL.
+| `+uploadcare+` | Inserts a image placeholder element. This placeholder supports image uploads via drag-and-drop, file selection, or by providing a URL.
 |===
diff --git a/modules/ROOT/partials/toolbar-button-ids/uploadcare-toolbar-buttons.adoc b/modules/ROOT/partials/toolbar-button-ids/uploadcare-toolbar-buttons.adoc
@@ -1,5 +1,5 @@
 [cols="1,3",options="header"]
 |===
 |Identifier |Description
-| `+uploadcare+` | Inserts a `<p>` tag with the `+contenteditable="false"+` attribute, containing a placeholder image. This placeholder supports image uploads via drag-and-drop, file selection, or by providing a URL.
+| `+uploadcare+` | Inserts a image placeholder element. This placeholder supports image uploads via drag-and-drop, file selection, or by providing a URL.
 |===
