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

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.