Template Settings API

The template settings API is a format for settings that is used by page templates and post types to create post-by-post settings.

This is a reference guide for options and configuration of template settings.

Format

Template settings are used to render a list of settings for users. This is accomplished as an array of settings configuration objects. The general format looks like this:

const myTemplateSettings = [
  {
    _id: "settingId",
    input: "---inputType---",
    label: "Setting Label",
    description: "The setting description",
    _default: "The default value",
    list: ["foo", "bar"],
    settings: [], // sortable input
  },
]

_id is the key that you'll use to refer to the setting in your templates.
label and description are used to add text to the setting
_default is the default value of the setting if it is undefined
list is for providing a standard list of options
input is the type of input to show, discussed below.
settings are nested settings for the sortable list input

Types of Inputs

The template settings are built on the elements available under the form UI. In each setting object, you can select on with the basic key of the input type:

sortable - nested sortable inputs (discussed below)
text - text input
textarea - textarea input
email - email text input
phone - phone number text input
password - password text input
checkbox - checkbox input
birthday - birthday input
date - date input
image-upload - image upload input
select - select input
editor - markdown editor
tags - tags selector

Sortable Lists

Often you'll want to allow users to organize a list of data items. This is the use case for the sortable input that is also discussed in the Form UI doc.

To configure a sortable with template settings, you can use the nested settings property.

You'll also need to add the default in an array format, however the nested settings defaults will be used if no value is set in the parent sortable setting config. Let's take a look:

const myTemplateSettings = [
  {
    _id: "boxes",
    input: "sortable",
    label: "Feature Boxes",
    description: "Some feature boxes",
    _default: [{ __title: "Box 1" }, { __title: "Box 2" }, { __title: "Box 3" }],
    settings: [
      {
        input: "text",
        label: "Heading",
        _id: "heading",
        _default: "Box",
      },
      {
        input: "textarea",
        label: "Description",
        _id: "description",
        _default: "Box Description",
      },
    ],
  },
]

The above creates a sortable with three items (Box 1, 2, 3). In each item you'll have two inputs (heading (text), description(textarea)).

Page Template Components

In page templates you can use template settings to create options for users on a page-by-page basis.

As an example, we'll use the settings above sortable idea to show a list of boxes that a user creates. Full example:

<template>
  <div class="feature-boxes">
    <div v-for="(box, i) in settings.boxes" :key="i" class="box">
      <div class="box-heading">{{ box.heading }}</div>
      <div class="box-description">{{ box.description }}</div>
    </div>
  </div>
</template>

<script>
  import { stored } from "@factor/api"
  export default {
    computed: {
      post() {
        return stored("permalink") || {}
      },
      settings() {
        return this.post.settings || {}
      },
    },
    templateSettings() {
      return [
        {
          _id: "boxes",
          input: "sortable",
          label: "Feature Boxes",
          description: "Some feature boxes",
          _default: [{ __title: "Box 1" }, { __title: "Box 2" }, { __title: "Box 3" }],
          settings: [
            {
              input: "text",
              label: "Heading",
              _id: "heading",
              _default: "Box",
            },
            {
              input: "textarea",
              label: "Description",
              _id: "description",
              _default: "Box Description",
            },
          ],
        },
      ]
    },
  }
</script>

<style lang="less">
  // styles
</style>

Template Settings in Post Types

When you create a post type, you may want to create custom settings for each individual post that is created. An example might be a portfolio where for each "portfolio item" you want to add a URL, dates, logo, etc..

To automatically add these settings you can just register them on the post type with template settings.

import { addPostType } from "@factor/api"

addPostType({
  // ... other options
  templateSettings: [
    {
      input: "url",
      label: "URL",
      _id: "url",
    },
  ],
})

In the default management UI the settings will be rendered for users. When they save them, they'll become available under the post.settings property.

post-19603c73.svg