Docs (Public)

Field Models are nested inside of Content Models and define the individual fields that make up that particular content type. They map to the front matter of a markdown document or to the values in JSON/TOML/YAML data.

A field model describes the name and the type of a field, as well as its presentation and behavior inside the editing interface of the CMS.

Basic Example

Take the following markdown document with 3 front matter fields.

content/posts/my-post.md

---
date = "2014-09-28"
title = Creating a New Theme
banner_image = images/cat.png
---

This is a post about cats.

This document would have the corresponding field models in the stackbit.yaml:

...
models:
  posts: # this is a page model
    type: page
    label: Blog Posts
    folder: posts
    fields: #these are the field models
      - type: string # field model of type: string
        name: title # name maps to the field in the front matter
        label: Title
                required: true
            - type: date # a field model of type: date
                name: date 
                label: Publish Date
            - type: image # field model of type: image
                name: banner_image
                label: Main blog post image

Field Model Schema

Field NameDescriptionNotes
typeRequired
Name of any valid field type (e.g.: string, text, number, list, object)
See available field types in the Field Types table below.
nameRequired
The field key as it should appear in the content
Should contain only alphanumeric characters, underscore and a hyphen [A-Za-z0-9_]. Must start with a letter. Must not end with an underscore or a hyphen.
labelHuman readable label for the field. Defaults to _.startCase(name) (a lodash method).Should be short enough as some CMS's have restrictions on its length. Some CMS require label to be unique.
descriptionShort description to editors how the field is to be used
requiredDefault: false
Indicate if the field should be required
defaultThe default value for this field that will be placed inside the UI editor.This is not a fallback value that will be used if the field is not set or empty. In some CMS this is merely a UI editor feature, meaning that the default value will be set only if it is not hidden. Therefore, this field should not be used for required and hidden fields. In those cases, use const.
constThe constant value that should be set when the object is created.If this type of field is not supported by a specific CMS, its behavior is achieved by using default + required + readOnly, or required + enum options=[value], or any other combination that will ensure that when an object with constant field is created, it will be saved with constant value, and prevent user from setting it to anything else.
hiddenDefault: false
Indicates if the field should be hidden from the editor.
When hiding fields, some CMS might not set a field default value. Therefore, hidden should be used only with const or when the data is created outside of CMS UI (e.g.: API). For example, data that is imported into CMS when the site is created.
readOnlyDefault: false
Indicates if the field should be read only. This property could be used if a field value is not a constant and created outside of CMS UI (e.g.: imported via API).
Not in use yet.
uniqueDefault: false
Indicates if the field value should be unique
Not in use yet.
Not supported in many CMS.
widgetDefines the UI of field control (textfield, textarea, select, checkbox, etc.)Not in use yet
validationsTo be definedNot in use yet.
Currently field validations are based on their types, the required field and enum options.

Field Types

String Field

Short single-line plain text

fields:
  - type: string
    name: title
    label: Title

Text Field

Multi-line plain text field

fields:
  - type: text
    name: description
    label: A short description of the article

Markdown Field

Rich text that should be run through markdownify filter.

fields:
  - type: markdown
    name: description
    label: A short description of the article

Number Field

=Creates a number input field in the CMS. Can be a subtype of int (default) or float. Can be limited by min (minimum allowed value) or max (maximum allowed value). Use step to indicate jump steps.

fields:
  - type: number
    name: age
    label: The employees age
  - type: number
    subtype: float
    name: height
    label: Height

The data represented by these fields would be:

# data
age: 10
height: 175.5

Boolean Field

A boolean true or false

fields:
  - type: boolean
    name: draft
    label: Is this article a draft?

Image Field

The path to image file relative to the folder specified by staticDir property in stackbit.yaml . Creates an image widget in the CMS which typically has extra UI options like cropping, preview etc.

fields:
  - type: image
    name: thumbnail
    label: The thumbnail image for this blog post

File Field

Path to any file, relative to the folder specified by staticDir property in stackbit.yaml . Creates a basic file upload widget in the CMS.

fields:
  - type: file
    name: whitepaper
    label: A Link to the whitepaper PDF file

Datetime Field

A date and time

fields:
  - type: datetime
    name: date
    label: Publish Date
---
title: "My Blog Post"
date: 2017-03-09T14:25:52-05:00
---

Date Field

A date

fields:
  - type: date
    name: date
    label: Publish Date
---
title: "My Blog Post"
date: 2017-03-09
---

Color Field

Color value in Hex format (e.g.: #FF0000)

stackbit.yaml

...
models:
    theme:
    type: data
    label: Theme Config
    file: theme.json
        fields:
          - type: color
            name: primary_color
            label: Primary Theme Color
            - type: color
            name: link_color
            label: Link Color
# theme.json
{
  "primary_color": "#FFCC00",
    "link_color: "#3eb2fd"
}

Enum Field Type

The enum field type requires specifying an options field with list of allowed values. This list can be represented in two ways:

  1. List of strings, each string is one of the allowed values.
  2. List of objects with label and value fields. The value specifies the allowed value and the label specifies the label that will be presented to the user, if the underlying CMS supports that.
fields:
  # enum with list of values
    - type: enum
      name: tag
        label: Tag
        options: [foo, bar, baz]
  # enum with list of objects
    - type: enum
        name: element
        label: Element
        options:
            - label: "Foo!"
                value: foo
            - label: My Bar
                value: bar
            - label: bazzz
                value: baz

ß

Object Field

A nested object. Some CMS's support only a flat model structure. For these CMS's, all Object Fields will be transformed into Object Model Fields and Object Models. Therefore, this type of field should be used only if the nested object is not repeated in another field. Otherwise, Object Model Fields should be used instead to minimize number of models when flattening the model tree.

Fields:

  • fields - list of model fields of the nested object
  • labelField - the name of a field that will be used as title when embedded this field inside a list or in another object.

stackbit.yaml

...
models:
  config:
    type: data
    label: Config
    file: config.toml
    fields:
            - type: object
        name: params
        label: Params
        description: Site parameters
        fields:
          - type: string
            name: google_analytics_id
            label: Google Analytics ID
          - type: string
            name: google_tag_manager_id
            label: Google Tag Manager ID
          - type: object
            name: logo
            label: Params Logo
            fields:
              - type: image
                name: logo
                label: Logo Image
              - type: string
                name: alt
                label: Logo Alt Text

config.toml

...
[params]
  google_analytics_id = ""
  google_tag_manager_id = ""
  [params.logo]
    logo = "images/logo.svg"
    alt = "My Logo"

Object Model Field

A one-to-one reference to an Object Model. This is similar to defining a Reference Type Field referencing a single Object Model. But, unlike Reference Type Field, the data of this field does not require the type property.

stackbit.yaml

# stackbit.yaml
...
models:
  page:
    type: page
    label: Page
    fields:
      - type: string
        name: title
      - type: button # type is "button" which is an "object" model
        name: cta
  button:
    type: object
    label: Button
    labelField: label
    fields:
      - type: string
        name: label
      - type: string
        name: url

page.md

---
title: Page
cta:
  label: Example site
  url: https://www.example.com
---

Reference Field Type

A one-to-many reference to one or more Object Models. Objects referenced by this field must have a type property identifying the name of the model representing that object. A reference field type can be used inside list field. Thus allowing to define list of objects of multiple types.

Fields:

  • models - list of models that can be set for this field

stackbit.yaml

...
models:
  home:
    type: page
    label: Home
    singleInstance: true
    file: index.md
      fields:
      ...
          - type: reference
            name: section
            models: # the "models" array specifes which Object Models can be referenced by this field
          - intro
          - banner
  intro:
    type: object
    label: Intro Section
    fields:
      - type: markdown
        name: intro_text
        label: Intro Text
  banner:
    type: object
    label: Banner Section
    fields:
      - type: image
        name: banner_img
        label: Banner Image

index.md

---
layout: home
title: Home
section:
  type: intro # the "type" field is required, and it specifies the name of the object model representing the object itself
  intro_text: "Welcome *Home*!"
---

In the example above, the section field is a referenced object defined either by intro or by banner Object Models. Each of these objects must have the type field to identify the name of the Object Model. The type field could be also used to create conditions in templates as shown in the following example for a home.html layout file written in Nunjucks:

<h1>{{ page.title }}</h1>

{% if page.section.type == "intro" %}
    {{ page.section.intro_text | markdownify }}
{% elif page.section.type == "banner %}
    <img src="{{ page.section.banner_img | relative_url }}"/>
{% endif %}

The reference type can be also used in lists:

stackbit.yaml

...
models:
  home:
    type: page
    label: Home
    singleInstance: true
    file: index.md
        fields:
      ...
      - type: list
        name: sections
        label: Sections
        items:
          type: reference
          models: [intro, banner]

index.md

---
layout: home
title: Home
sections:
  - type: intro
      intro_text: "Welcome *Home*!"
  - type: banner
    banner_img: "welcome_banner.png"
---

List Field Type

List is used for arrays. A list field type may have an items field where you can define the type of element in the array. By default the type is set to string.

Fields:

  • items - specifies the type and attributes of list items
  • items.type - specifies the type of the list items, default is string.
  • items.* - fields specific to the specified item type:
  • items.labelField for items.type: object
  • items.models for items.type: referenceitem
  • items.options for items.type: enum

The example below defines a simple list of strings

fields:
  - type: string
    name: title
    label: Title
  - type: list
    name: tags
    label: Tags
    items:
      type: string

The data represented by this list in YAML (or front-matter):

---
title: JavaScript
tags:
  - code
  - javascript
  - node
---

The data represented by this list in TOML

title = "Javascript"
tags = ['code','javascript','node']

The date represented by this list in JSON

{
    title: "Javascript",
    tags: ['code','javascript','node']
}

The example below defines an advanced list of nested objects

fields:
  - type: string
    name: title
    label: Title
  - type: list
    name: button
    label: Buttons
    items:
      type: object
      labelField: label  # labelField specifies which field value to use as the list item label
      fields:
        - type: string
          name: url
          label: Button URL
        - type: string
          name: label
          label: Button Label

The data represented by such list might look like this:

---
title: JavaScript
buttons:
  - label: Example Site
    url: https://www.example.com
  - label: Stackbit
    url: https://www.stackbit.com
---

When using nested structures, it is recommended to reuse Object Models to allow model reusability.

Taking the previous example, the button object can be defined as a separate model and used as a list item type while preserving the structure of the represented data:

models:
  model_a:
    ...
        fields:
          - type: string
            name: title
            label: Title
          - type: list
            name: button
            label: Buttons
            items:
              type: button
  button:
    type: object
    label: Button
    labelField: label
    fields:
      - type: string
        name: url
        label: Button URL
      - type: string
        name: label
        label: Button Label

This kind of architecture allow reusing the button model in other models and reduces amount of models created in an API based CMS.

Field Model Naming Conventions

The following rules apply to naming fields:

  • Field names can only contain alphanumeric characters, hyphens - or underscores _
  • Field name must start with a letter
  • Field names must not start or end with a hyphen - or an underscore _

Copy of field types