Canopy Block Settings

Settings define the fields content editors fill in for each Canopy Block. You declare them in the settings array of a block template's config section, and their values are available in the template section through the settings variable.

All setting types share these attributes:

Tabs and groups

Blocks with many settings can organize them so editors are not shown everything at once. Both attributes are optional and only affect the editing form — they change nothing about how you access values in the template section.

Give settings a tab to split the form into tabs. Tabs appear in the order they are first used, and any settings without a tab are gathered under a General tab. The form only shows tabs when at least one setting declares one.

Give consecutive settings a group to place them under a labelled divider. Groups are open by default, and editors can collapse them.

{
    "title": "Hero",
    "name": "hero",
    "settings": [
        { "name": "title", "type": "text", "tab": "Content" },
        { "name": "description", "type": "textarea", "tab": "Content" },
        { "name": "background", "type": "color", "tab": "Style", "group": "Colors" },
        { "name": "text_color", "type": "color", "tab": "Style", "group": "Colors" },
        { "name": "custom_class", "type": "text", "tab": "Style", "group": "Advanced" }
    ]
}

This config gives the block a Content tab with two fields, and a Style tab where the color settings sit under a Colors group and the class setting under an Advanced group.

Help and descriptions

Every setting type accepts two optional strings for guiding editors. Like tabs and groups, they only affect the editing form and change nothing about the value in the template section.

• help is a short hint shown as an info icon tooltip beside the field label.
• description is muted helper text rendered underneath the input.

Use help for a quick clarification editors may not need every time, and description for guidance that should always be visible:

{
    "name": "subtitle",
    "type": "text",
    "help": "Shown under the page title.",
    "description": "Keep it under 80 characters so it fits on one line."
}

Text

type: text

A single line of plain text. The value is a String, with "New text" as the built-in default.

<p>{{ settings.subtitle }}</p>

Textarea

type: textarea

Multiple lines of plain text. The value is a String, empty by default.

Richtext

type: richtext

Formatted text edited with a rich text editor. The value is an HTML String, so output it with the raw filter:

<div class="prose">{{ settings.body|raw }}</div>

Select

type: select

A dropdown of predefined options. The value is the selected option's value as a String.

{
    "name": "alignment",
    "type": "select",
    "options": [
        { "value": "left", "label": "Left" },
        { "value": "center", "label": "Center" },
        { "value": "right", "label": "Right" }
    ],
    "default": "center"
}

Radio

type: radio

A set of radio buttons. Works exactly like Select, with the same options attribute, but shows every option at once in the editor.

Checkbox

type: checkbox

A single on or off toggle. The value is a Boolean, false by default.

{% if settings.show_title %}
  <h2>{{ settings.title }}</h2>
{% endif %}

File

type: file

A file picked from the site's assets. The value is an object describing the file.

{% if settings.brochure.path %}
  <a href="{{ settings.brochure.path }}" download>{{ settings.brochure.name }}</a>
{% endif %}

URL

type: url

A link with editable text and target. The value is an object.

<a href="{{ settings.cta.url }}" target="{{ settings.cta.target }}">{{ settings.cta.text }}</a>

Date

type: date

A date picker. The value is a formatted date String.

Color

type: color

A color picker. The value is a hex color String, #000000 by default.

<section style="background-color: {{ settings.background }}">...</section>

Heading

type: heading

A heading with editable text and an editable HTML element. The value is an object.

<{{ settings.heading.element }}>{{ settings.heading.value }}</{{ settings.heading.element }}>

Number

type: number

A numeric input. The value is a Number.

List

type: list

A repeatable list of text items. The value is an Array of Strings, empty by default.

<ul>
  {% for item in settings.features %}
    <li>{{ item }}</li>
  {% endfor %}
</ul>

Media Sources

type: media-sources

A list of media files for HTML5 audio and video elements. The value is an Array of objects, each with a url and a type (the MIME type).

<video controls>
  {% for source in settings.video_sources %}
    <source src="{{ source.url }}" type="{{ source.type }}" />
  {% endfor %}
</video>

Collection

type: collection

A collection picked from the site's collections. Use it when a block renders whatever a collection holds, and the editor decides which collection feeds it, such as a block that shows the latest items from any collection they choose. The editor sees a dropdown of the site's collections.

Collection settings use only the base attributes. default may be a collection handle String, and placeholder sets the dropdown's placeholder text.

The value is null while no collection is selected, or when the selected collection has been deleted. Otherwise it is an object:

Each entry in entries exposes its field values under their field names, such as entry.title or entry.image, along with id, created_at, and updated_at.

{
    "name": "source",
    "type": "collection",
    "label": "Collection",
    "help": "All entries of the chosen collection are rendered."
}

Entry

type: entry

One or more entries hand-picked from a collection. Use it when the editor chooses specific content rather than a whole collection: a featured item, a set of related items, or a hand-picked gallery.

display_field only changes the labels in the editor's picker. It never affects what the template receives or renders.

Pass an array to show multiple values while picking: the first listed field with a value becomes the label, the remaining values appear alongside it, and searching matches all of the listed fields. This is useful when one field alone doesn't identify an entry, like products that share a name but differ by SKU:

{
    "name": "featured",
    "type": "entry",
    "collection": "products",
    "display_field": ["name", "sku"]
}

Rendering entries

Each entry exposes its field values under their field names, along with id, created_at, and updated_at, just like the entries of a Collection setting.

With multiple off, the value is the picked entry, or null when nothing is picked or the entry or its collection was deleted:

{% if settings.featured %}
  <h3>{{ settings.featured.title }}</h3>
  <img src="{{ settings.featured.image }}" alt="{{ settings.featured.title }}">
{% endif %}

With multiple on, the value is an array of entries in the exact order the editor picked them, so you can rely on that order for layout. Deleted entries are skipped, and the array is empty when nothing is picked:

{% if settings.related|length > 0 %}
  {% for item in settings.related %}
    {{ item.title }}
  {% endfor %}
{% endif %}

Common configurations

Lock the setting to one collection, and label entries by a specific field while picking:

{
    "name": "featured",
    "type": "entry",
    "label": "Featured product",
    "collection": "products",
    "display_field": "sku"
}

Pre-select a collection but let the editor switch to another:

{
    "name": "highlight",
    "type": "entry",
    "label": "Highlight",
    "default_collection": "products"
}

Let the editor pick up to four entries:

{
    "name": "related",
    "type": "entry",
    "label": "Related items",
    "collection": "products",
    "multiple": true,
    "max": 4
}

Form

type: form

A form picked from the project's forms. It works like the Collection selector: the editor sees a dropdown of the project's forms and chooses one, so a single block template can render whichever form the page needs, a contact form here, a newsletter signup there, without hard-coding a handle.

default may be a form handle String.

The value is null while no form is selected, or when the selected form has been deleted. Otherwise it is an object:

Combine the setting with the form tag, passing the picked handle to the tag and looping the fields, and the block generates a fully working form for whichever form the editor selects:

{
    "name": "contact_form",
    "type": "form",
    "label": "Form",
    "placeholder": "Select a form"
}

Blog

type: blog

A blog picked from the site's blogs. It mirrors the Collection selector: the editor sees a dropdown of the site's blogs and chooses one, so a single block template can render posts from whichever blog the page needs, the news blog here, a case studies blog there, without hard-coding a slug.

The stored value is the blog slug, a plain String, so default may be a blog slug too.

{ "name": "source", "type": "blog", "label": "Blog", "placeholder": "Choose a blog" }

The value in the template section is null while no blog is picked, or when the slug no longer exists. Otherwise it is an object in the same shape the blog module returns, so existing blog markup ports over unchanged:

{% if settings.source %}
  <h2>{{ settings.source.name }}</h2>
  {% for post in settings.source.posts %}
    <article>
      <a href="{{ post.slug }}">{{ post.title }}</a>
      <p>{{ post.publish_date|date('d M Y') }}</p>
      <p>{{ post.description }}</p>
    </article>
  {% endfor %}
{% endif %}

The post object

Every post, whether it arrives through a blog's posts array or through a Post setting, exposes the same keys:

slug is the post's full path, so link to it directly rather than prefixing the blog's uri. The three dates are Strings, ready to pass to the date filter.

Posts come back newest first, ordered by publish_date, both in a blog's posts array and in the editor's post picker.

Post

type: post

One or more posts hand-picked from a blog. It mirrors the Entry setting: use it when the editor chooses specific posts rather than a whole blog, a featured post, a set of related reading, or a hand-picked roundup.

The stored value is { "blog": "<slug>", "id": <id> }, or { "blog": "<slug>", "ids": [<id>, ...] } in multiple mode.

{ "name": "featured", "type": "post", "label": "Featured post", "blog": "news" }

{ "name": "related", "type": "post", "label": "Related", "multiple": true, "max": 3 }

Rendering posts

Each post is a post object. With multiple off, the value is the picked post, or null when nothing is picked:

{% if settings.featured %}
  <h3><a href="{{ settings.featured.slug }}">{{ settings.featured.title }}</a></h3>
  <img src="{{ settings.featured.cover_image }}" alt="{{ settings.featured.title }}">
{% endif %}

With multiple on, the value is always an array, empty rather than null when nothing is picked, in the exact order the editor picked them, so you can rely on that order for layout:

{% if settings.related|length > 0 %}
  {% for post in settings.related %}
    <a href="{{ post.slug }}">{{ post.title }}</a>
  {% endfor %}
{% endif %}

Picking posts

Picker labels are automatic: the post title, with the publish date as a muted hint beside it. There is no display_field equivalent, Entry needs one because collections have arbitrary fields, while posts always have a title.