wagtail-block-reference

BlockReference support for Wagtail — enables forward and cyclic block references.

Heads up: this package is quite hacky. It works by monkey-patching Wagtail internals (Python and JS), which is inherently fragile. It exists because the upstream PR (wagtail#14279) may take a while to land (if it ever does), and waiting wasn't an option for me :). The test suite deliberately targets the patched internals so that a future Wagtail upgrade that breaks the patches fails loudly rather than silently misbehaving.

Installation

pip install wagtail-block-reference

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "wagtail_block_reference",
]

Usage

from wagtail import blocks
from wagtail_block_reference import BlockReference

class CommentBlock(blocks.StructBlock):
    text = blocks.CharBlock()
    replies = blocks.ListBlock(BlockReference(lambda: CommentBlock))

Targets must resolve to the same instance

A cycle ends when a walk meets a target it has already seen, and "already seen" means the same object. So a reference must resolve to the same block instance every time.

Declaring the target as a class, a dotted path, or a class attribute gives you that for free. A factory does not:

# Fine: one CommentBlock instance, memoised on the reference.
replies = blocks.ListBlock(BlockReference(lambda: CommentBlock))

# Broken: a new block on every resolution, so the graph never closes.
replies = blocks.ListBlock(BlockReference(lambda: registry.build("comment")))

The second form is an infinitely deep graph rather than a cyclic one, and no visited-set can bound it. It shows up most easily with a dynamic block registry — memoise the registry so a given name always yields the same instance.

This is caught rather than left to exhaust the stack: past WAGTAIL_BLOCK_REFERENCE_MAX_WALK_DEPTH levels (default 100), check() reports wagtailcore.E010 and other walks raise BlockReferenceDepthExceeded. Raise the setting if a graph really is nested that deeply through references.

How it works

BlockReference is a lazy proxy that resolves its target block on first access. The target can be a lambda (for forward/cyclic references), a dotted import path, or a block class.

The package ships two patches:

Python patch (patches.py, applied at import time): hooks into Wagtail's block metaclass so that BlockReference attributes declared on a StructBlock are collected as child blocks, and registers a telepath adapter so the block serialises as its resolved target.

JS patch (patch.js, injected via insert_global_admin_js): intercepts window.telepath before Wagtail's own bundles load, then wraps StructBlock and StreamBlock prototypes with a lazy childBlockDefsByName getter. Without this, the cyclic telepath graph causes a Maximum call stack size exceeded crash when the editor tries to build the block name map at construction time.

Supported versions

All Wagtail versions that are currently under active or security support: 7.0 LTS, 7.3, and 7.4 LTS. CI tests against each of these. Versions drop off the matrix as they go end-of-life.

Development

# Install dependencies
uv sync

# Lint & format
uv run ruff check .
uv run ruff format .

# Run all tests (unit + E2E) against a single Wagtail version
uv run playwright install chromium
uv run pytest tests/

# Run all tests against all supported Wagtail versions (installs Chromium automatically)
uv run tox

# Run all tests against all supported Wagtail versions (installs Chromium automatically)
# and see visually what the browser is doing
uv run tox  -- --headed --slowmo=500

# Run against a specific version
uv run tox -e wagtail74

# Run against a specific version and see visually what the browser is doing
uv run tox -e wagtail74 -- --headed --slowmo=500

License

MIT