# Metafields

Metafields are powerful components that can be added to Objects and Object Types. Metafields added to Object Types will be default for all new Objects in the type.

# Model

Parameter Required Type Description
type required Enum text, textarea, html-textarea, select-dropdown, object, objects, file, date, radio-buttons, check-boxes, repeater, parent, markdown, json, switch, number
title required String Your Metafield title
key required String Unique identifier for your Metafield
value varies Varies by type Metafield value. Property required to be present (empty string ok) except for repeater and parent (should not be present). See example model below for various value types and requirements.
required Bool A value is required
regex String Restrict the value to match a regular expresssion
regex_message String The message displayed when the value fails the regex
minlength Number Add minlength to text or textarea Metafields
maxlength Number Add maxlength to text or textarea Metafields
options Required for options, radio, checkbox and switch Varies by type Array of options for select, radio, and checkbox Metafields and string for switch Metafield with possible values true,false and yes,no
children Array Add nested Metafields

Example Metafields

{
  "metafields": [
    {
      "type": "text",
      "title": "Headline",
      "key": "headline",
      "value": "3030 Palo Alto Blvd.",
      "required": true
    },
    {
      "type": "textarea",
      "title": "Basic Text",
      "key": "basic_text",
      "value": "This home is a must see!",
      "required": true
    },
    {
      "type": "html-textarea",
      "title": "Extended Text",
      "key": "extended_text",
      "value": "<p>Some <strong>HTML content</strong> for <em>dramatic</em> effect!</p>"
    },
    {
      "type": "markdown",
      "title": "Markdown Text",
      "key": "markdown_text",
      "value": "# Hello World!"
    },
    {
      "type": "select-dropdown",
      "title": "State",
      "key": "state",
      "value": "California",
      "options": [
        {
          "key": "CA",
          "value": "California"
        },
        {
          "key": "TX",
          "value": "Texas"
        }
      ]
    },
    {
      "type": "object",
      "title": "Pages",
      "key": "pages",
      "object_type": "pages",
      "value": "5a4806974fa85fc8a7000002" // Object ID
    },
    {
      "type": "objects",
      "title": "Other Listings",
      "key": "other_listings",
      "object_type": "listings",
      "value": "5a4806974fa85fc8a7000007,5a4806974fa85fc8a7000008" // Comma-separated Object IDs
    },
    {
      "type": "file",
      "title": "Hero",
      "key": "hero",
      "value": "media-name-property-in-bucket.jpg" // This is the name of your media. Gets converted to url and imgix_url automatically
    },
    {
      "type": "date",
      "title": "Listing Start Date",
      "key": "listing_start_date",
      "value": "2020-10-15"
    },
    {
      "type": "json",
      "title": "JSON Data",
      "key": "json_data",
      "value": {
        "strings": "cheese",
        "arrays": ["Bradbury","Charles","Ramono","the last Jedi","Liotta"],
        "objects": {
          "bools": true,
          "nestable": true
        }
      }
    },
    {
      "type": "radio-buttons",
      "title": "Deposit Required",
      "key": "deposit_required",
      "value": "The Other",
      "options": [
        {
          "value": "This"
        },
        {
          "value": "That"
        },
        {
          "value": "The Other"
        }
      ]
    },
    {
      "type": "check-boxes",
      "title": "Amenities",
      "key": "amenities",
      "value": [
        "Pool",
        "Gym"
      ],
      "options": [
        {
          "value": "Pool"
        },
        {
          "value": "Gym"
        },
        {
          "value": "Landscaping"
        }
      ]
    },
    {
      "type": "switch",
      "title": "This is great",
      "key": "this_is_great",
      "value": true,
      "options": "true,false"
    },
     {
      "type": "parent",  // ! No value !
      "title": "Call Out Section",
      "key": "call_out_section",
      "children": [
        {
          "type": "text",
          "title": "Headline",
          "key": "headline",
          "value": "You're Going to Love it Here!"
        },
        {
          "type": "html-textarea",
          "title": "Section Content",
          "key": "section_content",
          "value": "<p>You are going to <strong>love</strong> it in Cosmic Village. The best place to raise a team!</p>"
        },
        {
          "type": "file",
          "title": "Hero",
          "key": "hero",
          "value": "big-beautiful-image.jpg"
        }
      ]
    },
    {
      "type": "repeater", // ! No value !
      "title": "Testimonials",
      "key": "testimonials",
      "repeater_fields": [
        {
          "title": "Name",
          "key": "name",
          "value": "",
          "type": "text",
          "required": false
        },
        {
          "title": "Quote",
          "key": "quote",
          "value": "",
          "type": "text",
          "required": false
        }
      ],
      "children": [
        {
          "type": "repeating_item",
          "children": [
            {
              "type": "text",
              "title": "Name",
              "key": "name",
              "value": "Fiona Apple"
            },
            {
              "type": "text",
              "title": "Name",
              "key": "name",
              "value": "Jon Brion"
            }
          ]
        }
      ]
    }
  ]
}

# Validation

You can use optional validation parameters to make sure editors using the Web Dashboard enter the correct values.

Reference the Metafield model to learn more.

Parameter Required Type Description
required Bool A value is required
regex String Restrict the value to match a regular expresssion
regex_message String The message displayed when the value fails the regex
minlength Number Add minlength to text or textarea Metafields
maxlength Number Add maxlength to text or textarea Metafields

Example Metafields with Validations

{
  "title": "Users",
  "singular": "User",
  "slug": "users",
  "metafields": [
    {
      "key": "first_name",
      "title": "First Name",
      "type": "text",
      "value": "",
      "required": true,
      "minlength": 2
    },
    {
      "key": "last_name",
      "title": "Last Name",
      "type": "text",
      "value": "",
      "required": true,
      "minlength": 2
    },
    {
      "key": "email",
      "title": "Email",
      "type": "text",
      "value": "",
      "regex": "/^([a-z0-9_.-]+)@([da-z.-]+).([a-z.]{2,6})$/",
      "regex_message": "You must enter a valid email."
    },
    {
      "key": "avatar",
      "title": "Avatar",
      "type": "file",
      "value": ""
    },
    {
      "key": "tagline",
      "title": "Tagline",
      "type": "text",
      "value": "",
      "maxlength": 50
    }
  ]
}

# Connect Objects

You can connect Objects to create "one to many" and "many to many" relationships between Objects using Single and Multiple Object Metafields.

    # Single Objects

    For a Single Object Metafield, add the Object ID (_id) to the value to connect the Object. The full Object will be returned on the Metadata response in the object property.

    # Multiple Objects

    For Multiple Object type Metafields, you can add the Object IDs as comma-separated values. The full Objects will be returned on the Metadata response in the objects property.

    Parameter Required Type Description
    type required Enum object, objects
    title required String Your Metafield title
    key required String Unique identifier for your Metafield
    object_type required String Object Type slug
    value String For single Object this is the _id property. For multiple Objects it is comma-separated _ids.

    # Edit Metafields

    You can edit an existing Object's Metafields by using the following method. This method allows you to edit specific Metafields identified by key, without affecting other Metafields.

    Parameter Required Type Description
    slug String Object Slug
    metafields Array Array of new or existing Metafields to add or edit. Required properties are { type, key, title }