Fields and Types × Mattrbld

At the heart of every Schema in Mattrbld are its Fields. They dictate what widget will be rendered when Content with that Schema assigned to it is being edited, what is valid content and what is not and what options Content Editors have when managing content. In this article you’ll gain an overview about how fields are structured and what types they have, before you can go ahead and learn about each default field type in more detail.

Structure

All fields in Mattrbld implement the same interface, so no matter what field type they are, they all follow the same structure:

{
  "type": String,
  "customField": String,
  "default": Any,
  "description": String,
  "displayField": String,
  "group": String,
  "icon": String,
  "key": String,
  "label": String,
  "localised": Boolean,
  "options": [
    {
      "component": String,
      "key": String,
      "label": String,
      "props": Object,
      "slot": String,
      "value": Any,
    }, …
  ],
  "tab": String,
  "validation": {
    "enforceMinMax": Boolean,
    "max": Number,
    "min": Number,
    "regex": String,
    "regexError": String,
    "required": Boolean,
    "unit": String,
    "isString": Boolean
  },
  "value": [Array, null],
  "version": Number,
  "visibility": {
    "hidden": Boolean,
    "limitToRoles": Array,
    "showByValue": {
      "comparator": [String, Number],
      "field": String,
      "value": Any
    }
  },
  "visualOnly": Boolean
}

Depending on each field type, some of the properties above can be left out for convenience, but there are some required properties that have to have a value as you’ll see in the explanation of each property below:

type (required) is the unique type of this field used to identify and distinguish it from others
customField is the path of the field in the .mattrbld/custom-fields/ directory, linking that specific clone of the field to its original. Since default fields aren’t custom fields, they don’t have this property
default describes the default content of the field if it’s not set to null or undefined
description is the description of the field shown when it’s shown in the list of available fields of the Schema Editor
displayField is a key of another field. If the field supports being displayed in a compact manner, the value of the field with the provided field will be shown as a preview. If this property is null or undefined the preview value is picked from the first field with a displayable value. You can learn more about this in the article on Field Group fields
group is the category under which the field will be displayed in the list of available fields of the Schema Editor
icon is the name of the icon to assign to this field
key (required) is the key of the property the value of this field should be assigned to in the content item. You’ll find more information about this below
label (required) is the human-readable label to display to Content Editors so they know what the field represents, since keys may only make sense to developers or technologically versed users
localised denotes whether or not this field should make use of Mattrbld’s multi-language features.
options houses the various options of this particular field. The array is used to dynamically create widgets to modify these options when editing the field in the Schema Editor, the actual Schema will only contain an object mapping keys to values
- component is the name of the component to render
- key is the key of the option, since options are stored as key:value pairs
- label is the label for the option,
- props is an object of props that are passed to the component
- slot is a string that will be passed to the default slot of the component if supported
- value is the actual value of the option and can be used to set a default
tab is the tab the field should be shown in. If it’s null or undefined the field will be shown in the first tab of the Schema
validation holds the validation information of the field, for more information check out the article on validation
value is either null or an array of nested fields. If set to an empty array, the Schema Editor will show a dropzone for this field
version is the current version of this field
visibility holds visibility information about this field
- hidden will hide the field from anyone in the Content Editor, but still add its value under the specified key. You can use this to add default content to your Schemas that shouldn’t be edited by also providing a default value
- limitToRoles will limit the visibility of this field to the roles specified in the array. If null or undefined the field will be visible to everyone with access to the Collection
- showByValue can be used to conditionally show this field based on the value of another field. You can learn more about it below
  - comparator is the value that should be used to compare to
  - field is the key path of the field the value of which should be compared to the value
  - value is either a string, null, true or false. If it is a string, it has to be one of ‘matches’, ‘equals’, ‘smaller’, or ‘greater’ which will determine how the value of the field and the comparator will be compared
visualOnly marks this field as purely visual, meaning that it won’t be showing in the content. This is intended for fields like the Separator and Heading fields which are only used to show additional information to Content Editors. If this option is set to true, the field’s key will not be editable, since it has no impact on the content. Because of this, the visualOnly default fields all have a key prefixed with ___mb_visual_ to avoid collisions with any keys you may define

Field Keys

The key property of a field is crucial since it determines where Mattrbld will store the value of that field in the content. Consider the following Schema (simplified for legibility):

{
  "fields": [
    {
      "type": "text",
      "key": "title"
    }
  ]
}

This instructs Mattrbld to save the value of the text field under a key of “title” in the content structure, resulting in the following output:

{
  "title": "value of the text input"
}

As such, if you had a blog post with a title, some content and a publishing date, you’d have to make sure to give the fields in your Schema meaningful keys that can map to that data structure.

If we roll with the example of that blog post, you’d likely expect the file to look something like this:

---
title: Hello World
published: 2021-06-23
---

# Hello World!

This is the **Markdown** content of the post.

So you’d define your Schema as follows (details omitted for legibility):

{
  "fields": [
    {
      "type": "text",
      "key": "title"
    },
    {
      "type": "date",
      "key": "published"
    },
    {
      "type": "rich text",
      "key": "content",
      "options": {
        "outputFormat": "markdown"
      }
    }
  ]
}

Note how the key “content” does not show in the frontmatter of the blog post. That is because it is a special key.

Special Keys

There are certain key names that have special meaning in Mattrbld if they are placed at the top-level of the Schema. Currently, there is only one:

content is used in Markdown files to write the value of that field into the body-part of the file instead of the frontmatter. In other files, this key behaves like any other

Reserved Keys

You may use any valid JavaScript string as a key for your fields, so long as you avoid the following:

Keys containing period (.) characters, for example foo.bar
Keys starting with ___mb_ (three leading underscores), as those are reserved for internal functionality
The reserved keys ___toplevel and___addIndicator (three leading underscores), as these are also used internally

You should also make sure that keys on the same level, i.e. not nested within other fields, are unique, otherwise two fields will refer to the same value in the content item. Unless that’s what you want to achieve, of course.

Showing Fields Conditionally

The showByValue property in the visibility options for a field can be used to only show that field if another field has a specific value. This can be useful if you would like to toggle the visibility of certain options based on the value of a dropdown or toggle for example.

The easiest way to define these rules is by doing so in the Schema Editor, but if you would like to write them by hand for some reason, here’s how they work.

When determining whether or not a field with the showByValue option should be visible, Mattrbld will first look up the value of the field with the key-path defined under field in the content item currently being edited. Nested fields can be targeted by using keys joined by periods (.). For example to get a field with the key “field” nested within the field with the key “child” within the field with the key “parent”, you’d use the following key-path: parent.child.field.

After the value was fetched from the content, Mattrbld will check if the value of the value option is not a string. If that is the case, it will do a strict equality check to determine if the fetched value equals the passed value. If it matches, the field will be visible, if it doesn’t it will not.

If the value option is a string, Mattrbld will react differently depending on what that string is:

If it’s “matches”, Mattrbld will turn the passed comparator option into a regular expression and check if the value fetched from the content matches that regular expression
If it’s “equals”, Mattrbld will perform a strict equality test between the value fetched from content and the passed comparator
If it’s “smaller” or “greater”, Mattrbld will check if the value fetched from content is smaller or greater than the passed comparator respectively

For example to show a field based on whether the value of the field “test” matches the regular expression /[0-9]+/ you’d write its showByValue visibility option as follows:

{
  "comparator": "/[0-9]+/",
  "field": "test",
  "value": "matches"
}

If instead you wanted to show it if the field “toggle” was false you’d write it as follows:

{
  "comparator": null,
  "field": "toggle",
  "value": false
}

Types

Mattrbld is able to handle all primitive JavaScript types that can be serialised to JSON:

Strings
Numbers
Booleans
Arrays
Objects

Dates are stored as either UNIX-timestamps or ISO-formatted dates depending on the respective option in Date and Time fields. Similarly, rich text is stored as either HTML or Markdown, depending on the field’s options.

Of course, an array can be anything from a list of tags to a set of objects and even something as seemingly simple as a string might be one of a set of limited options, a string of characters with no newlines allowed or the value of a dropdown field. That’s why the default fields of Mattrbld cover a wide range of different types that may look the same to a computer, but are very different to a human.