Add initial docs for StreamField block previews

CHANGELOG.txt

@@ -30,6 +30,7 @@ Changelog
  * Fill in the ImageBlock alt text from the image’s default alt text when converting from ImageChooserBlock (Cynthia Kiser)
  * Make sure typing text at the bottom of the page editor always scrolls enough to keep the text into view (Jatin Bhardwaj)
  * Add StreamField and InlinePanel interfaces support for drag-and-drop reordering of items (Thibaud Colas, Sage Abdullah)
+ * Add previews support for StreamField blocks inside the block picker (Sage Abdullah, Thibaud Colas)
  * Fix: Improve handling of translations for bulk page action confirmation messages (Matt Westcott)
  * Fix: Ensure custom rich text feature icons are correctly handled when provided as a list of SVG paths (Temidayo Azeez, Joel William, LB (Ben) Johnston)
  * Fix: Ensure manual edits to `StreamField` values do not throw an error (Stefan Hammer)

docs/reference/streamfield/blocks.md

@@ -47,6 +47,21 @@ All block definitions accept the following optional keyword arguments:
 -   `group`
     -   The group used to categorize this block. Any blocks with the same group name will be shown together in the editor interface with the group name as a heading.
 
+(block_preview_arguments)=
+
+[StreamField blocks can have previews](configuring_block_previews) that will be shown inside the block picker. To accommodate the feature, all block definitions also accept the following optional keyword arguments:
+
+-   `description`
+    -   The description of the block. For [](field_block_types), it will fall back to `help_text` if not provided.
+-   `preview_value`
+    -   The placeholder value that will be used for rendering the preview. If not provided, it will fall back to the `default` value.
+-   `preview_template`
+    -   The template that is used to render the preview. If not provided, it will use the `wagtailcore/shared/block_preview.html` base template that reuses the block's real `template`.
+
+```{versionadded} 6.4
+The `description`, `preview_value`, and `preview_template` keyword arguments were added.
+```
+
 (field_block_types)=
 
 ## Field block types

docs/releases/6.4.md

@@ -25,6 +25,12 @@ In the default configuration, these tasks are executed immediately within the re
 
 This feature was developed by Jake Howard.
 
+### Previews for StreamField blocks
+
+You can now set up previews for StreamField blocks. The preview will be shown in the block chooser, along with a description for the block. This feature can help users choose the right block when writing content inside a StreamField. To enable this feature, see [](configuring_block_previews).
+
+This feature was developed by Sage Abdullah and Thibaud Colas.
+
 ### Headless documentation
 
 The new [](headless) documentation page curates important information about Wagtail’s headless capabilities, directly within the developer documentation. This is the foundation for a [headless improvements roadmap](https://github.com/wagtail/rfcs/pull/100) for Wagtail.

docs/topics/streamfield.md

@@ -512,6 +512,62 @@ class EventBlock(blocks.StructBlock):
 
 All block types, not just `StructBlock`, support the `template` property. However, for blocks that handle basic Python data types, such as `CharBlock` and `IntegerBlock`, there are some limitations on where the template will take effect. For further details, see [](boundblocks_and_values).
 
+(configuring_block_previews)=
+
+## Configuring block previews
+
+StreamField blocks can have previews that will be shown inside the block picker when you add a block in the editor. To enable this feature, you must configure the preview value and template. You can also add a description to help users pick the right block for their content.
+
+You can do so by [passing the keyword arguments](block_preview_arguments) `preview_value`, `preview_template`, and `description` when instantiating a block:
+
+```py
+("quote", blocks.StructBlock(
+    [
+        ("text", blocks.TextBlock()),
+        ("source", blocks.CharBlock()),
+    ],
+    preview_value={"text": "This is the coolest CMS ever.", "source": "Willie Wagtail"}
+    preview_template="myapp/previews/blocks/quote.html",
+    description="A quote with attribution to the source, rendered as a blockquote."
+))
+```
+
+You can also set `preview_value`, `preview_template`, and `description` as attributes in the `Meta` class of the block. For example:
+
+```py
+class QuoteBlock(blocks.StructBlock):
+    text = blocks.TextBlock()
+    attribute_name = blocks.CharBlock()
+
+    class Meta:
+        preview_value = {"text": "This is the coolest CMS ever.", "source": "Willie Wagtail"}
+        preview_template = "myapp/previews/blocks/quote.html"
+        description = "A quote with attribution to the source, rendered as a blockquote."
+```
+
+Alternatively, you can also override the `get_preview_value`, `get_preview_context`, and `get_preview_template` methods to achieve the desired results.
+
+In many cases, you likely want to use the block's real template that you already configure via `template` or `get_template` as described in [](streamfield_per_block_templates). Wagtail provides a default preview template for all blocks that makes use of the `{% include_block %}` tag (as described in [](streamfield_template_rendering)), which will reuse your block's specific template.
+
+However, the default template does not include any static assets that may be necessary to render your blocks properly. If you only need to add static assets to the preview page, you can skip specifying `preview_template` and instead override the default template globally. You can do so by creating a `wagtailcore/shared/block_preview.html` template inside one of your `templates` directories (with a higher precedence than the `wagtail` app) with the following content:
+
+```html+django
+{% extends "wagtailcore/shared/block_preview.html" %}
+{% load static %}
+
+{% block css %}
+    {{ block.super }}
+    <link rel="stylesheet" href="{% static 'css/my-styles.css' %}">
+{% endblock %}
+
+{% block js %}
+    {{ block.super }}
+    <script src="{% static 'js/my-script.js' %}"></script>
+{% endblock %}
+```
+
+For more details on overriding templates, see also Django's guide on [](inv:django#howto/overriding-templates).
+
 ## Customizations
 
 All block types implement a common API for rendering their front-end and form representations, and storing and retrieving values to and from the database. By subclassing the various block classes and overriding these methods, all kinds of customizations are possible, from modifying the layout of StructBlock form fields to implementing completely new ways of combining blocks. For further details, see [](custom_streamfield_blocks).