hoponhopofftickets/viator-collector/SHORTCODES.md

# Viator Collector — Shortcode Reference

All landing-page sections are shortcodes. Drop them into a **Shortcode block**, a
**Custom HTML block**, or a page template. Every section is wrapped in a
`.vc-app` container and styled by a single scoped stylesheet
(`assets/css/vc-design.css`), so the "Hop On Hop Off" design cannot leak into the
theme. Icons come from a bundled SVG sprite (no external icon library); the
listing/single/section assets load only on pages that use them.

## Quick reference

| Shortcode | Renders | Data source |
|---|---|---|
| `[viator_hero]` | Booking hero (location / date / seat) | `viator_destination` terms |
| `[viator_top_destinations]` | Rail of destination cards | `viator_destination` terms |
| `[viator_top_tours]` | Rail of tour cards | `viator_tour` posts |
| `[viator_top_attractions]` | Rail of tour cards | `viator_tour` posts |
| `[viator_browse_activities]` | Rail of tour cards | `viator_tour` posts |
| `[viator_bus_tours]` | "Open Top Bus Tours" promo + 4-up card grid | `viator_tour` posts |
| `[viator_about]` | Static "About / Memorable" block + stat counters | Shortcode attributes |
| `[viator_articles]` | Rail of latest blog-post cards | `post` posts |
| `[viator_faq]` | FAQ accordion | Shortcode `items` / `vc_faq_items` filter |
| `[viator_testimonials]` | Testimonials marquee | `vc_testimonials` filter |

`[viator_hero_slider]` is kept as a **back-compat alias** for `[viator_hero]`.

Home page matching the design mockup (`new front/index.html`), top to bottom:

```
[viator_hero image_id="125304"]
[viator_top_destinations]
[viator_bus_tours image_id="125310"]
[viator_top_tours]
[viator_about image_id="125311"]
[viator_testimonials]
[viator_articles]
[viator_faq]
```

Heavy decorative images (hero photo, open-top bus, isometric bus) are **not
bundled** — upload them in **Media** and pass the attachment `image_id` (exactly
like `[viator_hero image_id="…"]`). Icons and tiny decorations are inline SVG.

---

## `[viator_hero]`

Full-width booking hero: a Location / Date / Seat form that submits (GET) to the
tours archive, pre-filtering by the chosen destination.

| Attribute | Default | Description |
|---|---|---|
| `title` | `Set out on the journey.` | Hero heading. |
| `eyebrow` | `Tour & Travel` | Small pill above the heading. |
| `image` | *(setting / bundled)* | Background image URL. Falls back to the **Hero image** setting, then a bundled image. |

```
[viator_hero title="Explore the city your way." image="https://example.com/hero.jpg"]
```

---

## Shared attributes (tour rails)

`[viator_top_tours]`, `[viator_top_attractions]` and `[viator_browse_activities]`
all select tours the same way and render a horizontally-scrolling rail of cards.

| Attribute | Default | Description |
|---|---|---|
| `limit` | `8` | How many tours to show. |
| `ids` | — | Post IDs, comma-separated. **Order is preserved.** |
| `codes` | — | Viator product codes, e.g. `5010SYDNEY,2050ICON`. |
| `destination` | — | Destination term slug(s), e.g. `orlando,miami`. |
| `tag` | — | Activity/tag term slug(s), e.g. `theme-parks`. |
| `orderby` | `rating` | `rating` \| `price` (asc) \| `date` \| `rand`. Ignored when `ids` is used. |
| `title` | varies | Section heading (`<br>` allowed). |
| `lead` | varies | Sub-heading paragraph. |

```
[viator_top_tours limit="12" destination="london"]
[viator_top_tours ids="482,517,690" title="Editor's Picks"]
[viator_top_attractions codes="5010SYDNEY,2050ICON"]
```

> **`orderby="rating"`:** WordPress drops posts lacking the meta key when ordering
> by it, so if that would empty the section it falls back to newest-first.

---

## `[viator_top_destinations]`

Rail of destination-term cards; each links to that destination's tour archive.

| Attribute | Default | Description |
|---|---|---|
| `limit` | `8` | Number of destinations. |
| `orderby` | `count` | `count` (most tours first) or `name`. |
| `ids` | — | Term IDs, comma-separated. **Order preserved.** |
| `slugs` | — | Term slugs, e.g. `london,paris,sydney`. |
| `title` | `Where you<br>wanna go?` | Heading (`<br>` allowed). |
| `lead` | *(default copy)* | Sub-heading. |
| `link_text` | `View tours` | "See all" action text. |

Card image resolution: the term's own image (Viator Destinations → edit → Image),
otherwise the first tour photo in that destination (cached). Empty destinations
are hidden automatically.

---

## `[viator_bus_tours]`

The "Open Top Bus Tours…" promo block (route line, headline, "See all", a chip,
a bus illustration and note) followed by a 4-up grid of tour cards. Selects tours
with the **same attributes as the tour rails** (`ids` / `codes` / `destination` /
`tag` / `limit` / `orderby`), plus:

| Attribute | Default | Description |
|---|---|---|
| `title` | `Open Top<br>Bus Tours…` | Promo headline (`<br>` allowed). |
| `note` | *(default copy)* | Paragraph under the headline. |
| `chip` | `Very Fun!` | Small accent chip. |
| `image_id` | — | **Media attachment ID** of the open-top bus illustration. |
| `image` | — | …or a direct image URL (use `image_id` when possible). |

```
[viator_bus_tours image_id="125310" tag="hop-on-hop-off" limit="4"]
[viator_bus_tours ids="482,517,690,701"]
```

---

## `[viator_about]`

Static "About" marketing block: headline with an accent chip, a paragraph, four
stat counters and a decorative isometric bus. All copy is editable.

| Attribute | Default | Description |
|---|---|---|
| `title` | `Hop On Hop Off` | Headline. |
| `highlight` | `Memorable` | Accent chip appended to the headline. |
| `text` | *(default copy)* | Paragraph. |
| `button_text` | `About us` | Button label. |
| `button_url` | *(tours archive)* | Button link. |
| `image_id` | — | **Media attachment ID** of the isometric bus illustration. |
| `image` | — | …or a direct image URL. |
| `stats` | *(4 defaults)* | `25+|Years Experience;;500+|Tours Conducted` — `|` separates number from label, `;;` separates stats. A trailing `+` is styled. |

```
[viator_about image_id="125311" stats="25+|Years Experience;;500+|Tours Conducted;;430+|Tours this Year;;15+|Different Tours"]
```

---

## `[viator_articles]`

A rail of the latest blog posts styled as the design's "Latest Articles" cards
(featured image, relative time, title, excerpt → links to the post).

| Attribute | Default | Description |
|---|---|---|
| `title` | `Latest<br>Articles` | Heading (`<br>` allowed). |
| `lead` | *(default copy)* | Sub-heading. |
| `limit` | `8` | Number of posts. |
| `category` | — | Restrict to a category slug. |
| `view_all` | *(posts page)* | "See all" link; defaults to the blog page. |

Cards use each post's **featured image**; set one so the card isn't blank.

```
[viator_articles limit="8" category="travel-tips"]
```

---

## `[viator_faq]`

FAQ accordion.

| Attribute | Default | Description |
|---|---|---|
| `title` | `FAQ's` | Heading. |
| `lead` | *(default copy)* | Sub-heading. |
| `items` | *(defaults)* | `Question|Answer;;Question 2|Answer 2` — `|` separates Q from A, `;;` separates pairs. |

Without `items`, a sensible default set is used. Override globally in code:

```php
add_filter( 'vc_faq_items', function ( $items ) {
    return array(
        array( 'q' => 'Where do the buses depart?', 'a' => 'From the central stop on Main St.' ),
        array( 'q' => 'Are tickets refundable?',    'a' => 'Yes, up to 24 hours before start.' ),
    );
} );
```

```
[viator_faq items="Is it online?|Yes, fully.;;Can I cancel?|Up to 24h before."]
```

---

## `[viator_testimonials]`

Animated marquee of traveller quotes.

| Attribute | Default | Description |
|---|---|---|
| `title` | `Your Comments` | Heading. |
| `lead` | *(default copy)* | Sub-heading. |

Content comes from the `vc_testimonials` filter (each item:
`name`, `role`, `text`, `avatar`, optional `size` = `lg`\|`sm`):

```php
add_filter( 'vc_testimonials', function ( $items ) {
    $items[] = array(
        'name'   => 'Jane Doe',
        'role'   => 'London Tour',
        'text'   => 'Absolutely loved it!',
        'avatar' => 'https://example.com/jane.jpg',
        'size'   => 'lg',
    );
    return $items;
} );
```

---

## Listing & single-tour pages

These are **templates, not shortcodes** — they render automatically:

- **Tours archive:** `/tours/` (filter bar, sort, search, server pagination)
- **Destination archive:** `/tour-destination/{slug}/`
- **Single tour:** `/tours/{slug}/`

The archive banner text and hero image are filterable:

```php
add_filter( 'vc_listing_title',    fn() => 'Discover London Tours' );
add_filter( 'vc_listing_subtitle', fn() => 'Hand-picked experiences.' );
add_filter( 'vc_hero_image_url',   fn( $url ) => $url );
```

Useful archive query strings:

```
/tours/?bestdeal=1
/tours/?freecancel=1
/tours/?sellout=1
/tours/?dest=london&price=50-150&sort=price_asc
```

Filtering, sorting and pagination are **server-side** (GET params), so results are
shareable and crawlable.

---

## Notes & gotchas

- **One scoped stylesheet.** All surfaces use `assets/css/vc-design.css`, scoped
  to `.vc-app`. No Swiper, no Lucide, no external icon CDN.
- **Icons** are a bundled SVG sprite (`assets/icons/sprite.svg`), printed once per
  page and referenced with `<use href="#i-…">`.
- **Badges need flags.** `_vc_flags` is only populated on tours crawled after that
  field was added — older tours may show no badge until the next full sync.
- **`max_travelers`** only appears once a tour's full detail has been fetched.
- If a section has no data it renders **nothing**, rather than an empty shell.