`` element (where ``my_block_name`` is the block name given in the StreamField definition). If you wish to provide your own HTML markup, you can instead iterate over the field's value, and invoke ``{% include_block %}`` on each block in turn:
.. code-block:: html+django
{% load wagtailcore_tags %}
{% for block in page.body %}
{% include_block block %}
{% endfor %}
For more control over the rendering of specific block types, each block object provides ``block_type`` and ``value`` properties:
.. code-block:: html+django
{% load wagtailcore_tags %}
{% for block in page.body %}
{% if block.block_type == 'heading' %}
{{ block.value }}
{% else %}
{% include_block block %}
{% endif %}
{% endfor %}
By default, each block is rendered using simple, minimal HTML markup, or no markup at all. For example, a CharBlock value is rendered as plain text, while a ListBlock outputs its child blocks in a `
` wrapper. To override this with your own custom HTML rendering, you can pass a ``template`` argument to the block, giving the filename of a template file to be rendered. This is particularly useful for custom block types derived from StructBlock:
.. code-block:: python
('person', blocks.StructBlock(
[
('first_name', blocks.CharBlock(required=True)),
('surname', blocks.CharBlock(required=True)),
('photo', ImageChooserBlock()),
('biography', blocks.RichTextBlock()),
],
template='myapp/blocks/person.html',
icon='user'
))
Or, when defined as a subclass of StructBlock:
.. code-block:: python
class PersonBlock(blocks.StructBlock):
first_name = blocks.CharBlock(required=True)
surname = blocks.CharBlock(required=True)
photo = ImageChooserBlock()
biography = blocks.RichTextBlock()
class Meta:
template = 'myapp/blocks/person.html'
icon = 'user'
Within the template, the block value is accessible as the variable ``value``:
.. code-block:: html+django
{% load wagtailimages_tags %}
{% image value.photo width-400 %}
{{ value.first_name }} {{ value.surname }}
{{ value.biography }}
Since ``first_name``, ``surname``, ``photo`` and ``biography`` are defined as blocks in their own right, this could also be written as:
.. code-block:: html+django
{% load wagtailcore_tags wagtailimages_tags %}
{% image value.photo width-400 %}
{% include_block value.first_name %} {% include_block value.surname %}
{% include_block value.biography %}
Writing ``{{ my_block }}`` is roughly equivalent to ``{% include_block my_block %}``, but the short form is more restrictive, as it does not pass variables from the calling template such as ``request`` or ``page``; for this reason, it is recommended that you only use it for simple values that do not render HTML of their own. For example, if our PersonBlock used the template:
.. code-block:: html+django
{% load wagtailimages_tags %}
{% image value.photo width-400 %}
{{ value.first_name }} {{ value.surname }}
{% if request.user.is_authenticated %}
Contact this person
{% endif %}
{{ value.biography }}
{{ block }}
{% endif %}
{% endfor %}
{# Correct: #}
{% for block in page.body %}
{% if block.block_type == 'person' %}
{% include_block block %}
{% endif %}
{% endfor %}
Like Django's ``{% include %}`` tag, ``{% include_block %}`` also allows passing additional variables to the included template, through the syntax ``{% include_block my_block with foo="bar" %}``:
.. code-block:: html+django
{# In page template: #}
{% for block in page.body %}
{% if block.block_type == 'person' %}
{% include_block block with classname="important" %}
{% endif %}
{% endfor %}
{# In PersonBlock template: #}
...
The syntax ``{% include_block my_block with foo="bar" only %}`` is also supported, to specify that no variables from the parent template other than ``foo`` will be passed to the child template.
.. _streamfield_get_context:
As well as passing variables from the parent template, block subclasses can pass additional template variables of their own by overriding the ``get_context`` method:
.. code-block:: python
import datetime
class EventBlock(blocks.StructBlock):
title = blocks.CharBlock(required=True)
date = blocks.DateBlock(required=True)
def get_context(self, value):
context = super(EventBlock, self).get_context(value)
context['is_happening_today'] = (value['date'] == datetime.date.today())
return context
class Meta:
template = 'myapp/blocks/event.html'
In this example, the variable ``is_happening_today`` will be made available within the block template.
BoundBlocks and values
----------------------
All block types, not just StructBlock, accept a ``template`` parameter to determine how they will be rendered on a page. 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, since those built-in types (``str``, ``int`` and so on) cannot be 'taught' about their template rendering. As an example of this, consider the following block definition:
.. code-block:: python
class HeadingBlock(blocks.CharBlock):
class Meta:
template = 'blocks/heading.html'
where ``blocks/heading.html`` consists of:
.. code-block:: html+django
{{ value }}
This gives us a block that behaves as an ordinary text field, but wraps its output in ```` tags whenever it is rendered:
.. code-block:: python
class BlogPage(Page):
body = StreamField([
# ...
('heading', HeadingBlock()),
# ...
])
.. code-block:: html+django
{% load wagtailcore_tags %}
{% for block in page.body %}
{% if block.block_type == 'heading' %}
{% include_block block %} {# This block will output its own ...
tags. #}
{% endif %}
{% endfor %}
This kind of arrangement - a value that supposedly represents a plain text string, but has its own custom HTML representation when output on a template - would normally be a very messy thing to achieve in Python, but it works here because the items you get when iterating over a StreamField are not actually the 'native' values of the blocks. Instead, each item is returned as an instance of ``BoundBlock`` - an object that represents the pairing of a value and its block definition. By keeping track of the block definition, a ``BoundBlock`` always knows which template to render. To get to the underlying value - in this case, the text content of the heading - you would need to access ``block.value``. Indeed, if you were to output ``{% include_block block.value %}`` on the page, you would find that it renders as plain text, without the ```` tags.
(More precisely, the items returned when iterating over a StreamField are instances of a class ``StreamChild``, which provides the ``block_type`` property as well as ``value``.)
Experienced Django developers may find it helpful to compare this to the ``BoundField`` class in Django's forms framework, which represents the pairing of a form field value with its corresponding form field definition, and therefore knows how to render the value as an HTML form field.
Most of the time, you won't need to worry about these internal details; Wagtail will use the template rendering wherever you would expect it to. However, there are certain cases where the illusion isn't quite complete - namely, when accessing children of a ``ListBlock`` or ``StructBlock``. In these cases, there is no ``BoundBlock`` wrapper, and so the item cannot be relied upon to know its own template rendering. For example, consider the following setup, where our ``HeadingBlock`` is a child of a StructBlock:
.. code-block:: python
class EventBlock(blocks.StructBlock):
heading = HeadingBlock()
description = blocks.TextBlock()
# ...
class Meta:
template = 'blocks/event.html'
In ``blocks/event.html``:
.. code-block:: html+django
{% load wagtailcore_tags %}
{% include_block value.heading %}
- {% include_block value.description %}
In this case, ``value.heading`` returns the plain string value rather than a ``BoundBlock``; this is necessary because otherwise the comparison in ``{% if value.heading == 'Party!' %}`` would never succeed. This in turn means that ``{% include_block value.heading %}`` renders as the plain string, without the ```` tags. To get the HTML rendering, you need to explicitly access the ``BoundBlock`` instance through ``value.bound_blocks.heading``:
.. code-block:: html+django
{% load wagtailcore_tags %}
{% include_block value.bound_blocks.heading %}
- {% include_block value.description %}
In practice, it would probably be more natural and readable to make the ```` tag explicit in the EventBlock's template:
.. code-block:: html+django
{% load wagtailcore_tags %}
{{ value.heading }}
- {% include_block value.description %}
This limitation does not apply to StructBlock and StreamBlock values as children of a StructBlock, because Wagtail implements these as complex objects that know their own template rendering, even when not wrapped in a ``BoundBlock``. For example, if a StructBlock is nested in another StructBlock, as in:
.. code-block:: python
class EventBlock(blocks.StructBlock):
heading = HeadingBlock()
description = blocks.TextBlock()
guest_speaker = blocks.StructBlock([
('first_name', blocks.CharBlock()),
('surname', blocks.CharBlock()),
('photo', ImageChooserBlock()),
], template='blocks/speaker.html')
then ``{% include_block value.guest_speaker %}`` within the EventBlock's template will pick up the template rendering from ``blocks/speaker.html`` as intended.
In summary, interactions between BoundBlocks and plain values work according to the following rules:
1. When iterating over the value of a StreamField or StreamBlock (as in ``{% for block in page.body %}``), you will get back a sequence of BoundBlocks.
2. If you have a BoundBlock instance, you can access the plain value as ``block.value``.
3. Accessing a child of a StructBlock (as in ``value.heading``) will return a plain value; to retrieve the BoundBlock instead, use ``value.bound_blocks.heading``.
4. The value of a ListBlock is a plain Python list; iterating over it returns plain child values.
5. StructBlock and StreamBlock values always know how to render their own templates, even if you only have the plain value rather than the BoundBlock.
.. _custom_editing_interfaces_for_structblock:
Custom editing interfaces for ``StructBlock``
---------------------------------------------
To customise the styling of a ``StructBlock`` as it appears in the page editor, you can specify a ``form_classname`` attribute (either as a keyword argument to the ``StructBlock`` constructor, or in a subclass's ``Meta``) to override the default value of ``struct-block``:
.. code-block:: python
class PersonBlock(blocks.StructBlock):
first_name = blocks.CharBlock(required=True)
surname = blocks.CharBlock(required=True)
photo = ImageChooserBlock()
biography = blocks.RichTextBlock()
class Meta:
icon = 'user'
form_classname = 'person-block struct-block'
You can then provide custom CSS for this block, targeted at the specified classname, by using the :ref:`insert_editor_css` hook.
For more extensive customisations that require changes to the HTML markup as well, you can override the ``form_template`` attribute in ``Meta`` to specify your own template path. The following variables are available on this template:
``children``
An ``OrderedDict`` of ``BoundBlock``\s for all of the child blocks making up this ``StructBlock``; typically your template will call ``render_form`` on each of these.
``help_text``
The help text for this block, if specified.
``classname``
The class name passed as ``form_classname`` (defaults to ``struct-block``).
``block_definition``
The ``StructBlock`` instance that defines this block.
``prefix``
The prefix used on form fields for this block instance, guaranteed to be unique across the form.
To add additional variables, you can override the block's ``get_form_context`` method:
.. code-block:: python
class PersonBlock(blocks.StructBlock):
first_name = blocks.CharBlock(required=True)
surname = blocks.CharBlock(required=True)
photo = ImageChooserBlock()
biography = blocks.RichTextBlock()
def get_form_context(self, value, prefix='', errors=None):
context = super(PersonBlock, self).get_form_context(value, prefix=prefix, errors=errors)
context['suggested_first_names'] = ['John', 'Paul', 'George', 'Ringo']
return context
class Meta:
icon = 'user'
form_template = 'myapp/block_forms/person.html'
Custom block types
------------------
If you need to implement a custom UI, or handle a datatype that is not provided by Wagtail's built-in block types (and cannot built up as a structure of existing fields), it is possible to define your own custom block types. For further guidance, refer to the source code of Wagtail's built-in block classes.
For block types that simply wrap an existing Django form field, Wagtail provides an abstract class ``wagtail.wagtailcore.blocks.FieldBlock`` as a helper. Subclasses just need to set a ``field`` property that returns the form field object:
.. code-block:: python
class IPAddressBlock(FieldBlock):
def __init__(self, required=True, help_text=None, **kwargs):
self.field = forms.GenericIPAddressField(required=required, help_text=help_text)
super(IPAddressBlock, self).__init__(**kwargs)
Migrations
----------
StreamField definitions within migrations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
As with any model field in Django, any changes to a model definition that affect a StreamField will result in a migration file that contains a 'frozen' copy of that field definition. Since a StreamField definition is more complex than a typical model field, there is an increased likelihood of definitions from your project being imported into the migration -- which would cause problems later on if those definitions are moved or deleted.
To mitigate this, StructBlock, StreamBlock and ChoiceBlock implement additional logic to ensure that any subclasses of these blocks are deconstructed to plain instances of StructBlock, StreamBlock and ChoiceBlock -- in this way, the migrations avoid having any references to your custom class definitions. This is possible because these block types provide a standard pattern for inheritance, and know how to reconstruct the block definition for any subclass that follows that pattern.
If you subclass any other block class, such as ``FieldBlock``, you will need to either keep that class definition in place for the lifetime of your project, or implement a `custom deconstruct method `__ that expresses your block entirely in terms of classes that are guaranteed to remain in place. Similarly, if you customise a StructBlock, StreamBlock or ChoiceBlock subclass to the point where it can no longer be expressed as an instance of the basic block type -- for example, if you add extra arguments to the constructor -- you will need to provide your own ``deconstruct`` method.
.. _streamfield_migrating_richtext:
Migrating RichTextFields to StreamField
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you change an existing RichTextField to a StreamField, and create and run migrations as normal, the migration will complete with no errors, since both fields use a text column within the database. However, StreamField uses a JSON representation for its data, so the existing text needs to be converted with a data migration in order to become accessible again. For this to work, the StreamField needs to include a RichTextBlock as one of the available block types. The field can then be converted by creating a new migration (``./manage.py makemigrations --empty myapp``) and editing it as follows (in this example, the 'body' field of the ``demo.BlogPage`` model is being converted to a StreamField with a RichTextBlock named ``rich_text``):
.. code-block:: python
# -*- coding: utf-8 -*-
from __future__ import unicode_literals
from django.db import models, migrations
from wagtail.wagtailcore.rich_text import RichText
def convert_to_streamfield(apps, schema_editor):
BlogPage = apps.get_model("demo", "BlogPage")
for page in BlogPage.objects.all():
if page.body.raw_text and not page.body:
page.body = [('rich_text', RichText(page.body.raw_text))]
page.save()
def convert_to_richtext(apps, schema_editor):
BlogPage = apps.get_model("demo", "BlogPage")
for page in BlogPage.objects.all():
if page.body.raw_text is None:
raw_text = ''.join([
child.value.source for child in page.body
if child.block_type == 'rich_text'
])
page.body = raw_text
page.save()
class Migration(migrations.Migration):
dependencies = [
# leave the dependency line from the generated migration intact!
('demo', '0001_initial'),
]
operations = [
migrations.RunPython(
convert_to_streamfield,
convert_to_richtext,
),
]