Every setting type, block rule, limit and error message for section themes, in one place.
Files
A section is two files in the theme's sections/ folder. The file name, without the extension, is the section type.
sections/sale_banner.html
sections/sale_banner.json
A section type can use letters, digits and underscores. Anything else, for example sale-banner, is not found.
A page layout is a file in the layouts/ folder:
| File | Page |
|---|---|
layouts/index.json |
Home page |
layouts/products.json |
Product list |
layouts/product.json |
Product page |
layouts/search.json |
Product list, when a shopper searches |
layouts/page.json |
Content pages |
layouts/header_group.json |
Header, on every page |
layouts/footer_group.json |
Footer, on every page |
There are no Python files for sections. A section gets its data from its settings, and from the commera object in the template.
Section file
{
"name": "Sale banner",
"category": "Banners",
"settings": [],
"blocks": {},
"max_blocks": 3
}
| Key | What it does |
|---|---|
name |
The name in the editor, in the Add section list and in the section tree. |
category |
The group the section sits under in the Add section list. |
settings |
A list of settings. Each one becomes a field in the editor. |
blocks |
The kinds of block a merchant can add, by block type. Leave it as {} for none. |
max_blocks |
The most blocks the section can hold. If you leave it out, or set it to 0, the limit is 50. |
groups |
Where the section can go. The default is ["pages"]. Use ["header_group"] or ["footer_group"] for header and footer sections. |
pages |
Limits the section to some pages, for example ["index"]. |
required |
Set it to true, and if the theme's layout file for a page has this section, the page cannot be saved without it. |
max_products |
For a section with a source setting, how many products to load. The default is 8. |
Setting
{ "id": "title", "type": "text", "label": "Title", "default": "Flat 20% off" }
| Key | What it does |
|---|---|
id |
The name you use in the template: section.settings.title. Required. |
type |
One of the types below. |
label |
The field name in the editor. Without it, the editor shows the id. |
default |
The value until the merchant changes it. |
options |
For select only: the list of choices. |
Setting types
| Type | Field in the editor | What the template gets |
|---|---|---|
text |
One line of text | The text, with HTML escaped |
textarea |
A few lines of text | The text, with HTML escaped |
url |
One line of text | The text, with HTML escaped |
image |
An Upload button | A ready image URL, with HTML escaped. Empty if the file is missing. |
number |
A number | A float, for example 4.0. Use \| int when you need a whole number. |
checkbox |
A tick box | true or false |
select |
A drop-down | The chosen option, as written in options |
collection |
A collection picker | The collection handle |
products |
A product picker | A list of product codes |
The editor does not know any other type. It stops with Unknown section setting type: <type>.
The editor shows each select option with its first letter in capitals and _ or - changed to a space. So on_sale shows as On sale.
A text value can also be saved for each language, for example {"en": "Sale", "ar": "..."}. The template gets the one that matches the page language. If there is none, it gets the English one, or the first one.
Images
An image value can be:
| Value | Result |
|---|---|
images/hero.webp |
A file in your theme's public/themes/<theme>/ folder. |
/files/dress.webp |
A file a merchant uploaded. It must exist. |
/assets/..., http://..., https://... |
Used as written. |
If the merchant clears an image, the default of the setting is used.
The source setting
A section with a setting called source gets a section.products list, filled in before your template runs. The section is left out of the page when the list is empty. Use these option names:
source |
Products | Needs the setting |
|---|---|---|
newest |
The newest products | |
on_sale |
Products with a sale price | |
collection |
Products in one collection | collection |
hand_picked |
The products the merchant picked | products |
Do not use source as a name for anything else.
Blocks
"blocks": {
"offer": {
"name": "Offer",
"settings": []
}
}
The key (offer) is the block type. name is what the editor shows. settings works like the section's settings.
In the template, section.blocks is the list of blocks. Each block has type, id and settings.
Add {{ block.editor_attributes }} to the block's outer tag. The editor uses it to select the block when the merchant clicks it in the preview. It prints nothing on the live store.
Blocks of a type that the section does not list are skipped. Blocks after the max_blocks limit are not shown.
Layout file
{
"sections": [
{
"id": "hero",
"type": "hero",
"hidden": false,
"settings": { "background": "warm" },
"blocks": [
{ "id": "slide-1", "type": "slide", "settings": { "image": "images/hero.webp" } }
]
}
]
}
| Key | Rule |
|---|---|
id |
Required. Each section id must be different on a page. Each block id must be different inside its section. |
type |
Required. The file name of a section in the theme. |
hidden |
true or false. A hidden section stays in the editor and is left out of the store. |
settings |
Only setting ids that the section file lists. You can leave out any setting, and its default is used. |
blocks |
A list. Only block types that the section file lists. |
A merchant's saved layout comes before the layout file. See Ship it.
Errors
These are the messages that come back when a layout cannot be saved. A layout file is not checked when the store loads. A section type that does not exist is skipped, and its place on the page is empty.
| Message | What to do |
|---|---|
A layout must be an object with a "sections" list. |
The file must be { "sections": [ ... ] }. |
Section entries need an id and a type. |
Add id and type to every section. |
Block entries need an id and a type. |
Add id and type to every block. |
Section id <id> is used twice. |
Give each section a different id. |
Block id <id> is used twice. |
Give each block in the section a different id. |
Section type <type> does not exist in this theme. |
There is no sections/<type>.json file. Check the spelling. |
Section type <type> cannot be used in <page>. |
The section's groups or pages do not allow it on this page. |
Section <id>: hidden must be true or false. |
Use true or false, without quotes. |
Section <id>: blocks must be a list. |
Use [ ... ] for blocks. |
Section <id> allows at most <number> blocks. |
Remove blocks, or raise max_blocks. |
Section <id> does not allow blocks of type <type>. |
Add the block type to the section's blocks. |
<Name> section: settings must be an object. |
Use { ... } for settings. |
<Name> section: unknown setting <id>. |
The section's .json file has no setting with this id. |
<Name> section: "<Label>" has the wrong type. |
The value does not fit the type. For example, select values must be one of the options, and checkbox must be true or false. |
<Name> section: image <path> is not an uploaded file. |
A /files/... image that is not in the site. |
<Name> section: image <path> does not exist in this theme. |
No such file in the theme's public/themes/<theme>/ folder. |
<Name> section: product <code> does not exist or is not published. |
Use the code of a published product. |
<Name> section: collection <handle> does not exist. |
Use a collection handle that exists. |
The <page> page needs its <Name> section. |
The section has "required": true. Put it back. |
For a block, <Name> section is <Block name> block in <Section name> section.
If a section fails while it renders, the page shows the rest of the sections and the Error Log gets an entry called Theme section <type> failed to render.