---
title: "Add sections"
space: "Commera"
url: "https://docs.bwh.tech/commera/build-a-section-theme/add-sections"
updated: "2026-11-07"
---

Write three new sections: a sale banner, some offer tiles and a row of sale products. Then put them on the home page.

By the end, the home page has the three sections, and a merchant finds them in the editor under **Add section**.

## Before you start

Finish [Change a section](/commera/build-a-section-theme/change-a-section).

## What is a setting, what is a block, what is fixed

Before you write a section, decide who changes what. A section has three kinds of thing.

| Make it | When | Example |
| --- | --- | --- |
| A **setting** | One value, which the merchant may want to change | The heading of the sale banner |
| A **block** | A thing that repeats, where the merchant adds, removes and reorders copies | An offer in the sale banner |
| **Fixed** in the `.html` | The merchant should not change it, or the design breaks | Spacing, the grid, font sizes, the shape of a card |

A good test is to ask "what would the client ask me to change before Diwali?" It is the words, the photos and the number of offers. It is not the padding.

Two more things help:

- Give every setting a `default` that looks good, so the section looks right the moment it is added.
- Use the theme's colours (`bg-brand`, `text-on-brand`) and not fixed ones. The section then follows the colour the client picks in Theme settings.

## Sale banner

A banner with a heading and up to three offers. The heading is a setting. Each offer is a block, with a photo, a title, some text, a discount code and a link.

1. Make `themes/diwali/sections/sale_banner.json`:

   ```json
   {
   	"name": "Sale banner",
   	"category": "Banners",
   	"settings": [
   		{ "id": "heading", "type": "text", "label": "Heading", "default": "The festival sale" }
   	],
   	"blocks": {
   		"offer": {
   			"name": "Offer",
   			"settings": [
   				{ "id": "image", "type": "image", "label": "Image", "default": "" },
   				{ "id": "title", "type": "text", "label": "Title", "default": "Flat 20% off" },
   				{ "id": "text", "type": "textarea", "label": "Text", "default": "" },
   				{ "id": "code", "type": "text", "label": "Discount code", "default": "" },
   				{ "id": "url", "type": "url", "label": "Link", "default": "" }
   			]
   		}
   	},
   	"max_blocks": 3
   }
   ```

   - `name` is what the merchant sees. `category` is the group it sits in under **Add section**.
   - `blocks` lists the kinds of block. The key, `offer`, is the block type.
   - `max_blocks` is the most offers the merchant can add.

2. Make `themes/diwali/sections/sale_banner.html`:

   ```jinja
   {% set language = frappe.lang or "en" %}
   {% if section.blocks %}
   <section class="bg-brand px-5 py-16 text-on-brand md:px-12">
   	<h2 class="text-4xl">{{ section.settings.heading }}</h2>
   	<div class="mt-8 grid gap-6 grid-cols-[repeat(auto-fit,minmax(20rem,1fr))]">
   		{% for offer in section.blocks %}
   		<a href="{{ offer.settings.url or '/' ~ language ~ '/products' }}" class="flex flex-col items-start gap-6 rounded-xl border border-on-brand/30 p-5 sm:flex-row sm:items-center"{{ offer.editor_attributes }}>
   			{% if offer.settings.image %}
   			<img src="{{ offer.settings.image }}" alt="{{ offer.settings.title }}" loading="lazy" class="aspect-[3/4] w-36 shrink-0 rounded-lg object-cover">
   			{% endif %}
   			<div>
   				<p class="text-3xl">{{ offer.settings.title }}</p>
   				{% if offer.settings.text %}
   				<p class="mt-2 text-p-md">{{ offer.settings.text }}</p>
   				{% endif %}
   				{% if offer.settings.code %}
   				<p class="mt-4 inline-flex h-8 items-center whitespace-nowrap rounded-lg border border-dashed border-on-brand px-3 text-base">{{ _("Use code {0}").format(offer.settings.code) }}</p>
   				{% endif %}
   			</div>
   		</a>
   		{% endfor %}
   	</div>
   </section>
   {% endif %}
   ```

   - `section.settings.heading` is the setting. `section.blocks` is the list of offers.
   - `offer.settings.image` is a ready image URL. You do not have to build it.
   - `{{ offer.editor_attributes }}` lets the editor select the offer when the merchant clicks it in the preview. Put it on the outer tag of every block. It prints nothing on the live store.
   - The section prints nothing if it has no offers.

:::caution[Never build a Tailwind class from a variable]
Tailwind reads the class names in your files as plain text. A class like `md:grid-cols-{{ n }}` is never found, and the stylesheet does not get it. This section needs a grid that fits any number of offers, so it uses one class that is written out: `grid-cols-[repeat(auto-fit,minmax(20rem,1fr))]`. When you need to choose between classes, write each one out, as the hero does.
:::

## Offer tiles

A row of tiles for price bands, such as "Under ₹1,999". Each tile is a block. The colour of a tile is a `select`, so the merchant picks from your list.

1. Make `themes/diwali/sections/offer_tiles.json`:

   ```json
   {
   	"name": "Offer tiles",
   	"category": "Banners",
   	"settings": [
   		{ "id": "heading", "type": "text", "label": "Heading", "default": "Shop by budget" }
   	],
   	"blocks": {
   		"tile": {
   			"name": "Tile",
   			"settings": [
   				{ "id": "label", "type": "text", "label": "Label", "default": "Under ₹1,999" },
   				{ "id": "caption", "type": "text", "label": "Caption", "default": "" },
   				{ "id": "url", "type": "url", "label": "Link", "default": "" },
   				{
   					"id": "tone",
   					"type": "select",
   					"label": "Colour",
   					"options": ["warm", "blush", "plain"],
   					"default": "warm"
   				}
   			]
   		}
   	},
   	"max_blocks": 4
   }
   ```

2. Make `themes/diwali/sections/offer_tiles.html`:

   ```jinja
   {% set language = frappe.lang or "en" %}
   {% set tones = {"warm": "bg-surface-amber-3", "blush": "bg-surface-red-2", "plain": "bg-surface-gray-2"} %}
   {% if section.blocks %}
   <section class="px-5 py-20 md:px-12">
   	<h2 class="text-3xl">{{ section.settings.heading }}</h2>
   	<div class="mt-8 grid grid-cols-2 gap-4 md:grid-cols-4">
   		{% for tile in section.blocks %}
   		<a href="{{ tile.settings.url or '/' ~ language ~ '/products' }}" class="{{ tones[tile.settings.tone] }} flex aspect-[4/3] flex-col justify-end rounded-xl p-5"{{ tile.editor_attributes }}>
   			<p class="text-3xl">{{ tile.settings.label }}</p>
   			{% if tile.settings.caption %}
   			<p class="mt-1 text-base text-ink-gray-7">{{ tile.settings.caption }}</p>
   			{% endif %}
   		</a>
   		{% endfor %}
   	</div>
   </section>
   {% endif %}
   ```

   The `tones` line is the same idea as the hero's `backgrounds`: each option maps to a class that is written out in full.

## Festive picks

A row of products that are on sale. The merchant does not pick the products. The theme asks the store, so the row always shows what is on sale today.

Templates get a `commera` object. `commera.catalog.list_products` returns a page of products, in the same shape the shop pages use.

1. Make `themes/diwali/sections/festive_picks.json`:

   ```json
   {
   	"name": "Festive picks",
   	"category": "Products",
   	"settings": [
   		{ "id": "title", "type": "text", "label": "Title", "default": "On sale this Diwali" },
   		{ "id": "count", "type": "number", "label": "Products to show", "default": 4 }
   	],
   	"blocks": {},
   	"max_blocks": 0
   }
   ```

2. Make `themes/diwali/sections/festive_picks.html`:

   ```jinja
   {% from "components/macros/product_card.html" import product_card with context %}
   {% set products = commera.catalog.list_products(on_sale=True, sort="discount", page_size=section.settings.count | int).products %}
   {% if products %}
   <section class="px-5 py-20 md:px-12">
   	<h2 class="text-3xl">{{ section.settings.title }}</h2>
   	<div class="mt-10 grid grid-cols-2 gap-x-5 gap-y-12 md:grid-cols-4 md:gap-x-8">
   		{% for product in products %}
   		{{ product_card(product) }}
   		{% endfor %}
   	</div>
   </section>
   {% endif %}
   ```

   - `on_sale=True` keeps the products that have a sale price. `sort="discount"` puts the biggest discounts first.
   - A `number` setting gives a float, so `| int` turns it into a whole number for `page_size`.
   - `product_card` is the same macro the starter's product lists use.
   - If no product is on sale, the section prints nothing.

:::note[A simpler way for a plain product list]
If a section only needs a list of products, name one of its settings `source`. The theme then loads the products before your template runs, and puts them in `section.products`. Featured products works this way. See the [section reference](/commera/build-a-section-theme/section-reference).
:::

## Put them on the home page

A section file says how a section works. A layout says where it goes. Open `themes/diwali/layouts/index.json` and add three entries to the `sections` list, after the hero:

```json
	{
		"id": "festival-sale",
		"type": "sale_banner",
		"hidden": false,
		"settings": { "heading": "The festival sale" },
		"blocks": [
			{
				"id": "offer-1",
				"type": "offer",
				"settings": {
					"image": "images/suit.webp",
					"title": "Suits, flat 20% off",
					"text": "Linen and silk blends for the evenings of the festival.",
					"code": "DIWALI20"
				}
			},
			{
				"id": "offer-2",
				"type": "offer",
				"settings": {
					"title": "Festive dresses from ₹2,999",
					"text": "Printed cotton that goes from the puja to the party."
				}
			}
		]
	},
	{
		"id": "festive-picks",
		"type": "festive_picks",
		"hidden": false,
		"settings": {},
		"blocks": []
	},
	{
		"id": "budget",
		"type": "offer_tiles",
		"hidden": false,
		"settings": {},
		"blocks": [
			{ "id": "tile-1", "type": "tile", "settings": { "label": "Under ₹1,999", "caption": "Gifts for everyone", "tone": "warm" } },
			{ "id": "tile-2", "type": "tile", "settings": { "label": "Under ₹2,999", "caption": "Kurtas and shirts", "tone": "blush" } },
			{ "id": "tile-3", "type": "tile", "settings": { "label": "Under ₹4,999", "caption": "Dresses and suits", "tone": "plain" } }
		]
	}
```

- `type` is the file name of the section.
- `id` is the name of this copy. It must be different from the other ids on the page.
- `settings` and `blocks` hold the values for this page. A setting you leave out uses its `default`.
- The second offer has no photo. The client adds it later.

Build the CSS, because the new sections use classes the theme did not have:

```bash
npm run build:diwali
```

## Check it worked

Open `/en`. The three sections are on the home page.

<img src="/files/commera-04-add-sections-sale-banner-aae56c1e.png" alt="A deep red sale banner with two offers: suits flat 20 percent off with a code, and festive dresses from 2,999" width="944">

<img src="/files/commera-04-add-sections-festive-picks-7baf9671.png" alt="A row of four products on sale, with the old price crossed out" width="944">

<img src="/files/commera-04-add-sections-offer-tiles-3aa00c08.png" alt="Three coloured tiles: Under 1,999, Under 2,999 and Under 4,999" width="944">

On a phone, the offers stack, and the image goes above the words:

<img src="/files/commera-04-add-sections-sale-banner-mobile-c25227ba.png" alt="The sale banner on a phone: each offer has its photo above the text" width="320">

Now open the theme editor, at `/commera/storefront/theme/Diwali/editor`. Click the **+** next to **Home page**. The new sections are in the list. **Sale banner** and **Offer tiles** are under **Banners**, and **Festive picks** is under **Products**, because of each file's `category`.

<img src="/files/commera-04-add-sections-add-section-a972d8fe.png" alt="The Add section list, with Offer tiles and Sale banner under Banners and Festive picks under Products" width="290">

:::note[A section that is missing from the list]
The file name must use letters, digits and underscores only, so `sale_banner.json` works and `sale-banner.json` does not. Each section needs both a `.json` and an `.html` file.
:::

## Next steps

- [Hand it to your client](/commera/build-a-section-theme/hand-it-to-your-client)
- [Section reference](/commera/build-a-section-theme/section-reference)
