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_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]`.

A typical home page:

```
[viator_hero]
[viator_top_destinations]
[viator_top_tours]
[viator_top_attractions]
[viator_browse_activities]
[viator_testimonials]
[viator_faq]
```

---

## `[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_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.