Open navClose nav

Front Matter Templates

Disclaimer

This guide assumes you already have an understanding of Front Matter and how it works with Forestry. If this isn’t the case, you can read up on it in the Front Matter doc.

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.

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

Managing FMTs

FMTs can be creating using the CMS, or by creating Config Files.

FMTs can only be accessed in the CMS by team members with the Developer or Site Owner role.

Creating an FMT

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.

Creating an FMT from Existing Pages

https://res.cloudinary.com/forestry-demo/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 an FMT from an an existing page, navigate to the page you wish to use as the basis for your FMT. Next, click the “…” button in the toolbar, then click Create Template.

https://res.cloudinary.com/forestry-demo/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-demo/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 page by navigating to the Front Matter page and clicking Add Template. Then, select Create based on existing document from the modal that appears.

Creating an FMT 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-demo/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 FMT, 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 FMTs

To edit an FMT, navigate to the Front Matter page in the CMS, and click the FMT 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 FMT.

The Field Listing

https://res.cloudinary.com/forestry-demo/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-demo/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-demo/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.

Field defaults are only applied when creating new pages and aren’t intended to be used as a fallback value 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 FMT editing screen.

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

Display Field

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

https://res.cloudinary.com/forestry-demo/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 FMT? Fear not! All changes to FMTs are committed to your Git repository, and can easily be reversed by a developer!


Applying FMTs 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-demo/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 FMT to and click the Settings button, and then select Change Template.

https://res.cloudinary.com/forestry-demo/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 FMT you wish to apply to the page from the dropdown, and then click Change.

Applying to Content Types

FMTs can be applied to all pages in a content type using the settings.yml config file. See the Config Files documentation for more information.

Applying an FMT to a content type will apply the FMT to any page without an FMT already applied to it. It will also make that FMT the default option when creating new pages.


Last updated on April 18, 2019