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.