Merge branch '6-dev' into undo-static-path-config

Author: stevepiercy

docs/classic-ui/images.md

@@ -25,7 +25,8 @@ We will use the image object as context in the following examples.
 
 ## Default scales
 
-In `/@@imaging-controlpanel` Plone allows you to configure which scales are available and what dimensions they should have. By default we have the following scales configured:
+In `/@@imaging-controlpanel` Plone allows you to configure which scales are available and what dimensions they should have.
+By default, we have the following scales configured:
 
 * huge 1600:65536
 * great 1200:65536
@@ -176,9 +177,9 @@ scale_util = api.content.get_view("images", context, request)
 tag = scale_util.scale("image", width=600, height=200)
 ```
 
-(classic-ui-images-using-image_scale0-in-templates-label)=
+(classic-ui-images-using-image_scale-in-templates-label)=
 
-### Using image_scale in templates
+### Using `image_scale` in templates
 
 You could use the URL-variant from above, but that would be an uncached version.
 To create a cached scale in a page template you can do the following:
@@ -212,9 +213,10 @@ You can also provide the following keyword arguments to set `title`, `alt`, or `
 
 (classic-ui-images-get-image_scale-by-cached-uid-name-label)=
 
-### Get image_scale by cached UID name
+### Get `image_scale` by cached UID name
 
-If you only have the cached image name from an URL and need to get the image scale, unfortunately you can't use restrictedTraverse(), as this will not be able to resolve the scale. But you can use this workaround, by calling the `publishTraverse` method in `ImageScaling` directly:
+If you only have the cached image name from an URL and need to get the image scale, unfortunately you can't use `restrictedTraverse()`, as this will not be able to resolve the scale.
+But you can use this workaround, by calling the `publishTraverse` method in `ImageScaling` directly:
 
 ```python
 import re
@@ -255,81 +257,206 @@ The `ImageScaling` view explicitly checks the permissions of the current user.
 To access image scales, which are normally not accessible to the current user, override the `validate_access` method in `plone.namedfile.scaling.ImageScale`.
 
 
-## `srcset` configuration
+(classic-ui-images-responsive-image-support)=
 
-In `/@@imaging-controlpanel` Plone allows you to define HTML {term}`srcset` attributes.
-A `srcset` can help the browser serve the best fitting image for the current users situation.
-Which image scale is best for the user can be decided on different metrics.
+## Responsive image support
 
+Plone supports the generation of picture tags with `srcset`s for image optimization.
+Additionally, you can define [media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries/Using_media_queries) for [art direction](classic-ui-images-responsive-image-support-art-direction) and further optimization.
 
-### viewport size
+The configuration allows you to define different picture variants, such as `Large`, `Medium`, or `Small`.
+Users can choose from them in editors, such as TinyMCE, and developers can use them in templates.
 
-The first is metric would be the viewport size.
+
+(classic-ui-images-responsive-image-support-picture-variants)=
+
+### Picture variants
+
+In `/@@imaging-controlpanel` Plone allows you to define picture variants with a list of available image scales.
+These are used for HTML {term}`srcset` attributes.
+A `srcset` attribute can help the browser to serve the best fitting image size for the current user's display.
+
+
+(classic-ui-images-responsive-image-support-default-configuration-label)=
+
+### Default configuration
+
+The default configuration covers image size optimization, and will provide the browser with the needed information to load the optimal image size.
 
 ```json
 {
-  "scale": "large",
-  "media": "(max-width:800px)"
-},
+    "large": {
+        "title": "Large",
+        "sourceset": [
+            "scale": "larger",
+            "additionalScales": ["preview", "teaser", "large", "great", "huge"],
+        ],
+    },
+    "medium": {
+        "title": "Medium",
+        "sourceset": [
+            "scale": "teaser",
+            "additionalScales": ["preview", "large", "larger", "great"],
+        ],
+    },
+    "small": {
+        "title": "Small",
+        "sourceset": [
+            "scale": "preview",
+            "additionalScales": ["large", "larger"],
+        ],
+    },
+}
+```
+
+### Optional settings
+
+The `sourceset` property is an array and can have more than one entry.
+If we have the following two entries, the `image_srcset` output filter will generate one `source` tag for each entry and an additional `img` tag from the last entry.
+
+```json
 {
-  "scale": "larger"
+    "medium": {
+        "title": "Large",
+        "sourceset": [
+            {
+              "scale": "mobile_crop",
+              "media": "(max-width: 768px)",
+              "additionalScales": ["mobile_crop_highres"],
+            },
+            {
+             "scale": "teaser",
+              "media": "(min-width: 769px)",
+              "additionalScales": ["large", "larger", "great", "huge"],
+            }
+        ],
+    },
 }
 ```
 
-With this definition the browser will use the `large` scale when the viewport's width is 800 pixels or fewer.
-When the viewport width is greater than 800 pixels, the browser will use the larger scale `1000px`.
 
+(classic-ui-images-responsive-image-support-filtering-scales)=
 
-### Pixel density
+#### Filtering scales
 
-Another metric is the pixel density of the user's screen.
-This metric denotes the pixel density, or resolution, of an output device in {term}`dots per inch` (DPI).
+By default, for every `srcset`, all available scales will be included in the `srcset`.
 
 ```json
 {
-  "scale": "huge",
-  "media": "(min-resolution: 192dpi), (-webkit-min-device-pixel-ratio: 2)"
-},
-{
-  "scale": "large"
+    "large": {
+        "title": "Large",
+        "sourceset": [
+            {"scale": "larger"},
+        ],
+    },
 }
 ```
 
-With this definition the browser will use the `huge` scale of 1600 pixels when the screen has a density of 192 DPI, also knows as `2x`.
-We use here two different media queries to also support older Safari versions.
-Mobile devices with Safari-like iPhones only support the old non-standard media query.
-If you do not care about IE support, you can use `min-resolution: 2dppx`, which is closer to `2x`.
-The most common variants are:
+To restrict the list of used scales inside a `srcset`, you can set the `additionalScales` parameter with an array of allowed scales.
+Without this parameter, all scales which are not globally excluded scales will be used.
+
+```json
+    "small": {
+        "title": "Small",
+        "sourceset": [
+            {
+              "scale": "preview",
+              "additionalScales": ["large", "larger", "great", "huge"],
+            },
+        ],
+    },
+```
+
+This means the generated `srcset` will contain the scales from `preview` up to `huge`, but not `mini`, for example.
 
-- `1x`: 96 DPI
-- `1.25x`: 120 DPI
-- `1.5x`: 144 DPI
-- `2x`: 192 DPI
-- `3x`: 288 DPI
 
+(classic-ui-images-responsive-image-support-picture-variant-in-editor)=
 
-### Combining viewport size and pixel density
+#### Hiding a picture variant in editors
 
-It is also possible to combine the two metrics.
+It is possible to hide a picture variant in editors.
+This is useful when you want to define a picture variant to be used in templates only.
+
+```json
+    "leadimage": {
+        "title": "Lead image",
+        "sourceset": [
+            {
+              "scale": "preview",
+              "additionalScales": ["large", "larger"],
+              "hideInEditor": true,
+            },
+        ],
+    },
+```
+
+
+(classic-ui-images-responsive-image-support-art-direction)=
+
+### Art direction
+
+With image size optimization, the browser is able to choose the optimal image for each display size.
+But we have no control over which scale the browser will actually use.
+For example to force the browser to use a zoomed version of an image for smaller screens, we can use media queries.
+The technique is called [art direction](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images#art_direction).
+
+Let's have a look at a more advanced configuration:
 
 ```json
 {
-  "scale": "great",
-  "media": "(max-width:799px) and (min-resolution: 144dpi), (max-width:799px) and (-webkit-min-device-pixel-ratio: 1.5)"
-},
-{
-  "scale": "large",
-  "media": "(max-width:799px)"
-},
-{
-  "scale": "huge",
-  "media": "(min-width:800px) and (min-resolution: 144dpi), (max-width:800px) and (-webkit-min-device-pixel-ratio: 1.5)"
-},
-{
-  "scale": "larger",
-  "media": "(min-width:800px)"
-},
-{
-  "scale": "huge"
+    "large": {
+        "title": "Large",
+        "sourceset": [
+            {"scale": "larger"},
+        ],
+    },
+    "medium": {
+        "title": "Medium",
+        "sourceset": [
+            {
+              "scale": "mobile_crop",
+              "media": "(max-width: 768px)",
+              "additionalScales": ["mobile_crop_highres"],
+            },
+            {
+             "scale": "teaser",
+              "media": "(min-width: 769px)",
+              "additionalScales": ["large", "larger", "great", "huge"],
+            }
+        ],
+    },
+    "small": {
+        "title": "Small",
+        "sourceset": [
+            {"scale": "preview"},
+        ],
+    },
 }
+
+```
+
+This will result in a `srcset` as in the following example for a medium image:
+
+```html
+<picture>
+  <source media="(max-width: 677px)"
+          srcset="resolveuid/45fed06defa54d15b37c5b1dc882710c/@@images/image/mobile_crop 800w,
+                  resolveuid/45fed06defa54d15b37c5b1dc882710c/@@images/image/mobile_crop_highres 1600w">
+  <source media="(min-width: 678px)"
+          srcset="resolveuid/45fed06defa54d15b37c5b1dc882710c/@@images/image/teaser 600w,
+                  resolveuid/45fed06defa54d15b37c5b1dc882710c/@@images/image/large 800w,
+                  resolveuid/45fed06defa54d15b37c5b1dc882710c/@@images/image/larger 1000w,
+                  resolveuid/45fed06defa54d15b37c5b1dc882710c/@@images/image/great 1200w">
+  <img alt="Alternative text"
+       class="image-richtext image-size-medium"
+       loading="lazy"
+       src="resolveuid/45fed06defa54d15b37c5b1dc882710c/@@images/image/teaser"
+       width="600"
+       height="400">
+</picture>
+```
+
+```{note}
+Please note that this example has the `resolve_uid_and_caption` filter disabled to see the scale names better.
+The real `src` URLs look more like `http://localhost:8080/Plone50/dsc04791.jpg/@@images/778f9c06-36b0-485d-ab80-12c623dc4bc3.jpeg`.
 ```