Fields - Documentation

Fields define the individual fields that make up that particular content model. They map to the front matter of a markdown document or to the values in JSON/TOML/YAML data.

A field 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 fields in the stackbit.yaml:

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

Field Schema

Field Name	Description	Notes
`type`	Required Name of any valid field type (e.g.: string, text, number, list, object)	See available field types in the #field_types table below.
`name`	Required 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.
`label`	Human readable label for the field. Defaults to _.startCase(name) (a https://lodash.com/docs/4.17.15#startCase).	Should be short enough as some CMS's have restrictions on its length. Some CMS require label to be unique.
`description`	Short description to editors how the field is to be used
`required`	Default: false Indicate if the field should be required
`default`	The 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.
`const`	The 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.
`hidden`	Default: 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.
`readOnly`	Default: 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.
`unique`	Default: false Indicates if the field value should be unique	Not in use yet. Not supported in many CMS.
`widget`	Defines the UI of field control (textfield, textarea, select, checkbox, etc.)	Not in use yet
`validations`	To be defined	Not 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

Data:

---
title: Lorem Ipsum
---

Slug Field

Field representing the URL slug

fields:
  - type: slug
    name: slug
    label: Slug

Data:

---
slug: blog/lorem-ipsum
---

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:

---
age: 10
height: 175.5
---

Boolean Field

A boolean true or false

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

Data:

---
draft: true
---

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

Data:

---
title: "My Blog Post"
date: 2017-03-09T14:25:52-05:00
---

Date Field

A date

fields:
  - type: date
    name: date
    label: Publish Date

Data:

---
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

Data:

{
  "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:

List of strings, each string is one of the allowed values.
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

Data:

---
tag: foo
element: bar
---

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"

Model Field

Fields of model type can be used to store nested objects. The advantage of model field over the object field is that model field is defined in a separate model, allowing reusing that model, while the object field is defined within the field preventing it from being reused. Additionally, the model field can store objects of several types, while the object field can only store a single type of object.

Objects referenced by the model field, must have the type field (or any other field name specified by the objectTypeKey) holding the value of the object's model name. This is required to identify the name of the model representing the object. The type field can be omitted if the model field can have an objects of a single type.

Fields:

models - list of models that can be set for this field. All models must be of object type - type: object

Example

For example, assume a schema with a page model that has a link field that referencing an object of the link_model model:

stackbit.yaml

# stackbit.yaml
...
models:
  page:
    type: page
    label: Page
    layout: page
    fields:
      # the "link" field can only reference objects of "link_model" type
      - type: model
        name: link
        models: [link_model]
  link_model:
    type: object
    label: Link
    labelField: label
    fields:
      - type: string
        name: label
      - type: string
        name: url

page.md

---
layout: "page"
link:
  # the "type" is optional if the field can reference an object
  # of a specific model, e.g.: "link_model" only
  # type: link_model
  label: "About"
  url: "/about"
---

Hello World

Now, lets create another link_or_button field that could reference objects of link_model or button_model model types:

stackbit.yaml:

models:
  page:
    type: page
    label: Page
    layout: page
    fields:
      # the "link_or_button" field can reference objects
      # of "link_model" or "button_model" types
      - type: model
        name: link_or_button
        models: [link_model, button_model]
  link_model:
    ...
  button_model:
    type: object
    label: Button
    fields:
      - type: string
        name: label
      - type: string
        name: action
      - type: enum
        name: style
        options: [default, primary, secondary]

Now, because the link_or_button field can reference objects of different types, the referenced object must have the type field to allow validating and type-checking of its fields agains the schema. This type field could also be used in site template logic to execute different code paths.

index.md:

---
layout: "page"
link:
  label: "About"
  url: "/about"
# The "link_or_button" field must specify the "type" field to
# indicate which kind of object it references.
link_or_button:
  type: "link_model"
  label: "Try Now"
  url: "/try"
---

List Example

The model field type can also be used inside list fields.

models:
  page:
    type: page
    label: Page
    layout: page
    fields:
      - type: list
        name: sections
        items:
          type: model
          models: [hero_section, features_section, faq_section]
  hero_section:
    type: object
    label: Hero Section
    fields:
      - type: markdown
        name: intro_text
        label: Intro Text
  features_section:
    type: object
    label: Features Section
    fields:
      ...
  faq_section:
    type: object
    label: FAQ Section
    fields:
      ...

index.md

---
layout: home
title: Home
sections:
  - type: hero_section
    title: ...
  - type: features_section
    features: ...
  - type: faq_section
    questions: ...
---

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 == "hero_section" %}
  {{ page.section.intro_text | markdownify }}
{% elif page.section.type == "features_section %}
  ...
{% elif page.section.type == "faq_section %}
  ...
{% endif %}

Reference Field

Fields of reference type can be used to store objects by reference. The difference between the reference and the model fields is that reference field stores the object's location (for file-based CMS) or object's ID (for API-based CMS), while the model fields store the object as the field value. The reference fields are very useful when the same data needs to be referenced from multiple places.

Objects referenced by this field must have a type property identifying the name of the model representing that object.

Fields:

models - list of models that can be set for this field. All models must be of data type - type: data

Example

stackbit.yaml

dataDir: data
models:
  post:
    type: page
    label: Post
    folder: blog
    layout: post
    urlPath: blog/{slug}
    labelField: title
    fields:
      - type: string
        name: title
        required: true
      - type: slug
        name: slug
        required: true
      - type: reference
        name: author
        models: [author]
  person:
    # type: data specifies that objects defined by this model are global,
    # and can be referenced by fields of type "reference". These objects
    # are referenced by their object ID in API-based CMS,
    # or by a file path in Git-based CMS.
    type: data
    label: Author
    folder: authors
    fields:
      - type: string
        name: first_name
        label: Author's first name
      - type: string
        name: last_name
        label: Author's last name
      - type: string
        name: bio

├── data
│   ├── config.json
│   └── authors
│       ├── bob.json
│       └── alice.json

Like with the model field, objects referenced by reference field type, must define the type field (or any other field name specified by the objectTypeKey) to indicate the object's model name.

// data/authors/bob.json
{
  "type": "author",
  "first_name": "John",
  "last_name": "Doe",
  "bio": "John Doe says Hello World"
}

In Git-based CMS, the value of the reference field will be the path to the data file:

# content/posts/hello.md
---
title: Hello
slug: hello
author: data/authors/bob.json
layout: post
---

In the example above, the author field is a referenced object represented by the person model of type data. The type of the referenced objects identified by the type field.

List Example

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: featured_products
        label: Featured Products
        items:
          type: reference
          models:
            - product_flower
            - product_tree

# data/products/rose.yaml
type: product_flower
name: Rose

# data/products/tulip.yaml
type: product_flower
name: Tulip

# data/products/lemon.yaml
type: product_tree
name: Lemon tree

index.md

---
layout: home
title: Home
featured_products:
  - data/products/rose.yaml
  - data/products/tulip.yaml
  - data/products/lemon.yaml
---

List Field Type

List field is used to represent lists of items of the same type. A list field type may have an items field where you can define the type of items 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: model and items.type: reference
- items.options for items.type: enum

Examples:

List of strings

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']
}

List of enums

fields:
  - type: list
    name: categories
    label: Categories
    items:
      type: enum
      options:
        - tech
        - art
        - announcements

Data:

---
categories:
  - tech
  - art
---

List of objects

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
---

List of models

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: model
          models: [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 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 _

Ready to get started?

Try Stackbit Now