Storefront banners in Go

What it does

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.

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 modulePass banners.New to gocommerce.New, as below, or start the reference binary with -banners. It adds one table.
2. Add the picturesOn 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 orderMove 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 themThe 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.

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{}),
)

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 onlyA 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 scheduleA 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 uploadThe 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 placementsSlides and grid tiles. There are no other layouts, and a tile’s grid is known only by its heading text.
• No countsNothing records how often a banner was seen or clicked.

Related modules

Each is a directory under ext/, imported the same way. Where this one fits in the store: How modules extend GoCommerce.

• 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}.
• 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.
• 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.
• 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.