# Storefront banners in Go (GoCommerce module)

> Keep a GoCommerce storefront’s home page pictures as rows: slides across the top, grids of tiles under a heading, a phone picture, a switch and one saved order.

- Canonical: https://kitcommerce.store/integrations/banners/
- Last updated: 2026-10-28

---

Platform

## Storefront banners in Go

A Go package that keeps the pictures on a storefront’s home page as rows, one per picture: slides across the top, and grids of tiles under a heading. Each is a picture, an optional phone picture, a title that is also its alternative text, and a link. The storefront reads them at /x/banners?page=home, already split into slides and grids.

- **Platform** module
- **1** setting
- **6** tests
- **6** API operations
- **ext/banners**

### What it does

In the package’s own words, banners are “the pictures a shop puts on its storefront’s pages: slides across the top of a page, and grids of tiles under a heading, each a picture and a link.” They are kept as rows, one per picture, so a shop adds, reorders and switches off one banner without rewriting a page.

A banner has a placement, slide or grid, and a grid tile has a heading: tiles with the same heading on a page form one grid. The picture is wide enough for a desktop; an optional narrower crop is for phones, and without one the wide picture is used there too. The order is the shop’s own and runs across the whole page.

Each banner names its page, so other pages can follow, but only the home page is accepted until a storefront shows banners anywhere else. A store that starts with the sample shop gets three slides and a Shop by collection grid, made from the sample shop’s photographs.

### Configuration

There is nothing to set in Go: Config is an empty struct, there so a setting can arrive without changing how the module is installed. Banners are rows an operator edits on the admin’s Content › Banners screen or through the API.

*Banners module settings — 1 setting, 0 required*

| Setting | Environment variable | Required | What it does |
| --- | --- | --- | --- |
| `banners` Banners, on the Plugins screen | — | No | The plugin’s switch, on by default. Off, GET /x/banners answers 404 while the Banners screen and its admin routes keep working, so banners can be prepared before they show. |

The module reads its Config struct, not the environment. The variable names are the ones the package’s own example or the reference binary uses; in your own `main()` you choose where each value comes from. Where a setting has a panel label, the admin’s settings drawer can hold it too, and a value typed there wins over Config.

### Setting it up

1. **Install the module** — Pass banners.New to gocommerce.New, as below, or start the reference binary with -banners. It adds one table.
2. **Add the pictures** — On Content › Banners, add a slide or a grid tile: a picture chosen from Files or typed in as a link, an optional phone picture, a title and a link such as /collections/new-in.
3. **Put them in order** — Move banners with the arrows on the screen. The page’s whole order is saved at once, with PUT /api/admin/x/banners/order.
4. **Render them** — The storefront reads GET /x/banners?page=home and gets slides and grids, each grid with its heading and its tiles in order. Only switched-on banners are served.

main.go

```
import (
	"github.com/itswadesh/gocommerce/core"
	"github.com/itswadesh/gocommerce/ext/banners"
)

app, err := gocommerce.New(cfg,
	// Config has nothing to set yet.
	banners.New(banners.Config{}),
)
```

The package doc has no example of its own; this is how the reference binary’s -banners flag installs it. cfg is your gocommerce.Config. Import path `github.com/itswadesh/gocommerce/ext/banners`.

### How it works

- **Served already split**

  GET /x/banners?page=home answers the page, its slides and its grids, with only switched-on banners and in the shop’s order. Grids come in the order their first tile appears. Each banner carries its id, title, link, picture and phone picture.

- **One order per page**

  PUT /api/admin/x/banners/order takes every banner on the page, each once, and rewrites their positions in one transaction. An order that leaves one out or names one twice is refused, so a page is never half sorted. A new banner goes last on its page.

- **Addresses that cannot run**

  A picture or a link is a path on the site or an http or https address. javascript:, data:, a protocol-relative //host, /\\ and any whitespace or control character are refused. Addresses are at most 2,048 characters, titles 200.

- **A switch that keeps the banner**

  Switching a banner off takes it off the storefront without deleting it. A save that does not mention the switch leaves it as it was.

- **Its own rights**

  banners.read for managers and staff, banners.write for managers: changing what every visitor sees on arrival is the manager’s.

- **Sample banners come and go together**

  The sample shop’s slides and grid are marked as samples, which only the engine sets, and are erased with the rest of the sample shop. A slide whose sample collection or category the store lacks is left out rather than linking nowhere.

### What it does not do

Read these before an order depends on it. No store is known to run GoCommerce in production yet, so these come from the code, not from anyone’s experience.

- **The home page only** — A banner for any page but home is refused. The column is there for other pages; the storefront shows banners on its home page alone.
- **No schedule** — A banner is on or off. There is no start or end date; the switch is the only way to time one.
- **An address, not an upload** — The module stores the picture’s address. Uploading is the Files screen’s job, and the module does not check that a picture exists or how large it is.
- **Two placements** — Slides and grid tiles. There are no other layouts, and a tile’s grid is known only by its heading text.
- **No counts** — Nothing records how often a banner was seen or clicked.

FAQ

### Questions about the Banners module

**What does the storefront read?**

GET /x/banners?page=home on the host that serves your GoCommerce API. It answers the page name, a list of slides and a list of grids, each grid with its heading and tiles, already in the shop’s order.

**Can a banner show on a collection page?**

No. Only the home page is accepted, because no storefront shows banners anywhere else yet.

**Can I schedule a banner?**

No. A banner has an on and off switch and no dates. Switch it on when it should show, and off afterwards.

**What size should the pictures be?**

The module does not say or check. It takes a wide picture for desktops and an optional narrower one for phones; without the phone picture the wide one is used on phones too.

### Related modules

Each is a directory under `ext/`, imported the same way. Where this one fits in the store: [How modules extend GoCommerce](https://kitcommerce.store/features/development/).

- [CMS content pages in Go Add about, terms and delivery pages to a GoCommerce store: one page per slug and language, draft or published, served at /x/cms/pages/{slug}.](https://kitcommerce.store/integrations/cms/)
- [Contact form API in Go A GoCommerce contact form and product enquiries in one inbox: announced by email, answered from the admin, rate-limited, with a honeypot against bots.](https://kitcommerce.store/integrations/contact/)
- [Ecommerce FAQ API in Go Give a GoCommerce store a page of questions and answers: grouped into sections, ordered by hand, draft or published, served whole at /x/faq.](https://kitcommerce.store/integrations/faq/)
- [Customer accounts and login in Go Add shopper accounts to a GoCommerce store: sign-up, sign-in, saved addresses, password reset and order history by claim. Guest checkout keeps working.](https://kitcommerce.store/integrations/identity/)

### Source

Everything on this page is read from [`ext/banners`](https://github.com/itswadesh/gocommerce/tree/main/ext/banners) in the GoCommerce repository, MIT licensed. When this page and the code disagree, the code is right and this page is out of date.

- [ext/banners on GitHub](https://github.com/itswadesh/gocommerce/tree/main/ext/banners)
- [All GoCommerce modules](https://kitcommerce.store/integrations/)

### Try it against a store of your own

The backend + admin quick start runs GoCommerce’s API and admin on your own machine, without a storefront. Add this module to it and try it on test orders before a real one depends on it.

[Backend + admin quick start](https://kitcommerce.store/#one-command) · [Read the module](https://github.com/itswadesh/gocommerce/tree/main/ext/banners) · [All integrations](https://kitcommerce.store/integrations/)