Experimental Feature: New ImageBlock for StreamField (Work in Progress)

client/src/entrypoints/images/image-chooser-modified.js

@@ -0,0 +1,25 @@
+class ImageBlockDefinition extends window.wagtailStreamField.blocks
+  .StructBlockDefinition {
+  render(placeholder, prefix, initialState, initialError) {
+    const block = super.render(placeholder, prefix, initialState, initialError);
+
+    const altTextField = document.getElementById(prefix + '-alt_text');
+    const isDecorativeField = document.getElementById(prefix + '-decorative');
+    const updateStateInput = () => {
+      if (isDecorativeField.checked) {
+        altTextField.setAttribute('disabled', true);
+      } else {
+        altTextField.removeAttribute('disabled');
+      }
+    };
+    updateStateInput();
+    isDecorativeField.addEventListener('change', updateStateInput);
+
+    return block;
+  }
+}
+
+window.telepath.register(
+  'wagtail.images.blocks.ImageBlock',
+  ImageBlockDefinition,
+);

client/webpack.config.js

@@ -61,6 +61,7 @@ module.exports = function exports(env, argv) {
       'image-chooser',
       'image-chooser-modal',
       'image-chooser-telepath',
+      'image-chooser-modified',
     ],
     'documents': [
       'document-chooser',

wagtail/blocks/field_block.py

@@ -1,3 +1,4 @@
+import copy
 import datetime
 from decimal import Decimal
 
@@ -817,11 +818,22 @@ def bulk_to_python(self, values):
         """Return the model instances for the given list of primary keys.
 
         The instances must be returned in the same order as the values and keep None values.
+        If the same ID appears multiple times, a distinct object instance is created for each one.
         """
         objects = self.model_class.objects.in_bulk(values)
-        return [
-            objects.get(id) for id in values
-        ]  # Keeps the ordering the same as in values.
+        seen_ids = set()
+        result = []
+
+        for id in values:
+            obj = objects.get(id)
+            if obj is not None and id in seen_ids:
+                # this object is already in the result list, so we need to make a copy
+                obj = copy.copy(obj)
+
+            result.append(obj)
+            seen_ids.add(id)
+
+        return result
 
     def get_prep_value(self, value):
         # the native value (a model instance or None) should serialise to a PK or None

wagtail/images/blocks.py

@@ -1,8 +1,13 @@
+from django import forms
+from django.core.exceptions import ValidationError
 from django.template.loader import render_to_string
 from django.utils.functional import cached_property
 
 from wagtail.admin.compare import BlockComparison
-from wagtail.blocks import ChooserBlock
+from wagtail.blocks import BooleanBlock, CharBlock, ChooserBlock, StructBlock
+from wagtail.blocks.struct_block import StructBlockAdapter, StructBlockValidationError
+from wagtail.images.models import AbstractImage
+from wagtail.telepath import register
 
 from .shortcuts import get_rendition_or_not_found
 
@@ -51,3 +56,110 @@ def htmldiff(self):
                 "image_b": self.val_b,
             },
         )
+
+
+class ImageBlock(StructBlock):
+    image = ImageChooserBlock(required=True)
+    decorative = BooleanBlock(
+        default=False, required=False, label="Image is decorative"
+    )
+    alt_text = CharBlock(required=False)
+
+    def get_searchable_content(self, value):
+        return []
+
+    def _struct_value_to_image(self, struct_value):
+        image = struct_value.get("image")
+        decorative = struct_value.get("decorative")
+        if image:
+            # If the image is decorative, set alt_text to an empty string
+            image.contextual_alt_text = (
+                "" if decorative else struct_value.get("alt_text", "")
+            )
+            image.decorative = decorative
+        return image
+
+    def to_python(self, value):
+        struct_value = super().to_python(value)
+        return self._struct_value_to_image(struct_value)
+
+    def bulk_to_python(self, values):
+        struct_values = super().bulk_to_python(values)
+        return [
+            self._struct_value_to_image(struct_value) for struct_value in struct_values
+        ]
+
+    def value_from_datadict(self, data, files, prefix):
+        struct_value = super().value_from_datadict(data, files, prefix)
+        return self._struct_value_to_image(struct_value)
+
+    def clean(self, value):
+        if value is None:
+            raise StructBlockValidationError(
+                block_errors={
+                    "image": ValidationError("Expected an image instance, got nothing")
+                }
+            )
+
+        if not isinstance(value, AbstractImage):
+            raise StructBlockValidationError(
+                block_errors={
+                    "image": ValidationError(
+                        "Expected an image instance, got %r" % value
+                    )
+                }
+            )
+
+        if not value.contextual_alt_text and not value.decorative:
+            raise StructBlockValidationError(
+                block_errors={
+                    "alt_text": ValidationError(
+                        "Alt text is required for non-decorative images"
+                    )
+                }
+            )
+
+        return value
+
+    def normalize(self, value):
+        if value is None or isinstance(value, AbstractImage):
+            return value
+        else:
+            struct_value = super().normalize(value)
+            return self._struct_value_to_image(struct_value)
+
+    def get_form_state(self, value):
+        return {
+            "image": self.child_blocks["image"].get_form_state(value),
+            "alt_text": value and value.contextual_alt_text,
+            "decorative": value and value.decorative,
+        }
+
+    def get_prep_value(self, value):
+        return {
+            "image": self.child_blocks["image"].get_prep_value(value),
+            "alt_text": value and value.contextual_alt_text,
+            "decorative": value and value.decorative,
+        }
+
+    def extract_references(self, value):
+        return self.child_blocks["image"].extract_references(value)
+
+    class Meta:
+        icon = "image"
+        template = "wagtailimages/widgets/image.html"
+
+
+class ImageBlockAdapter(StructBlockAdapter):
+    js_constructor = "wagtail.images.blocks.ImageBlock"
+
+    @cached_property
+    def media(self):
+        structblock_media = super().media
+        return forms.Media(
+            js=structblock_media._js + ["wagtailimages/js/image-chooser-modified.js"],
+            css=structblock_media._css,
+        )
+
+
+register(ImageBlockAdapter(), ImageBlock)

wagtail/images/models.py

@@ -289,6 +289,11 @@ class AbstractImage(ImageFileMixin, CollectionMember, index.Indexed, models.Mode
 
     objects = ImageQuerySet.as_manager()
 
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.is_decorative = False
+        self.contextual_alt_text = None
+
     def _set_file_hash(self):
         with self.open_file() as f:
             self.file_hash = hash_filelike(f)
@@ -618,6 +623,9 @@ def find_existing_renditions(
             ]
             for rendition in Rendition.cache_backend.get_many(cache_keys).values():
                 filter = filters_by_spec[rendition.filter_spec]
+                # The retrieved rendition needs to be associated with the current image instance, so that any
+                # locally-set properties such as contextual_alt_text are respected
+                rendition.image = self
                 found[filter] = rendition
 
             # For items not found in the cache, look in the database
@@ -1218,7 +1226,10 @@ def url(self):
 
     @property
     def alt(self):
-        return self.image.default_alt_text
+        if self.image.is_decorative:
+            return ""
+        else:
+            return self.image.contextual_alt_text
 
     @property
     def attrs(self):

wagtail/images/templates/wagtailimages/widgets/image.html

@@ -0,0 +1,5 @@
+{% load wagtailimages_tags %}
+
+<figure>
+    {% image value fill-600x338 loading="lazy" %}
+</figure>

wagtail/images/tests/test_blocks.py

@@ -1,9 +1,11 @@
 import unittest.mock
 
+from bs4 import BeautifulSoup
 from django.apps import apps
 from django.test import TestCase
 
-from wagtail.images.blocks import ImageChooserBlock
+from wagtail.blocks.struct_block import StructBlockValidationError
+from wagtail.images.blocks import ImageBlock, ImageChooserBlock
 
 from .utils import (
     Image,
@@ -73,3 +75,68 @@ def test_extract_references(self):
 
         # None should not yield any references
         self.assertListEqual(list(block.extract_references(None)), [])
+
+
+class TestImageBlock(TestImageChooserBlock):
+    def test_render(self):
+        block = ImageBlock()
+        value = {
+            "image": self.image.id,  # An id is expected
+            "alt_text": "Sample alt text",
+            "decorative": False,
+        }
+        html = block.render(block.to_python(value))
+        soup = BeautifulSoup(html, "html.parser")
+        img_tag = soup.find("img")
+
+        # check specific attributes
+        self.assertEqual(img_tag["alt"], value.get("alt_text"))
+        self.assertIn("/media/images/test.", img_tag["src"])
+
+    def test_render_as_decorative(self):
+        block = ImageBlock()
+        value = {
+            "image": self.image.id,  # An id is expected
+            "alt_text": "Sample alt text",
+            "decorative": True,
+        }
+        html = block.render(block.to_python(value))
+        soup = BeautifulSoup(html, "html.parser")
+        img_tag = soup.find("img")
+
+        # check specific attributes
+        self.assertEqual(img_tag["alt"], "")
+        self.assertIn("/media/images/test.", img_tag["src"])
+
+    def test_no_alt_text(self):
+        block = ImageBlock()
+        value = {
+            "image": self.image.id,  # An id is expected
+            "alt_text": None,  # No alt text passed
+            "decorative": False,
+        }
+
+        # Use assertRaises as a context manager to check if a ValidationError is raised
+        with self.assertRaises(StructBlockValidationError) as context:
+            block.clean(block.to_python(value))
+
+        # Check the error message
+        self.assertIn(
+            "Alt text is required for non-decorative images",
+            str(context.exception.block_errors["alt_text"]),
+        )
+
+    def test_wrong_instance_type(self):
+        block = ImageBlock()
+        value = {"image": self.image.id, "alt_text": "Blank", "decorative": False}
+
+        # Use assertRaises as a context manager to check if a ValidationError is raised
+        with self.assertRaises(StructBlockValidationError) as context:
+            # pass in dict instead of normalized image instance
+            block.clean(value)
+
+        # Check the error message
+        self.assertIn(
+            "Expected an image instance, got %r" % value,
+            str(context.exception.block_errors["image"]),
+        )