Templating / Template Specific Fields
Note: You are currently reading the documentation for Bolt 3.7. Looking for the documentation for Bolt 5.2 instead?
Template Specific FieldsΒΆ
The Template Specific Fields (or "TemplateFields" for short) are a feature that helps solve a common challenge you might encounter when developing a site: It's very difficult to create a one size fits all solution for all pages. Many may look quite different to one another. This is why you'd create different templates to suit these different requirements. However, one page may be radically different from the other and even using the same fields between these pages would provide a limitation.
For example, your home page may have many different sections with some complex
markup between them. All of your other pages have a single body
html field,
which really won't suffice. You could create a new ContentType, or use
Resource Contenttypes, but this isn't really an
elegant solution.
To get started with TemplateFields, you need to add a template select field to your ContentType definition:
template:
type: templateselect
filter: '*.twig'
Template specific fields allow you to define extra fields to use when a template
is chosen for a record. They're defined in the theme's theme.yml
, and it's
just like defining the fields of a ContentType.
templatefields:
index.twig: # Our homepage template
section_1_heading:
type: text
section_1_body:
type: html
section_2_heading:
type: text
section_2_body:
type: html
footer_image:
type: image
When you change your template while editing a record, and it has template fields associated with it, you'll be politely notified that you need to save and refresh for these changes to take effect. If this is already the template for a record, this will happen automatically.
Note: TemplateFields are usable with a select
number of field types. Do not use type: date
, type: datetime
,
type: repeater
, type: block
or type: templateselect
as template specific fields. These fields will not work as expected.
To change the name shown for each template in the templateselect
field you can
define the names and their associated ContentTypes in the theme's theme.yml
.
templateselect:
templates:
- name: 'Homepage template'
filename: 'index.twig'
- name: 'Page with gallery'
filename: 'page_with_gallery.twig'
Then you will be able to go to the Template
section of the record editing and change
the content to your heart's desire. Once saved, accessing this data is very simple.
Just go through the templatefields
property of the record.
{{ record.templatefields.section_1 }}
{# This will output whatever is stored in section_1 #}
Warning: The data stored in these fields is only
around while that template is selected. If you change templates with templatefield data
stored, you will lose that data if the templatefields of the new template differ
from those of the current one. Bolt will do its best to warn you when this will happen.
Couldn't find what you were looking for? We are happy to help you in the forum, on Slack or on Github.