**Marketing -> Popups**

A popup is a message you show your traders inside the platform: a promotion, an
announcement, a short form. What it looks like lives under **Content**, who sees
it and when lives under **Rules**.

## Starting from a design

New popups begin with two questions and a gallery.

**What is this popup for?** Say something, hand out a code, or collect an email.
It only decides the content you start from, and which designs you are offered
next. Everything on the canvas is yours to rewrite afterwards.

**How do you want to build it?** The visual canvas or HTML and CSS. Both end up
as the same popup on the trader's screen; the difference is how you edit it.

Then the designs, six per purpose: two visual layouts and one hand written one,
each in a light and a dark palette. They are drawn in the gallery exactly as a
trader will receive them, not as an approximation, so what you click is what you
get. Every one of them uses your brand colour. There is a blank card at the end
of the row for starting from nothing.

## Designing it

**Visual** gives you a canvas. Add text, boxes, lines, images, buttons and input
fields from the toolbar, drag them where you want them, and set colours, fonts
and sizes in the panel on the right. The canvas is a fixed size that scales down
to fit smaller screens, so what you lay out is what a trader sees.

**Code** gives you an HTML and a CSS box, with a live preview beside them. Use it
when the design is beyond what the canvas does. Scripts, iframes and embedded
content are stripped before anything is stored: a popup renders live in your
traders' browsers, so it cannot carry active content.

### Converting a visual design to HTML

A visual popup has a **Convert to HTML** button next to the editor name. It
compiles the canvas into HTML and CSS you can then edit by hand, keeping your
tokens and your brand colour intact, and sets the popup's width to the width the
canvas was so nothing gets cropped.

:::warning This only goes one way
Free HTML cannot be mapped back onto a canvas, so the popup stays in code mode
from that point on. Convert when you have taken the canvas as far as it goes,
not to have a look.
:::

If the design had inputs on it, the canvas stops being what defines the form.
The fields move into the Form panel below, and the converted markup binds to
those keys. Nothing is lost, but that is where you edit them from then on.

Text can contain tokens like `{{trader_name}}` and `{{coupon_code}}`, filled per
trader when the popup is shown. The token palette lists what is available.

## Collecting answers

Add an input with the **Field** tool and the popup starts collecting. There is no
separate list of fields to declare first: the inputs on the canvas are the form.
Each one has a name, a type (text, email or long text) and a required flag, all
set in the properties panel next to everything else about it.

The first field you add brings a **Send** button with it. Any button can become
that button by setting its action to "Submit the form".

Two things stop a save, because the popup could not work once live:

- An input without a name. The name is what its answers are stored under.
- Fields with nothing that submits them.

The editor flags both while you design, so it should never be a surprise.

:::note Renaming a field
A field keeps the name it was first saved with, internally. Renaming the label
later changes what the trader reads, and leaves earlier answers filed where they
already are, so your submissions list stays whole.
:::

The **Form** panel holds what happens around the fields: who gets emailed when
someone submits, under which subject, and what the trader sees afterwards. Leave
the recipient empty to only store submissions without sending mail.

### In code mode

There is no canvas to place inputs on, so a code-mode popup declares its fields
in the Form panel and you bind them yourself. Each field shows the key it is
stored under. Three hooks:

| Attribute                     | What it does                          |
| ----------------------------- | ------------------------------------- |
| `<div data-popup-form></div>` | Moves our own form block to that spot |
| `data-popup-field="key"`      | Binds your own input to that field    |
| `data-popup-action="submit"`  | Submits the form                      |

Without any of them the form block is rendered underneath your HTML. Every field
you bind yourself drops out of that block; bind them all and the block disappears
entirely, which makes your own submit button the only way to send it.

The Form panel shows a snippet with this popup's real keys, ready to paste.

## Buttons

A button does one of four things when clicked:

| Action           | What happens                                  |
| ---------------- | --------------------------------------------- |
| Open a link      | Sends the trader to a URL or an internal page |
| Close the popup  | Dismisses it                                  |
| Copy coupon code | Copies the attached coupon to the clipboard   |
| Submit the form  | Sends what the trader filled in               |

Attach a coupon under **Coupon** to use the copy action and the
`{{coupon_code}}` token.

## Whether it appears at all

A popup is content and nothing more. It appears because a rule names it, never
on its own, so a popup nothing points at is invisible however finished it looks.

The editor says so while you work. Beside the design, **Rules that show this**
lists every rule pointing at this popup and whether that rule is running, with
a link into each one. Underneath it sit the combinations that quietly do
nothing:

- Active, but no rule names it, or every rule that does is paused or out of its
  window.
- Not dismissible with nothing linking out of it. There is no close cross, the
  dim area does nothing, and a close button does nothing either, so a trader
  cannot get past it.
- A coupon attached that no button hands out, or a copy-code button with no
  coupon behind it.
- A coupon that no longer redeems. The popup still hands the code out, and the
  trader finds out at checkout.
- Fields with nobody emailed about them.

None of these stop a save. They are the things that are easy to miss and hard
to notice once it is live.

The popup list carries the same answer per row: how many rules name each popup
and how many of those are running, with a count of the active popups nothing
points at.

**Status** is what the rules are allowed to do with it:

| Status   | What it means                               |
| -------- | ------------------------------------------- |
| Draft    | Yours to work on. No rule can show it       |
| Active   | Ready. Rules that name it can show it       |
| Paused   | Held back, keeping the design and its rules |
| Archived | Out of use, kept for the record             |

## Showing it

**Rules** decides when a popup appears. A simple rule is a page, an audience, a
frequency and a date window. A flow is the same thing as a canvas of connected
steps, for when one message depends on another.

At most one popup shows per page view; when several match, the highest priority
wins. Frequency is enforced server side, so a trader cannot get around a once
ever or once per day rule by reloading.

## After it runs

**Analytics** per popup shows how often it was seen, dismissed, clicked and
converted. **Submissions** lists the answers, with a column per field.