# Garland builder

Chapter 9 of the Hooray user guide.

The garland builder lets a shopper design an organic balloon garland on the product page: pick up to four colours, choose a style and a length, and watch the preview redraw. You pack the kit, or build the garland, in exactly that mix. It needs no app and no metafield: it reads its own block's colours and settings, and a product option for the length.

## What shoppers see

* **A live preview**: an arc of balloons in three sizes on a soft wall, with a metre ruler under it. It's laid out from a fixed pattern for each product, so the same product always draws the same garland, and changing a colour only recolours the balloons; they never jump about. A longer length draws a longer arc. With nothing picked, it's a pale "ghost" garland and the line under it says "Pick up to 4 colours to see your garland."
* **A text summary** next to the preview, for everyone including screen reader users: "Organic, 3 m: Sage, Sand, Terracotta", with "About 110 balloons" beside it.
* **Style**: **Classic** ("Even 11" balloons") or **Organic** ("5", 11" and 18" mixed").
* **Colours**: one balloon swatch per colour, each with its name, ticked like checkboxes. The legend counts "2 of 4 picked". When the shopper reaches the most allowed, the others fade, and the line says "You've picked 4 colours, the most for this garland. Untick one to swap."
* **Length** comes from the product's own variant picker, which sits above the builder: choose 3 m and the preview and summary follow.

**Buy it now stays hidden until at least one colour is picked**, because it would skip the colours. If the shopper presses **Add to cart** with no colour, nothing is added: "Pick at least one colour." appears under the colours and the first colour gets focus.

## Set it up

1. **Create the product**, such as "Organic garland kit", with an option called **Length** and one variant per length: `2 m`, `3 m`, `4 m`, `6 m`. Price each length.
2. **Assign the `product.garland` template** in the product's **Theme template** field and **Save**. The builder is already on that template, under the variant picker.
3. **Set your colours**: open the theme editor, choose **Products › garland**, and click the **Garland builder** block. Each colour is a **Garland colour** block inside it: rename, recolour, add, remove and reorder them. The presets ship eight (White, Sand, Sage, Terracotta, Blush, Cobalt, Sunshine and Chrome silver in Hooray).
4. **Point the home page at it**: in the home page's **Featured product** section, choose the kit as the **Product**. That section has its own **Garland builder** block with its own colours, so set them there too.
5. **Set a lead time** if you pack to order: give the product a `custom.lead_days`, such as 3. The cart's first event date then allows for it, and the panel says "Your garland needs 3 days, so the first date is…" (chapter 10).

Colours are set in each place the builder appears: the `product.garland` template and each Featured product section. Quick view borrows the colours from the product's own page.

## Garland builder settings

| Setting | Default | What it does |
| --- | --- | --- |
| Heading | "Your colours" | The colour list's heading |
| Most colours a shopper can pick | 4 | 1 to 6 |
| Length option names | `Length, Size` | The variant option that sets the length, matched without regard to capitals. Separate names with commas. The first of the product's options whose name is on this list is used. |
| Length when no option matches | 3 | In metres. Used when the product has no length option or its value can't be read. The summary then leaves out the length and the balloon count. |
| Longest garland | 6 | In metres. The preview is full width at this length. Longer lengths stay full width. |
| Show the style choice | On | Off hides Classic and Organic. The **Default style** is then always used and still saved. |
| Default style | Organic | **Organic** or **Classic** |
| Organic label, Organic description | "Organic", "5", 11" and 18" mixed" | |
| Classic label, Classic description | "Classic", "Even 11" balloons" | |
| Balloons per metre | 36 | For "About 110 balloons". Blank hides the count. The count is rounded to the nearest ten (five under 50). |
| Message when no colour is picked | "Pick at least one colour." | |

Each **Garland colour** block has a **Name** ("Sage") and a **Colour** (`#a8b596`). The name is what the shopper reads and what's saved on the order, so use names your team will recognise when packing. With every colour removed, the theme editor shows a note and shoppers see no builder.

## Lengths the builder understands

The builder reads the number at the start of the length value, and its unit: `3 m`, `3 metres`, `3m`, `300 cm`, `10 ft` and `10'` all work. A value with no unit counts as metres. The preview and the summary always show metres, so `10 ft` reads "3 m". A value with no number, such as "Large", uses **Length when no option matches**.

If your lengths are a **Size** option, they still work: **Size** is on the list by default. If you call it something else, such as "Garland length", add that name to **Length option names**.

## What you get on the order

The colours and the style are saved with the line as two **line item properties**:

| Property | Example |
| --- | --- |
| `Colours` | Sage, Sand, Terracotta, White (in the order the shopper picked them) |
| `Style` | Organic |

The length is the variant itself ("3 m"). The shopper sees all three in the cart and at checkout. In Shopify admin, open the order: the properties are listed under the product's name in the order's items, and they're on the order whatever the shopper's device. Two garlands with different colours are two separate lines.

The property names come from the theme's words: change or translate **Colours** and **Style** in **Edit default theme content** if you need to (chapter 15).

## Where else the builder works

* **Featured product**: with **Layout** set to **Garland preview in place of the gallery**, the live preview takes the gallery's place, as in every preset's home page. It needs a product chosen (chapter 4).
* **Quick view**: products on `product.garland` show the builder in quick view, with the colours from their product page. **Quick add** on their cards opens quick view rather than adding a garland with no colours.
* **Other templates**: you can add the Garland builder block to any product template, but keep garland products on `product.garland`: quick add and quick view only recognise that template, so a garland on the default template could be quick-added with no colours.