|
| 1 | +--- |
| 2 | +html_meta: |
| 3 | + "description": "Image resolving and scaling in Plone Classic UI" |
| 4 | + "property=og:description": "Image resolving and scaling in Plone Classic UI" |
| 5 | + "property=og:title": "Image Handling" |
| 6 | + "keywords": "Plone, Classic UI, classic-ui, image, resize, scale" |
| 7 | +--- |
| 8 | + |
| 9 | +(classic-ui-images-label)= |
| 10 | + |
| 11 | +# Image handling |
| 12 | + |
| 13 | +The default content types and behaviors use the field `plone.namedfile.NamedBlobImage` for all images. |
| 14 | + |
| 15 | +For this field, image scaling and HTML tag creation is provided by the `plone.namedfile.scaling` module, specifically in the [`ImageScaling`](https://github.com/plone/plone.namedfile/blob/ecf33a2bc7a8c61888909bc383b3e08d80888e43/plone/namedfile/scaling.py#L350) view. |
| 16 | + |
| 17 | +Given a Dexterity content type named `news-item1` with a `plone.namedfile.NamedBlobImage` field named `image`, we can use the following APIs to access the image scales and manage scales. |
| 18 | + |
| 19 | +```{note} |
| 20 | +We will use the image object as context in the following examples. |
| 21 | +``` |
| 22 | + |
| 23 | +(classic-ui-images-default-scales-label)= |
| 24 | + |
| 25 | +## Default scales |
| 26 | + |
| 27 | +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: |
| 28 | + |
| 29 | +* large 768:768 |
| 30 | +* preview 400:400 |
| 31 | +* mini 200:200 |
| 32 | +* thumb 128:128 |
| 33 | +* tile 64:64 |
| 34 | +* icon 32:32 |
| 35 | +* listing 16:16 |
| 36 | + |
| 37 | +You can add or change scales as you like. |
| 38 | + |
| 39 | + |
| 40 | +(classic-ui-images-image-resolving-by-uri-label)= |
| 41 | + |
| 42 | +## Image resolving by URI |
| 43 | + |
| 44 | +Plone can resolve an image scale via URI in different ways. |
| 45 | + |
| 46 | + |
| 47 | +(classic-ui-images-by-field-and-scale-name-label)= |
| 48 | + |
| 49 | +### By field and scale name |
| 50 | + |
| 51 | +Given our `news-item1` with the field `image`, we can get the name scale `thumb` as follows: |
| 52 | + |
| 53 | +`http://localhost:8080/Plone/news-item1/@@images/image/thumb` |
| 54 | + |
| 55 | +To get the original image, you can leave out the scale: |
| 56 | + |
| 57 | +`http://localhost:8080/Plone/news-item1/@@images/image` |
| 58 | + |
| 59 | + |
| 60 | +(classic-ui-images-by-cacheable-scale-uid-name-label)= |
| 61 | + |
| 62 | +### By cacheable scale UID name |
| 63 | + |
| 64 | +When an image scale is created, it will be cached under the name `UID.EXT` (i.e. `f4c34254b44ba351af7393bfe0296664.jpeg`) in the object annotations. |
| 65 | +Scaling keeps the uploaded formats, except for TIFF which ends up as JPEG. |
| 66 | +It can be resolved as follows: |
| 67 | + |
| 68 | +`http://localhost:8080/Plone/news-item1/@@images/3d182f34-8773-4f20-a79d-8774c3151b7e.jpeg` |
| 69 | + |
| 70 | +This is useful for caching URLs in Varnish or the browser. |
| 71 | +In case the uploaded image or scale definitions have changed, they will be saved again under a different UID. |
| 72 | +This changes the URL and forces either the browser, or a cache proxy such as Varnish, to fetch it again. |
| 73 | +When a scale has changed, the old stored entry in the annotation will be deleted after 24 hours. |
| 74 | +If one changes an image which is used in multiple pages, the updated versions will only be shown after a restart of the Plone instance, saving the pages again, or after 24 hours. |
| 75 | + |
| 76 | + |
| 77 | +(classic-ui-images-image-tag-label)= |
| 78 | + |
| 79 | +## Image tag |
| 80 | + |
| 81 | +To get an HTML tag for a scaled image, you can use the `ImageScaling` view as follows: |
| 82 | + |
| 83 | +```python |
| 84 | +from plone import api |
| 85 | + |
| 86 | +scale_util = api.content.get_view("images", context, request) |
| 87 | +tag = scale_util.tag("image", scale="mini") |
| 88 | +``` |
| 89 | + |
| 90 | +To get a specific image size: |
| 91 | + |
| 92 | +```python |
| 93 | +from plone import api |
| 94 | + |
| 95 | +scale_util = api.content.get_view("images", context, request) |
| 96 | +tag = scale_util.tag("image", width=600, height=200) |
| 97 | +``` |
| 98 | + |
| 99 | +The complete list of arguments with their default values is shown in the following example. |
| 100 | + |
| 101 | +```python |
| 102 | +from plone import api |
| 103 | + |
| 104 | +scale_util = api.content.get_view("images", context, request) |
| 105 | +tag = scale_util.tag( |
| 106 | + fieldname=None, |
| 107 | + scale=None, |
| 108 | + height=None, |
| 109 | + width=None, |
| 110 | + direction="thumbnail" |
| 111 | +) |
| 112 | +``` |
| 113 | + |
| 114 | +If you pass additional kwargs to `tag`, they become attributes on `tag`. |
| 115 | + |
| 116 | + |
| 117 | +(classic-ui-images-image-scaling-no-tag-creation-label)= |
| 118 | + |
| 119 | +## Image scaling without tag creation |
| 120 | + |
| 121 | +To get the scaling information only without creating an HTML tag, you can use the `ImageScaling` view as follows: |
| 122 | + |
| 123 | +```python |
| 124 | +from plone import api |
| 125 | + |
| 126 | +scale_util = api.content.get_view("images", context, request) |
| 127 | +# The default `Image` content type's field name is "image". |
| 128 | +# On the following line of code, "image" is the field name. |
| 129 | +image_scale = scale_util.scale("image", scale="mini") |
| 130 | +print(image_scale.url) |
| 131 | +print(image_scale.width) |
| 132 | +print(image_scale.height) |
| 133 | +``` |
| 134 | + |
| 135 | +This will produce the following output: |
| 136 | + |
| 137 | +```console |
| 138 | +http://localhost:8080/Plone/news-item1/@@images/3d182f34-8773-4f20-a79d-8774c3151b7e.jpeg |
| 139 | +200 |
| 140 | +110 |
| 141 | +``` |
| 142 | + |
| 143 | +The most important properties are the following: |
| 144 | + |
| 145 | +- `data` |
| 146 | +- `fieldname` |
| 147 | +- `height` |
| 148 | +- `mimetype` |
| 149 | +- `srcset` |
| 150 | +- `srcset_attribute` |
| 151 | +- `tag` |
| 152 | +- `uid` |
| 153 | +- `url` |
| 154 | +- `width` |
| 155 | + |
| 156 | +You can directly create an HTML tag from `image_scale`: |
| 157 | + |
| 158 | +```pycon |
| 159 | +>>> print(image_scale.tag()) |
| 160 | + |
| 161 | +<img src="http://localhost:8080/Plone/news/newsitem1/@@images/9f676d46-0cb3-4512-a831-a5db4079bdfa.jpeg" alt="News Item 1!" title="News Item 1" height="21" width="32" srcset="http://localhost:8080/Plone/news/newsitem1/@@images/4a68513c-cffd-4de0-8a35-80627945b80f.jpeg 2x, http://localhost:8080/Plone/news/newsitem1/@@images/c32929c6-cb89-4ce7-846f-38adf29c09a4.jpeg 3x" /> |
| 162 | +``` |
| 163 | + |
| 164 | +Instead of using the configured named scales, you can get an HTML tag with any specific size in pixels: |
| 165 | + |
| 166 | +```python |
| 167 | +from plone import api |
| 168 | + |
| 169 | +scale_util = api.content.get_view("images", context, request) |
| 170 | +tag = scale_util.scale("image", width=600, height=200) |
| 171 | +``` |
| 172 | + |
| 173 | +(classic-ui-images-using-image_scale0-in-templates-label)= |
| 174 | + |
| 175 | +### Using image_scale in templates |
| 176 | + |
| 177 | +You could use the URL-variant from above, but that would be an uncached version. |
| 178 | +To create a cached scale in a page template you can do the following: |
| 179 | + |
| 180 | +```xml |
| 181 | +<div tal:define="scale_view context/@@images; |
| 182 | + image_scale python: scale_view.scale('image', 'mini')"> |
| 183 | + <img |
| 184 | + src="${python: image_scale.url}" |
| 185 | + width="${python: image_scale.width" |
| 186 | + height="${python: image_scale.height}" |
| 187 | + > |
| 188 | +</div> |
| 189 | +``` |
| 190 | + |
| 191 | +Or you can get the HTML tag back, and replace the current tag with it: |
| 192 | + |
| 193 | +```xml |
| 194 | +<div tal:define="scale_view context/@@images"> |
| 195 | + <img tal:replace="structured python: scale_view.tag('image', 'mini')"> |
| 196 | +</div> |
| 197 | +``` |
| 198 | + |
| 199 | +You can also provide the following keyword arguments to set `title`, `alt`, or `css_class` for the generated tag: |
| 200 | + |
| 201 | +```xml |
| 202 | +<div tal:define="scale_view context/@@images"> |
| 203 | + <img tal:replace="structured python: scale_view.tag('banner', 'mini', title='The Banner', alt='Alternative text', css_class='banner')"> |
| 204 | +</div> |
| 205 | +``` |
| 206 | + |
| 207 | +(classic-ui-images-get-image_scale-by-cached-uid-name-label)= |
| 208 | + |
| 209 | +### Get image_scale by cached UID name |
| 210 | + |
| 211 | +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: |
| 212 | + |
| 213 | +```python |
| 214 | +import re |
| 215 | +from plone import api |
| 216 | + |
| 217 | +uri = "http://localhost:8080/Plone/news-item1/@@images/3d182f34-8773-4f20-a79d-8774c3151b7e.jpeg" |
| 218 | +image_url = re.compile(r"(.*@@images)\/([a-zA-Z0-9.-]*)\/?([a-zA-Z]*)") |
| 219 | + |
| 220 | +url_match = image_url.match(uri) |
| 221 | +groups = url_match.groups() |
| 222 | +# ("http://localhost:8080/Plone/news-item1", "3d182f34-8773-4f20-a79d-8774c3151b7e.jpeg") |
| 223 | +scale_util = api.content.get_view("images", context, request) |
| 224 | +image_scale = scaling_util.publishTraverse(context.REQUEST, groups[1]) |
| 225 | +``` |
| 226 | + |
| 227 | + |
| 228 | +(classic-ui-images-scaling-direction-label)= |
| 229 | + |
| 230 | +## Scaling `direction` |
| 231 | + |
| 232 | +The default direction is `thumbnail`. |
| 233 | + |
| 234 | +Other options are: |
| 235 | + |
| 236 | +* `down` |
| 237 | +* `keep` |
| 238 | +* `scale-crop-to-fill` |
| 239 | +* `scale-crop-to-fit` |
| 240 | +* `thumbnail` |
| 241 | +* `up` |
| 242 | + |
| 243 | + |
| 244 | +(classic-ui-images-permissions-label)= |
| 245 | + |
| 246 | +## Permissions |
| 247 | + |
| 248 | +The `ImageScaling` view explicitly checks the permissions of the current user. |
| 249 | +To access image scales, which are normally not accessible to the current user, override the `validate_access` method in `plone.namedfile.scaling.ImageScale`. |
0 commit comments