Recent searches

in
Developer ReferenceConfiguration File

Snippet

On this page

This key defines a snippet configuration.

Appears in

├── _snippets
│   └── Snippet
├── Snippet
│   └── alternate_formats
│       └── Snippet
└── _snippets_templates
    └── Snippet

Type

Object

Properties

alternate_formats — Array<Snippet>#

This key defines alternate configurations for this snippet.

Appears in: Snippet.

definitions — Object<unknown>#

This key defines the variables required for the selected template.

Appears in: Snippet.

Show examplesHide examples

In this example, we have configured snippet definitions for a custom snippet template.

Copied to clipboard
_snippets_definitions:
  custom_button:
    template: button
    definitions:
      text: Button Text
      url: Button URL
{
  "_snippets_definitions": {
    "custom_button": {
      "template": "button",
      "definitions": {
        "text": "Button Text",
        "url": "Button URL"
      }
    }
  }
}
hidden — boolean#

Whether to hide this snippet from the editor interface. Hidden snippets are still parsed, but cannot be inserted by team members.

Defaults to: false

Appears in: Snippet.

inline — boolean#

This key toggles whether this snippet can appear inline (within a sentence).

Setting this key to true will allow this snippet to appear inline (within a sentence).

By default, this key is false (i.e., this snippet is treated as a block-level element in the content editor).

Defaults to: false

Appears in: Snippet.

_inputs — Object<_inputs.*>#

This key defines which inputs are available at a given level of the configuration cascade.

This key has no default.

If undefined at higher levels of the configuration cascade, _inputs will default to any values configured in the CloudCannon configuration file.

Appears in: create, [*], schemas.*, collections_config.*, file_config[*], pull_request_templates[*], commit_templates[*], Snippet.

Show examplesHide examples

In this example, we have configured the date_created key as a Date and Time Input, which will automatically populate when you create a file using this input. Editors cannot alter this input as the interface is disabled.

Copied to clipboard
_inputs:
  date_created:
    type: datetime
    label: Date of article creation
    comment: UTC +0 timezone
    context:
      open: false
      title: Help
      icon: help
      content: This date field will automatically populate when you create an article.
    hidden: false
    disabled: true
    instance_value: NOW
    cascade: true
    options:
      timezone: Etc/UTC
{
  "_inputs": {
    "date_created": {
      "type": "datetime",
      "label": "Date of article creation",
      "comment": "UTC +0 timezone",
      "context": {
        "open": false,
        "title": "Help",
        "icon": "help",
        "content": "This date field will automatically populate when you create an article."
      },
      "hidden": false,
      "disabled": true,
      "instance_value": "NOW",
      "cascade": true,
      "options": {
        "timezone": "Etc/UTC"
      }
    }
  }
}

In this example, we have configured the blog_tags key as a Multiselect Input in the blog Collection.

Copied to clipboard
collections_config:
  blog:
    _inputs:
      blog_tags:
        type: multiselect
        label: Blog type
        comment: Select a blog type
        context:
          open: false
          title: Help
          icon: help
          content: |
            Blog tags help our users filter articles by topic.
        options:
          values:
            - Opinion
            - Feature
            - Resource
{
  "collections_config": {
    "blog": {
      "_inputs": {
        "blog_tags": {
          "type": "multiselect",
          "label": "Blog type",
          "comment": "Select a blog type",
          "context": {
            "open": false,
            "title": "Help",
            "icon": "help",
            "content": "Blog tags help our users filter articles by topic.\n"
          },
          "options": {
            "values": [
              "Opinion",
              "Feature",
              "Resource"
            ]
          }
        }
      }
    }
  }
}
_inputs_from_glob — Array<_inputs_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Input configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source⁠) and must end in the file extension .cloudcannon.inputs.yml.

You can use this key anywhere you would use the _inputs key in the configuration cascade.

This key has no default.

Appears in: [*], create, schemas.*, collections_config.*, file_config[*], Snippet.

Show examplesHide examples

In this example, we have several Input Configuration Files in the .cloudcannon/inputs/ folder, with each file containing multiple Input definitions. The value of the _inputs_from_glob key tells CloudCannon to only use the seo.cloudcannon.inputs.yml and blog-details.cloudcannon.inputs.yml files in that folder.

Copied to clipboard
collections_config:
  posts:
    path: content/posts
    icon: event
    inputs_from_glob:
      - /.cloudcannon/inputs/seo.cloudcannon.inputs.yml
      - /.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml
{
  "collections_config": {
    "posts": {
      "path": "content/posts",
      "icon": "event",
      "inputs_from_glob": [
        "/.cloudcannon/inputs/seo.cloudcannon.inputs.yml",
        "/.cloudcannon/inputs/blogDetails.cloudcannon.inputs.yml"
      ]
    }
  }
}
Copied to clipboard
seo_title:
  type: text
  options:
    required: true
    max_length: 50
seo_description:
  type: textarea
  options:
    show_count: true
    required: true
    max_length: 125
seo_image:
  type: image
  options:
    path:
      uploads: images
    accepts_mime_types:
      - image/png
      - image/jpeg
    required: true
    pattern: (?i)\.(jpe?g|png)$
    pattern_message: Please select a JPG or PNG image file
{
  "seo_title": {
    "type": "text",
    "options": {
      "required": true,
      "max_length": 50
    }
  },
  "seo_description": {
    "type": "textarea",
    "options": {
      "show_count": true,
      "required": true,
      "max_length": 125
    }
  },
  "seo_image": {
    "type": "image",
    "options": {
      "path": {
        "uploads": "images"
      },
      "accepts_mime_types": [
        "image/png",
        "image/jpeg"
      ],
      "required": true,
      "pattern": "(?i)\\.(jpe?g|png)$",
      "pattern_message": "Please select a JPG or PNG image file"
    }
  }
}
params — Object<params.*>#

This key defines the parameters of this snippet.

Appears in: Snippet.

picker_preview — Object#

This key defines the appearance of a Card when choosing an item to create. This uses preview as a base, and keys inside this object are overrides.

You can configure Card preview for Collections, Schemas, Object inputs, Array inputs, Select inputs, Structures, the Structure modal, Snippets, and the Snippet modal.

For more information about previews, please read our documentation on configuring card previews.

Appears in: Select Input options, Multiselect Input options, Choice Input options, Multichoice Input options, [*], Snippet.

Show examplesHide examples

In this example, we have configured the appearance of Cards in inputs using the Structure staff when adding items.

Copied to clipboard
_structures:
  staff:
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        picker_preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        picker_preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face
{
  "_structures": {
    "staff": {
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "picker_preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "picker_preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}
preview — Object#

This key defines the appearance of a Card.

You can configure Card preview for Snippets, and the Snippet modal.

For more information about previews, please read our documentation on configuring card previews.

Appears in: Snippet.

Show examplesHide examples

In this example, we have configured the appearance of the example Snippet's text and subtext.

Copied to clipboard
_snippets:
  example:
    snippet: <<example [[param]]>>
    preview:
      text:
        - text: Example
      subtext:
        - key: param
{
  "_snippets": {
    "example": {
      "snippet": "<<example [[param]]>>",
      "preview": {
        "text": [
          {
            "text": "Example"
          }
        ],
        "subtext": [
          {
            "key": "param"
          }
        ]
      }
    }
  }
}
_select_data — Object<_select_data.*>#

This key defines defines fixed data sets to populate Select and Multiselect inputs at a given level of the configuration cascade.

This key has no default.

If undefined at higher levels of the configuration cascade, _select_data will default to any values configured in the CloudCannon configuration file.

For more information, please read our documentation on Select and Multiselect inputs.

Appears in: [*], create, schemas.*, collections_config.*, file_config[*], Snippet.

Show examplesHide examples

In this example, we have configured the blog_tags Multiselect input for the blog Collection.

Copied to clipboard
collections_config:
  blog:
    _select_data:
      blog_topics:
        - Opinion
        - Feature
        - Resource
{
  "collections_config": {
    "blog": {
      "_select_data": {
        "blog_topics": [
          "Opinion",
          "Feature",
          "Resource"
        ]
      }
    }
  }
}
snippet — string#

This key defines the snippet string that contains the text to match for your snippet, with any dynamic sections represented using a placeholder in double square brackets.

Appears in: Snippet.

Show examplesHide examples

In this example, we have configured a snippet string for a custom button snippet.

Copied to clipboard
_snippets_definitions:
  custom_button:
    snippet: '[[text]]'
    template: button
{
  "_snippets_definitions": {
    "custom_button": {
      "snippet": "[[text]]",
      "template": "button"
    }
  }
}
strict_whitespace — boolean#

This key toggles whether this snippet treats whitespace as-is or not.

Setting this key to true will make the snippet treat whitespace as-is.

By default, this key is false (i.e., whitespace is normalized).

Appears in: Snippet.

_structures — Object<Structure>#

This key defines which structures are available for Object inputs and Array inputs at a given level of the configuration cascade.

This key has no default.

If undefined at higher levels of the configuration cascade, _structures will default to any values configured in the CloudCannon configuration file.

For more information, please read our documentation on structures.

Appears in: [*], create, schemas.*, collections_config.*, file_config[*], Snippet.

Show examplesHide examples

In this example, we want to populate an Array input in the blog Collection with Related Articles, including the name, description, and url fields.

Copied to clipboard
collections_config:
  blog:
    _structures:
      related_articles:
        style: select
        values:
          - preview:
              text:
                - key: name
              subtext:
                - key: url
            value:
              name: 
              description: 
              url:
{
  "collections_config": {
    "blog": {
      "_structures": {
        "related_articles": {
          "style": "select",
          "values": [
            {
              "preview": {
                "text": [
                  {
                    "key": "name"
                  }
                ],
                "subtext": [
                  {
                    "key": "url"
                  }
                ]
              },
              "value": {
                "name": null,
                "description": null,
                "url": null
              }
            }
          ]
        }
      }
    }
  }
}

In this example, we want to populate an Array input with Staff members, including the name, job_description, and profile_picture fields for all staff types, and the url field for Managers only.

Copied to clipboard
_structures:
  staff:
    style: modal
    hide_extra_inputs: false
    values:
      - value:
          _type: Employee
          name: 
          job_description: 
          profile_picture: 
        preview:
          text:
            - key: name
            - Employee
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: support_agent
      - value:
          _type: Manager
          name: 
          job_description: 
          profile_picture: 
          url: 
        preview:
          text:
            - key: name
            - Manager
          subtext:
            - key: job_description
            - Description of position
          image:
            - key: profile_picture
          icon: face
{
  "_structures": {
    "staff": {
      "style": "modal",
      "hide_extra_inputs": false,
      "values": [
        {
          "value": {
            "_type": "Employee",
            "name": null,
            "job_description": null,
            "profile_picture": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Employee"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "support_agent"
          }
        },
        {
          "value": {
            "_type": "Manager",
            "name": null,
            "job_description": null,
            "profile_picture": null,
            "url": null
          },
          "preview": {
            "text": [
              {
                "key": "name"
              },
              "Manager"
            ],
            "subtext": [
              {
                "key": "job_description"
              },
              "Description of position"
            ],
            "image": [
              {
                "key": "profile_picture"
              }
            ],
            "icon": "face"
          }
        }
      ]
    }
  }
}
_structures_from_glob — Array<_structures_from_glob[*]>#

This key defines globs that filter which files CloudCannon should use for Structure configuration.

Values in this array are relative to the root of your repository (i.e., /, not the value of source⁠) and must end in the file extension .cloudcannon.structures.yml.

You can use this key anywhere you would use the _structures key in the configuration cascade.

Please see our documentation on values_from_glob for defining individual Structure values in a split Configuration File.

This key has no default.

Appears in: [*], create, schemas.*, collections_config.*, file_config[*], Snippet.

Show examplesHide examples

In this example, we have several Structure Configuration Files in the .cloudcannon/structures/ folder. The value of the _structures_from_glob key tells CloudCannon to use the staffMembers.cloudcannon.structures.yml file in that folder.

Copied to clipboard
_structures_from_glob:
  - /.cloudcannon/structures/staffMembers.cloudcannon.structures.yml
{
  "_structures_from_glob": [
    "/.cloudcannon/structures/staffMembers.cloudcannon.structures.yml"
  ]
}
Copied to clipboard
staff:
  style: modal
  values:
    - label: Employee
      value:
        name: 
        job_description: 
        profile_picture: 
    - label: Manager
      value:
        name: 
        job_description: 
        profile_picture: 
        url:
{
  "staff": {
    "style": "modal",
    "values": [
      {
        "label": "Employee",
        "value": {
          "name": null,
          "job_description": null,
          "profile_picture": null
        }
      },
      {
        "label": "Manager",
        "value": {
          "name": null,
          "job_description": null,
          "profile_picture": null,
          "url": null
        }
      }
    ]
  }
}
template — string#

This key defines the template that this snippet should inherit, out of the available Snippet Templates.

Appears in: Snippet.

Show examplesHide examples

In this example, we have configured a snippet to use the button template.

Copied to clipboard
_snippets_definitions:
  custom_button:
    template: button
{
  "_snippets_definitions": {
    "custom_button": {
      "template": "button"
    }
  }
}
view — string#

This key defines how selected items are rendered.

Defaults to 'card', or 'inline' if inline is true.

Allowed values: card inline gallery

Appears in: Snippet.

Open in a new tab