Banners and teasers

A sofa sale belongs on top of the sofa page, and a pointer to the armchairs among the sofas.

A banner is a rule's effect place, not an entity of the catalog, so it gets the rule's condition, window, order, draft and trace. The home store's rule home/sofa-sale places two on the sofa page wohnen/sofas (wohnen: living):

{
    "id": "home/sofa-sale",
    "when": { "category": { "is": "wohnen/sofas" } },
    "then": {
        "place": [
            {
                "slot": "top",
                "banner": {
                    "kind": "banner",
                    "title": { "de": "Sofas im Angebot", "en": "Sofas on sale" },
                    "link": { "to": "category:wohnen/sofas", "filters": { "on_sale": true } }
                }
            },
            {
                "slot": "grid",
                "position": 4,
                "banner": {
                    "kind": "teaser",
                    "title": {
                        "de": "Sessel aus Leder, Samt und Stoff",
                        "en": "Armchairs in leather, velvet and fabric"
                    },
                    "link": { "to": "category:wohnen/sessel" }
                }
            }
        ]
    }
}

The banner leads to the sofas on sale, the teaser before the fourth sofa to the armchairs (Sessel). Each also carries a line of text and an image with the words that stand for it. The answer brings them as placements (Category pages).

Reference: place · link · image

Where a banner standsCopy Anchor Link

slot says where a banner stands, and on which page of the results:

kind says how wide: a banner spans the results, a teaser is the size of a tile. A banner is not a hit, so it changes no total, facet or order, and paging stays as it is. The search box shows no banners, and neither does an answer that redirects or a count_only one.

Reference: slot · position · kind

When banners competeCopy Anchor Link

The rule order decides between banners. A preview takes any release files, so you can try a clash without a draft. Put a teaser for the sofa guide, "Welches Sofa passt?" (which sofa fits?), on top of the order, before the fourth sofa:

jq '.rules |= [{id: "sofa-guide", description: "Sofa guide before the fourth sofa",
      when: {category: {is: "wohnen/sofas"}},
      then: {place: [{slot: "grid", position: 4, banner: {kind: "teaser", title: "Welches Sofa passt?"}}]}}] + .
    | {url: "/wohnen/sofas", files: {"rules.json": tojson}}' tests/fixtures/home/rules.json \
  | curl -s -H "Authorization: Bearer $key" -H 'Content-Type: application/json' -d @- $api/preview/page \
  | jq -r '.results.trace.steps[] | select(.step == "rules") | .rules[].effects[]? | select(.slot == "grid")
      | "\(.target): asked \(.position), placed \(.placed), \(.reason // .outcome)"'

teaser "Welches Sofa passt?": asked 4, placed 4, applied
teaser "Sessel aus Leder, Samt und Stoff": asked 4, placed 5, position 5 is past the last of 4 tiles

The new rule is higher, so its teaser takes position 4. The armchair teaser moves to the next free position, 5, which lies past the last of the four sofas, so the page leaves it out.

Top and bottom banners of several rules stand in rule order. A page shows at most 8 banners, the first in rule order, and the trace says why it left any out. The panel marks a banner that lost its position In conflict.

Reference: placements_per_page · placed

Add a bannerCopy Anchor Link

A new banner is a new rule at the top of the order, and it waits in a draft until you publish it. A campaign's window is its rule's schedule (Rules).

draft=$(curl -s -X POST -H "Authorization: Bearer $key" -H 'Content-Type: application/x-ndjson' \
  --data-binary @tests/fixtures/home/catalog.jsonl "$api/imports?name=catalog.jsonl" | jq -r .import.id)
version=$(curl -s -H "Authorization: Bearer $key" $api/imports/$draft | jq -r .version)
jq -n --arg version "$version" '{version: $version, name: "Sofa guide among the sofas", fields: {
    when: {trigger: {kind: "category", category: "wohnen/sofas"}},
    then: {place: [{slot: "grid", position: 2, banner: {kind: "teaser",
      title: {de: "Welches Sofa passt?", en: "Which sofa fits?"}, link: {to: "content:guide-sofa-finden"}}}]}}}' \
  | curl -s -H "Authorization: Bearer $key" -H 'Content-Type: application/json' -d @- $api/imports/$draft/rules \
  | jq -r '.rules.rules[:2][] | "\(.position). \(.summary)"'

1. Places teaser "Welches Sofa passt?" at 2 on "Sofas"
2. Places banner "Sofas im Angebot" on top, places teaser "Sessel aus Leder, Samt und Stoff" at 4 on "Sofas"

curl -s -H "Authorization: Bearer $key" $api/imports/$draft \
  | jq '{url: "/wohnen/sofas", files}' \
  | curl -s -H "Authorization: Bearer $key" -H 'Content-Type: application/json' -d @- $api/preview/page \
  | jq -c '.results.placements[] | del(.text, .image, .link)'

{"slot":"top","kind":"banner","title":"Sofas im Angebot","rule":"home/sofa-sale"}
{"slot":"grid","position":2,"kind":"teaser","title":"Welches Sofa passt?","rule":"sofa-guide-among-the-sofas"}
{"slot":"grid","position":4,"kind":"teaser","title":"Sessel aus Leder, Samt und Stoff","rule":"home/sofa-sale"}

curl -s -X POST -H "Authorization: Bearer $key" $api/imports/$draft/publish | jq -r .next

curl -s -X DELETE -H "Authorization: Bearer $key" $api/imports/$draft | jq -r .state

discarded

Reference: POST .../rules · POST /api/v1/preview/page

NextCopy Anchor Link

• Category pages: the placements an answer carries and where a storefront draws them.
• Rules: conditions, schedules and the rule order.
• Pages and their filters: the filters and sorting of the same sofa page.