Itineraries Block

The Itineraries block displays a list, grid, or carousel of itineraries from your Tourismo content. Use it to create itinerary directories, featured sections, or itinerary carousels on your site. (For DMO-specific itineraries, use the DMO Itineraries block.)

Overview

Use the Itineraries block to:

Show a directory or catalog of available itineraries
Display itineraries in a two-column row, grid, or carousel format
Filter, sort, and customize which itineraries are shown
Add a featured itineraries section to your homepage or region pages
Filter by specific regions when not on a region/itinerary/listing/event page

Block Features & Options

Display Modes:

Row (Default): Two-column layout (image and content)
Grid (Badge): Multi-column card grid (set custom_template_name="badge")
Carousel: Horizontal slider (set custom_template_name="carousel")

Layout Options:

align: Alignment of the block (left, center, right)
class_name: Custom CSS class for additional styling

Content & Filter Options:

linked_page_id: ID of your itinerary template page (required for navigation)
custom_template_name: Use a custom template for display ("badge", "carousel", or your own)
tag_filters: Filter by specific tags
tag_category: Filter by tag category
match_records_by_tag_category: Match records by tag category (boolean)
filter_records_by_region: Filter itineraries by region (boolean)
selected_region_id: Manually select a specific region to filter by (string; only available when not on region/itinerary/listing/event pages)
sort_by: Sort order (e.g., "name", "default")
button_text: Text for the action button

Display Toggles:

show_hero, show_name, show_subtitle, show_counts, show_region, show_short_description, show_description, show_tags, show_button, show_stats

When Show Stats is on, cards fetch stats after the page loads. Leave Stats Category blank for the default summary (legs and stops), or enter a category slug such as summary_custom_bcat. Custom templates can call $this->render_stats_placeholder($record) to include the same mount. Override the mount in itinerator/partials/stats-itineraries.php (see Regions).

How it Works

The block pulls itineraries from your Tourismo content and displays them in the selected format.
Filtering, sorting, and display options can be set in the block editor or via shortcode attributes.
The block is styled with .itin and .itinerator-itineraries classes for easy targeting.
Clicking an itinerary navigates to the linked template page (set via linked_page_id).

Region / Guide Filtering:

On region pages: Automatically filters by the current region; children/parents/lineage modes are available
On guide pages: Automatically filters by guide membership (filter[guide_id] — itineraries whose stops/listings sit inside the guide's bounds and share its tags). Hierarchy modes are hidden; parent regions are not included
On itinerary/listing/event pages: Automatically filters by the associated region
On other pages: Manually select a region or guide
Manual override: Selecting a specific region or guide always takes precedence

Filtering Modes

When filter_records_by_region is enabled, the sidebar Filtering Mode dropdown maps to region_filtering_mode / selected_region_id.

On Single Region pages (and other non-guide automatic context)

Mode	Description	Shortcode value
Use current page region (automatic)	Uses only the current page's region	`""` (attribute omitted)
Use current region and children (descendants)	Current region plus every descendant	`"current-and-children"`
Use current region and parents (ancestors)	Current region plus every ancestor	`"current-and-parents"`
Use current region and entire lineage	Ancestors, current region, and descendants	`"current-and-lineage"`
Select a specific region or guide	Exact pick; ignores automatic context	Set `selected_region_id`

On Single Guide pages

Mode	Description	Shortcode value
Use current guide (automatic)	Guide membership: bounds + shared tags (`filter[guide_id]`)	`""` (attribute omitted)
Select a specific region or guide	Exact pick; ignores automatic context	Set `selected_region_id`

Guide vs region: Guide membership is not the same as "itineraries assigned to the parent region." Hierarchy modes are not offered on guide pages because they describe region geography, not guide membership.

Manual selection always clears region_filtering_mode and works on any page.

How to Add & Configure

Open the block editor on any page or post
Click the + button to add a new block
Search for "Itineraries" in the block inserter
Select "Itinerator Itineraries" from the results
Configure settings in the block sidebar

Shortcode Usage

Important: The linked_page_id attribute is required for correct navigation. Always include it in your shortcode.

Basic Shortcode

[tourismo-itineraries linked_page_id="YOUR_PAGE_ID"]

With Options

[tourismo-itineraries linked_page_id="YOUR_PAGE_ID" show_hero="true" show_name="true" show_button="true" align="center"]

Shortcode Options

Attribute	Type	Default	Required	Description
linked_page_id	string	""	Yes	ID of your itinerary template page
custom_template_name	string	""	No	Use a custom template for display
tag_filters	array	[]	No	Filter by specific tags
tag_category	string	""	No	Filter by tag category
match_records_by_tag_category	boolean	false	No	Match records by tag category
filter_records_by_region	boolean	true	No	Filter by region or guide
selected_region_id	string	""	No	Manually select a region or guide to filter by
region_filtering_mode	string	""	No	Region hierarchy modes when automatic region context applies (`current-and-children`, `current-and-parents`, `current-and-lineage`). Not used on Single Guide pages (automatic guide membership only).
class_name	string	""	No	Custom CSS class
align	string	""	No	Alignment (left, center, right)
button_text	string	"Explore"	No	Text for the action button
sort_by	string	"default"	No	Sort order
show_hero	boolean	true	No	Show/hide hero images
show_name	boolean	true	No	Show/hide itinerary name
show_subtitle	boolean	false	No	Show/hide subtitle
show_counts	boolean	true	No	Show/hide stop/day counts
show_region	boolean	true	No	Show/hide region info
show_short_description	boolean	false	No	Show/hide short description
show_description	boolean	false	No	Show/hide full description
show_tags	boolean	false	No	Show/hide tags
show_button	boolean	true	No	Show/hide action button
show_stats	boolean	false	No	Load stats onto each card after page load
stats_category	string	""	No	Stats category slug (blank = summary)

Examples

Simple Itinerary List:

[tourismo-itineraries linked_page_id="123" show_name="true" show_description="true" show_region="true" show_counts="true"]

Grid (Badge) Example:

[tourismo-itineraries linked_page_id="123" custom_template_name="badge" show_hero="true" show_name="true" show_button="true"]

Carousel Example:

[tourismo-itineraries linked_page_id="123" custom_template_name="carousel" show_hero="true" show_name="true" show_button="true"]

Manual Region Selection:

[tourismo-itineraries linked_page_id="123" filter_records_by_region="true" selected_region_id="3"]

Current Region Plus Children:

[tourismo-itineraries linked_page_id="123" filter_records_by_region="true" region_filtering_mode="current-and-children"]

Region-Specific Itineraries: Note: Must be placed on a region template or other single page template.

[tourismo-itineraries linked_page_id="123" show_short_description="true" filter_records_by_region="true"]

Content Displayed

Itinerary name, subtitle, and hero image
Short and/or full description
Region information
Stop and day counts
Tags and categories
Featured status (property available on itinerary objects)
Action button (if enabled)

Layout options:

Row (two column, default)
Grid (multi-column cards, set custom_template_name="badge")
Carousel (horizontal slider, set custom_template_name="carousel")

Related Blocks

Itinerary – Display a single itinerary with map
Filter – Add content filtering
Title – Add section headers