diff --git a/en/02_Developer_Guides/14_Files/02_Images.md b/en/02_Developer_Guides/14_Files/02_Images.md index 5c31916e1..803e5776f 100644 --- 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 index 20b12144a..67ad84290 100644 --- 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 `` 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 + + + + +``` + +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.