Open navClose nav

Front Matter Templates

Disclaimer

Read first about Front Matter and how it works with Forestry.

What are Front Matter Templates?

Front Matter Templates (FMTs) enable developers to fully customize the interface of the Markdown and HTML editors. You can think of them as the content model for your front matter and also for your data files.

Front Matter Templates work by allowing developers to define which Fields are available to editors when editing pages, content types or data files.

Managing templates

You can create content templates right from within the CMS, or through YAML in Forestry config Files.

Editors don’t have access to the templates user interface in Forestry, you need to be developer, admin or site owner. See roles

Creating a front matter template

FMTs can be created from scratch, or can be created using the fields from an existing page that doesn’t have an FMT applied to it.

From an existing document

https://res.cloudinary.com/forestry-io/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2019/04/create-fmt-from-page.png

To create a front matter template from an an existing document, navigate to the document you wish to use as the basis for your template. Next, click on the options menu “…” button in the toolbar, then click Create Template.

https://res.cloudinary.com/forestry-io/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2019/04/create-fmt-from-page-modal.png

In the modal that opens, enter a name for the template and click Create Template. This will create the new template and redirect you to the Front Matter Template editor.

https://res.cloudinary.com/forestry-io/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2019/04/create-fmt-from-document.png

Alternatively, you can create a Front Matter Template from an existing document by navigating to the Front Matter page and clicking Add Template. Then, select Create based on existing document from the modal that appears.

Creating a front matter template from scratch

To create a Front Matter Template from scratch, navigate to the Front Matter page, and click Add Template. From here, select Create new blank template.

https://res.cloudinary.com/forestry-io/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2019/04/add-blank-fmt.png

Enter a name for your new template, and then select the layout you want to use.

  • Select Fields and big content area if your pages will contain Front Matter combined with markdown content. This is what you’ll want to use most of the time.
  • Select Fields if your pages will be composed exclusively of Front Matter (such as if you are building a page using Blocks, or using this template for non-markdown data such as JSON or YAML files) and you don’t want a markdown editor for your pages.

Click Create Template to begin adding fields.

Editing a front matter template

To edit a template, click on the Front Matter section in the CMS sidebar, and click the template you wish to edit from the list. This will take you to the editing screen, where you will see a list of all of the fields in the template.

The Field Listing

https://res.cloudinary.com/forestry-io/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2019/04/fmt-field-listing.png
Field listing example

The field listing shows you all of the fields configured for the selected FMT. Click Add Field to add a new field to the FMT. New fields are placed at the end of the listing.

You can insert a new field at a different position in the field listing by placing the cursor in between two fields and clicking the Add Field button that appears. To reorder fields, click on the drag handle (see below) and drag the field to the desired position.

Field Listing Legend

https://res.cloudinary.com/forestry-io/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2019/04/fmt-field-card-annotated.png
Breakdown of a field in the field listing
  1. Drag handle. Click and drag this to reorder the field in the listing.
  2. Field Label
  3. Visibility Indicator. This icon appears if the field is configured to be hidden from the page editor.
  4. Field Type
  5. Field Settings. Click this to edit the settings for the field.
  6. Delete Field

field card: drag handle, field label, hidden, type, settings, delete

Adding and Editing Fields

https://res.cloudinary.com/forestry-io/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2019/04/fmt-fields.png
FMT Field Grid

After clicking the Add Field button, you will be presented with a grid of field options. For details on the different available fields, refer to the field documentation.

Once you’ve selected the field you want, click the Add Field button at the bottom of the modal to proceed to the field settings.

Once a field has been added to the field listing, click the gear icon to access the field settings if you want to change them.

Field Settings

The field settings modal is how you will configure your front matter field. Field settings are broken out into multiple tabs. All fields have at least three tabs:

  • General — Essential field information common to all field types.
    • Label: the human-friendly label shown above the input field in the editor.
    • Name: the key stored in your content’s front matter. It is used to access this field in your templates.
    • Description: (Optional) a human friendly description of what the field does and/or instructions for your editors.
    • Hidden: When activated, this field will not be displayed when editing a document that uses this FMT.
  • Validation — settings to enforce specific rules for data input with this field.
    • Required: Whether or not the user must supply a value for this field.
  • Default — supply a default value for this field.
  • Visibility — define a field visibility in the CMS based on the status of a toggle or a select field used in the same template.
Field defaults are only applied when creating new pages and aren’t intended to be used as a fallback values for when no value is provided. For this, see How do I set fallback/hidden values for Front Matter?
Hidden fields can be used to set default values when creating new pages for fields that shouldn’t be modified by an editor. Check out our post on 3 tips for mastering blocks for some examples.

Some field types will have additional validation options, and additional tabs to configure different aspects of the field. Refer to the documentation for specific fields for more information.

Template Settings

To access template-wide settings, click the gear icon in the top right corner of the template editing screen.

From here, you can change the name of the template, switch the layout, set the Display Field., or delete the template,

Display Field

After you’ve added some fields to your template, you can assign one field to act as the Display Field. This field is used when displaying the document in the section listing, and is also used in the list of blocks created with a Blocks field type.

https://res.cloudinary.com/forestry-io/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2018/08/block_labels.png
Example of a block listing
Accidentally removed a field from your template? Fear not! All changes to FMTs are committed to your Git repository, and can easily be reversed by a developer!

Apply a Template to Content

FMTs can be applied to individual pages or to content types.

FMTs follow a “no-modification” rule. When applying an FMT to content, Forestry will not modify any existing values, and it will not remove values that are not part of the FMT.

Applying to Pages

https://res.cloudinary.com/forestry-io/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2019/04/change-fmt.png

To apply an FMT to an individual page, navigate to the page you want to apply the template to and click the Settings button, and then select Change Template.

https://res.cloudinary.com/forestry-io/image/fetch/c_limit,dpr_auto,f_auto,q_80,w_640/https://forestry.io/uploads/2019/04/change-fmt-modal.png

In the modal that opens, select the template you wish to apply to the page from the dropdown, and then click Change.

Applying to Sections

Templates can be applied to all pages in a section by editing the section settings and pickup the corresponding templates to assign or by using the settings.yml configuration file

Applying a template to a section will apply the template to any page without a template already applied to it. It will also use the template as a default option when creating a new document in this section.

Last updated on April 18, 2019