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+

[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

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

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):

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:

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.