Expand docs for StreamField block previews

docs/reference/streamfield/blocks.md

@@ -51,15 +51,15 @@ All block definitions accept the following optional keyword arguments or `Meta`
 
 [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 options:
 
--   `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.
+    -   The placeholder value that will be used for rendering the preview. See {meth}`~wagtail.blocks.Block.get_preview_value` for more details.
 -   `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`.
+    -   The template that is used to render the preview. See {meth}`~wagtail.blocks.Block.get_preview_template` for more details.
+-   `description`
+    -   The description of the block to be shown to editors. See {meth}`~wagtail.blocks.Block.get_description` for more details.
 
 ```{versionadded} 6.4
-The `description`, `preview_value`, and `preview_template` keyword arguments were added.
+The `preview_value`, `preview_template`, and `description` keyword arguments were added.
 ```
 
 All block definitions have the following methods that can be overridden:
@@ -69,6 +69,10 @@ All block definitions have the following methods that can be overridden:
 
     .. automethod:: wagtail.blocks.Block.get_context
     .. automethod:: wagtail.blocks.Block.get_template
+    .. automethod:: wagtail.blocks.Block.get_preview_value
+    .. automethod:: wagtail.blocks.Block.get_preview_context
+    .. automethod:: wagtail.blocks.Block.get_preview_template
+    .. automethod:: wagtail.blocks.Block.get_description
 ```
 
 (field_block_types)=

docs/topics/streamfield.md

@@ -555,11 +555,31 @@ class QuoteBlock(blocks.StructBlock):
         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.
+For more details on the preview options, see the corresponding {meth}`~wagtail.blocks.Block.get_preview_value`, {meth}`~wagtail.blocks.Block.get_preview_template`, and  {meth}`~wagtail.blocks.Block.get_description` methods, as well as the {meth}`~wagtail.blocks.Block.get_preview_context` method.
 
-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.
+In particular, the `get_preview_value()` method can be overridden to provide a dynamic preview value, such as from the database:
 
-However, the default preview 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:
+```python
+from myapp.models import Quote
+
+
+class QuoteBlock(blocks.StructBlock):
+    ...
+
+    def get_preview_value(self, value):
+        quote = Quote.objects.first()
+        return {"text": quote.text, "source": quote.source}
+```
+
+(streamfield_global_preview_template)=
+
+### Overriding the global preview template
+
+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). However, such templates are only an HTML fragment for the block, whereas the preview requires a complete HTML document as the template.
+
+To avoid having to specify `preview_template` for each block, Wagtail provides a default preview template for all blocks. This template makes use of the `{% include_block %}` tag (as described in [](streamfield_template_rendering)), which will reuse your block's specific template.
+
+Note that the default preview 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 default preview template, you can skip specifying `preview_template` for each block 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" %}

wagtail/admin/views/generic/preview.py

@@ -197,6 +197,8 @@ class StreamFieldBlockPreview(TemplateView):
     def base_context(self):
         # Do NOT use the name `block` in the context, as it will conflict with
         # the current block inside a template {% block %} tag.
+        # If any changes are made here that needs to be publicly documented,
+        # make sure to update the docs for `Block.get_preview_context`.
         return {
             "request": self.request,
             "block_def": self.block_def,

wagtail/blocks/base.py

@@ -273,26 +273,59 @@ class Block(metaclass=BaseBlock):
         return mark_safe(render_to_string(template, new_context))
 
     def get_preview_context(self, value, parent_context=None):
-        # We do not fall back to `get_context` here, because the preview context
-        # will be used for a complete view, not just the block. Instead, the
-        # default preview context uses `{% include_block %}`, which will use
-        # `get_context`.
+        """
+        Return a dict of context variables to be used as the template context
+        when rendering the block's preview. The ``value`` argument is the value
+        returned by :meth:`get_preview_value`. The ``parent_context`` argument
+        contains the following variables:
+
+        - ``request``: The current request object.
+        - ``block_def``: The block instance.
+        - ``block_class``: The block class.
+        - ``bound_block``: A ``BoundBlock`` instance representing the block and its value.
+
+        If :ref:`the global preview template <streamfield_global_preview_template>`
+        is used, the block will be rendered as the main content using
+        ``{% include_block %}``, which in turn uses :meth:`get_context`. As a
+        result, the context returned by this method will be available as the
+        ``parent_context`` for ``get_context()`` when the preview is rendered.
+        """
+        # NOTE: see StreamFieldBlockPreview.base_context for the context variables
+        # that can be documented.
         return parent_context or {}
 
     def get_preview_template(self, value, context=None):
-        # We do not fall back to `get_template` here, because the template will
-        # be used for a complete view, not just the block. In most cases, the
-        # block's template cannot stand alone for the preview, as it would be
-        # missing the necessary static assets.
-        #
-        # Instead, the default preview template uses `{% include_block %}`,
-        # which will use `get_template` if a template is defined.
+        """
+        Return the template to use for rendering the block's preview. The ``value``
+        argument is the value returned by :meth:`get_preview_value`. The ``context``
+        argument contains the variables listed for the ``parent_context`` argument
+        of :meth:`get_preview_context` above (and not the context returned by that
+        method itself).
+
+        Note that the preview template is used to render a complete HTML page of
+        the preview, not just an HTML fragment for the block. The method returns
+        the ``preview_template`` attribute from the block's options if provided,
+        and falls back to
+        :ref:`the global preview template <streamfield_global_preview_template>`
+        otherwise.
+
+        If the global preview template is used, the block will be rendered as the
+        main content using ``{% include_block %}``, which in turn uses
+        :meth:`get_template`.
+        """
         return (
             getattr(self.meta, "preview_template", None)
             or self.DEFAULT_PREVIEW_TEMPLATE
         )
 
     def get_preview_value(self):
+        """
+        Return the placeholder value that will be used for rendering the block's
+        preview. By default, the value is the ``preview_value`` from the block's
+        options if provided, otherwise the ``default`` is used as fallback. This
+        method can be overridden to provide a dynamic preview value, such as
+        from the database.
+        """
         if hasattr(self.meta, "preview_value"):
             return self.normalize(self.meta.preview_value)
         return self.get_default()
@@ -328,6 +361,11 @@ class Block(metaclass=BaseBlock):
         return has_specific_template or (has_preview_value and has_global_template)
 
     def get_description(self):
+        """
+        Return the description of the block to be shown to editors as part of the preview.
+        For :ref:`field block types <field_block_types>`, it will fall back to
+        ``help_text`` if not provided.
+        """
         return getattr(self.meta, "description", "")
 
     def get_api_representation(self, value, context=None):