Field Types / Block field
Note: You are currently reading the documentation for Bolt 3.7. Looking for the documentation for Bolt 5.2 instead?
The block
field allows you to insert a number of blocks of fields in a record.
You can give each of these blocks a name and define the fields that it has. The
Editor can then insert these in the Record as needed. As such, these fields are
sometimes refered to as "Named Repeaters".
Basic Configuration:¶
The configuration of a Block field consists of a few parts:
- The 'key', used to identify the entirety of the block.
type: block
to define it as a block type.- Other optional values, like in other field types (like 'label' or 'group').
- A
fields
key, that contains one or more block sections. - Each section has a required label, and again a
fields
key. - Under these
fields
, there can be one or more common fields liketext
,image
,html
andselect
.
A straighforward example can look like this:
contentblocks:
type: block
label: Content Blocks
group: Blocks
fields:
imagesection:
label: Image with description
fields:
heading:
type: text
image:
type: image
description:
type: html
height: 70px
textsection:
label: Paragraph
fields:
heading:
type: text
content:
type: html
height: 100px
As you can see the field is configured with a type of block
and then the
sections of sub-fields are configured under the fields
attribute. In general
you can include any valid fields within a repeater, there are a few that are not
supported.
Note: Blocks are useable with most of the
available field types, except for a few where it would get too complex, or where
it simply does not make sense to have more than one of. In short, do
not use type: slug
, type: block
,
type: repeater
or type: templateselect
as fields in
your block. These fields will not work as expected.
You can drag-and-sort blocks, but don't forget to save your record after sorting them.
If your block has one or more sub-fields with type: text
, the first one will be
used as the header of each individual block set. This is particularly useful when you
need to sort your block sets and collapse them all prior to sorting them. If there
is no type: text
field defined, the header falls back to the block's label.
Example usage in templates:¶
When you want to use blocks in your templates you will need to iterate over a set before you can access the individual sections of fields.
The approach you use may vary slightly on whether you know the names of the fields within each set or if you want to allow your template to iterate over all the sub-fields without necessarily knowing the field names.
For instance if you just want to iterate over all sections and then all fields within the set then the template code will look like this:
{% for group in record.contentblocks %}
{% for field in group %}
{{ field.fieldtype }}:
{{ field }}
{% endfor %}
{% endfor %}
In the example above using {{ field }}
will just output the value of the
sub-field, if it is a text field such as like text
, html
, textarea
or
markdown
. Since these are sometimes more complex fields you can use
{{ field|showimage }}
for images or {{ dump(field.value) }}
to dump the
value regardless of type. In practice, you'll often want to use the techniques
described in the section below for individual fields to output the specific type
of field in the layout you require.
If you know the names of the fields you want to render then you can fetch a
field from each block by name. For instance using the same example as above but
knowing that our block set comprises the individual sections imagesection
and
textsection
with each fields we can output the fields like this:
{% for group in record.contentblocks %}
{% if group.block == 'textsection' %}
<h2>{{ group.heading }}</h2>
{{ group.content }}
{% endif %}
{% if group.block == 'imagesection' %}
<h2>{{ group.heading }}</h2>
{{ group.image|showimage() }}
{{ group.description }}
{% endif %}
<hr>
{% endfor %}
Images and thumbnails¶
You can use the image- and thumbnail filters for images inside a block
contenttype, but the notation is slightly different. For example, if we have a
contenttype with a sections
repeater, acces them like this:
{% for section in record.sections %}
<img src="{{ section.repeatimage|image(1200, 800, "r") }}"
alt="{{ section.repeatimage.title }}">
{% endfor %}
Options¶
The field has one specific option:
collapsible
: Whether the separate sets of this Block are collapsible in the backend. This allows the editor to get a better overview, if there are multiple sets. The default istrue
, you can set it tofalse
to disable this feature.icon
: Allows you to add a FontAwesome icon to the header of a block set to identify it more easily. Example:icon: "fa:bolt"
.group
: Adds a separator with a label in the 'Add New...' dropdown. Example:group: Media
.
Couldn't find what you were looking for? We are happy to help you in the forum, on Slack or on Github.