From fa81702f3fd770a85a11d601a71f446ab6ed78c7 Mon Sep 17 00:00:00 2001
From: Sage Abdullah <sage.abdullah@torchbox.com>
Date: Mon, 3 Feb 2025 12:28:34 +0000
Subject: [PATCH] Add reference docs for Block.get_template and
Block.get_context
---
docs/reference/streamfield/blocks.md | 19 ++++++++++++++-----
wagtail/blocks/base.py | 13 ++++++-------
2 files changed, 20 insertions(+), 12 deletions(-)
diff --git a/docs/reference/streamfield/blocks.md b/docs/reference/streamfield/blocks.md
index b4fdca84fb..8229f3920a 100644
--- a/docs/reference/streamfield/blocks.md
+++ b/docs/reference/streamfield/blocks.md
@@ -2,7 +2,7 @@
# StreamField block reference
-This document details the block types provided by Wagtail for use in [StreamField](streamfield), and how they can be combined into new block types.
+This document details the block types provided by Wagtail for use in [StreamField](streamfield_topic), and how they can be combined into new block types.
```{note}
While block definitions look similar to model fields, they are not the same thing. Blocks are only valid within a StreamField - using them in place of a model field will not work.
@@ -32,16 +32,16 @@ body = StreamField([
})
```
-## Block options
+## Block options and methods
-All block definitions accept the following optional keyword arguments:
+All block definitions accept the following optional keyword arguments or `Meta` class attributes:
- `default`
- The default value that a new 'empty' block should receive.
- `label`
- The label to display in the editor interface when referring to this block - defaults to a prettified version of the block name (or, in a context where no name is assigned - such as within a `ListBlock` - the empty string).
- `icon`
- - The name of the icon to display for this block type in the menu of available block types. For a list of icon names, see the Wagtail style guide, which can be enabled by adding `wagtail.contrib.styleguide` to your project’s `INSTALLED_APPS`.
+ - The name of the icon to display for this block type in the editor. For more details, see our [icons overview](icons).
- `template`
- The path to a Django template that will be used to render this block on the front end. See [Template rendering](streamfield_template_rendering)
- `group`
@@ -49,7 +49,7 @@ All block definitions accept the following optional keyword arguments:
(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:
+[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.
@@ -62,6 +62,15 @@ All block definitions accept the following optional keyword arguments:
The `description`, `preview_value`, and `preview_template` keyword arguments were added.
```
+All block definitions have the following methods that can be overridden:
+
+```{eval-rst}
+.. autoclass:: wagtail.blocks.Block
+
+ .. automethod:: wagtail.blocks.Block.get_context
+ .. automethod:: wagtail.blocks.Block.get_template
+```
+
(field_block_types)=
## Field block types
diff --git a/wagtail/blocks/base.py b/wagtail/blocks/base.py
index c37d359a56..08854df06b 100644
--- a/wagtail/blocks/base.py
+++ b/wagtail/blocks/base.py
@@ -224,8 +224,9 @@ class Block(metaclass=BaseBlock):
def get_context(self, value, parent_context=None):
"""
- Return a dict of context variables (derived from the block value and combined with the parent_context)
- to be used as the template context when rendering this value through a template.
+ Return a dict of context variables (derived from the block ``value`` and combined with the
+ ``parent_context``) to be used as the template context when rendering this value through a
+ template. See :ref:`the usage example <streamfield_get_context>` for more details.
"""
context = parent_context or {}
@@ -239,11 +240,9 @@ class Block(metaclass=BaseBlock):
def get_template(self, value=None, context=None):
"""
- Return the template to use for rendering the block if specified on meta class.
- This extraction was added to make dynamic templates possible if you override this method
-
- value contains the current value of the block, allowing overridden methods to
- select the proper template based on the actual block value.
+ Return the template to use for rendering the block if specified.
+ This method allows for dynamic templates based on the block instance and a given ``value``.
+ See :ref:`the usage example <streamfield_get_template>` for more details.
"""
return getattr(self.meta, "template", None)