DOC Explain how to customise image rendering (#529)

silverstripe · Jun 30, 2024 · 81c3f93 · 81c3f93
1 parent 4667582
commit 81c3f93
Show file tree

Hide file tree

Showing 2 changed files with 34 additions and 0 deletions.
diff --git a/en/02_Developer_Guides/14_Files/02_Images.md b/en/02_Developer_Guides/14_Files/02_Images.md
@@ -334,6 +334,19 @@ SilverStripe\Core\Injector\Injector:
 
 Manipulated images are stored as "file variants" in the same folder structure as the original image. The storage mechanism is described in the ["File Storage" guide](file_storage).
 
+## Controlling how images are rendered
+
+Developers can customise how `Image` instances are rendered on their website by overriding the `templates/SilverStripe/Assets/Storage/DBFile_Image.ss` template file.
+
+This will apply to images added to an `HTMLEditorField` and images invoked in templates.
+
+You can also choose to have different rendering logic for `HTMLEditorField` images and for images invoked in templates by overriding different templates.
+
+- Add a `SilverStripe/Assets/Shortcodes/ImageShortcodeProvider_Image.ss` to your theme to control images added to an HTMLEditorField.
+- Add a `DBFile_Image.ss` file to the root of your theme to control only images invoked in templates.
+
+Look at [Template inheritance](../templates/Template_Inheritance) for more information on how to override SS templates.
+
 ## API documentation
 
 - [File](api:SilverStripe\Assets\File)

diff --git a/en/08_Changelogs/5.3.0.md b/en/08_Changelogs/5.3.0.md
@@ -8,6 +8,7 @@ title: 5.3.0 (unreleased)
 
 - [Features and enhancements](#features-and-enhancements)
   - [High-level API for converting files](#file-converter)
+  - [Improve customisability of rendered images](#image-rendering)
   - [Validation for elemental content blocks when saving individual blocks](#elemental-validation)
   - [Define scaffolded form fields for relations to `DataObject` models](#scaffolded-relation-formfields)
   - [Support for `JOIN` in SQL `UPDATE`](#sql-update-join)
@@ -52,6 +53,26 @@ Out of the box `silverstripe/assets` provides the new [`InterventionImageFileCon
 
 See [convert a file to a different format](/developer_guides/files/file_manipulation/#file-conversion) for more details.
 
+### Improve customisability of rendered images {#image-rendering}
+
+We've aligned how images added to an [`HTMLEditorField`](api:SilverStripe\Forms\HTMLEditor\HTMLEditorField) and images invoked in templates are rendered. The markup up for both `<img>` tags are now generated from the same template file. This makes it easier to customise how images are rendered on your site.
+
+The template for this is `templates/SilverStripe/Assets/Storage/DBFile_Image.ss`. Add a file with that path to your Silverstripe CMS theme if you want to override it.
+
+This opens many interesting possibilities. For example, this code snippet will provide a WebP version of any image rendered on your site.
+
+```html
+<picture>
+    <source srcset="$Convert('webp').Link" type="image/webp">
+    <img $AttributesHTML >
+</picture>
+```
+
+You can also choose to have different rendering logic for `HTMLEditorField` images and for images invoked in templates by overriding different templates.
+
+- Add a `SilverStripe/Assets/Shortcodes/ImageShortcodeProvider_Image.ss` to your theme to control images added to an HTMLEditorField.
+- Add a `DBFile_Image.ss` file to the root of your theme to control only images invoked in templates.
+
 ### Validation for inline-editable elemental content blocks {#elemental-validation}
 
 Elemental content blocks now support validation when saving or publishing individual content blocks using the "three-dot" context menu in the top-right of the block.