Typed table block¶

The typed_table_block module provides a StreamField block type for building tables consisting of mixed data types. Developers can specify a set of block types (such as RichTextBlock or FloatBlock) to be available as column types; page authors can then build up tables of any size by choosing column types from that list, in much the same way that they would insert blocks into a StreamField. Within each column, authors enter data using the standard editing control for that field (such as the Draftail editor for rich text cells).

Installation¶

Add "wagtail.contrib.typed_table_block" to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    "wagtail.contrib.typed_table_block",
]

Usage¶

TypedTableBlock can be imported from the module wagtail.contrib.typed_table_block.blocks and used within a StreamField definition. Just like StructBlock and StreamBlock, it accepts a list of (name, block_type) tuples to use as child blocks:

from wagtail.contrib.typed_table_block.blocks import TypedTableBlock
from wagtail import blocks
from wagtail.images.blocks import ImageChooserBlock


class DemoStreamBlock(blocks.StreamBlock):
    title = blocks.CharBlock()
    paragraph = blocks.RichTextBlock()
    table = TypedTableBlock(
        [
            ("text", blocks.CharBlock()),
            ("numeric", blocks.FloatBlock()),
            ("rich_text", blocks.RichTextBlock()),
            ("image", ImageChooserBlock()),
        ]
    )

To keep the UI as simple as possible for authors, it’s generally recommended to use Wagtail’s basic built-in block types as column types, as above. However, all custom block types and parameters are supported. For example, to define a ‘country’ column type consisting of a dropdown of country choices:

table = TypedTableBlock(
    [
        ("text", blocks.CharBlock()),
        ("numeric", blocks.FloatBlock()),
        ("rich_text", blocks.RichTextBlock()),
        ("image", ImageChooserBlock()),
        (
            "country",
            ChoiceBlock(
                choices=[
                    ("be", "Belgium"),
                    ("fr", "France"),
                    ("de", "Germany"),
                    ("nl", "Netherlands"),
                    ("pl", "Poland"),
                    ("uk", "United Kingdom"),
                ]
            ),
        ),
    ]
)

On your page template, the {% include_block %} tag (called on either the individual block, or the StreamField value as a whole) will render any typed table blocks as an HTML <table> element.

{% load wagtailcore_tags %}

{% include_block page.body %}

Or:

{% load wagtailcore_tags %}

{% for block in page.body %}
    {% if block.block_type == 'table' %}
        {% include_block block %}
    {% else %}
        {# rendering for other block types #}
    {% endif %}
{% endfor %}

Custom validation¶

As with other blocks, validation logic on TypedTableBlock can be customized by overriding the clean method (see StreamField validation). Raising a ValidationError exception from this method will attach the error message to the table as a whole. To attach errors to individual cells, the exception class wagtail.contrib.typed_table_block.blocks.TypedTableBlockValidationError can be used - in addition to the standard non_block_errors argument, this accepts a cell_errors argument consisting of a nested dict structure where the outer keys are row indexes and the inner keys are column indexes. For example:

from django.core.exceptions import ValidationError
from wagtail.blocks import IntegerBlock
from wagtail.contrib.typed_table_block.blocks import (
    TypedTableBlock,
    TypedTableBlockValidationError,
)


class LuckyTableBlock(TypedTableBlock):
    number = IntegerBlock()

    def clean(self, value):
        result = super().clean(value)
        errors = {}
        print(result.row_data)
        for row_num, row in enumerate(result.row_data):
            row_errors = {}
            for col_num, cell in enumerate(row["values"]):
                if cell == 13:
                    row_errors[col_num] = ValidationError(
                        "Table cannot contain the number 13"
                    )
            if row_errors:
                errors[row_num] = row_errors

        if errors:
            raise TypedTableBlockValidationError(cell_errors=errors)

        return result