Commera

Commera

Open in ChatGPT
Ask ChatGPT about this page
Open in Claude
Ask Claude about this page

Section reference

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.

Next steps

Last updated 2 weeks ago
Was this helpful?
Thanks!