Add viator-collector plugin (Hop On Hop Off front-end reskin)
Consolidate the plugin into the TourWebsite repository (its separate nested git repo has been removed). Includes the full new-design reskin: scoped design stylesheet, SVG icon sprite, rebuilt listing/single/section templates, and homepage hero/FAQ/testimonials shortcodes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01J4hNL1PSHxXbu94SCenpKj
This commit is contained in:
195
viator-collector/SHORTCODES.md
Normal file
195
viator-collector/SHORTCODES.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user