Regions Block

The Regions block displays a collection of regions from your Tourismo content. Use it to create region directories, showcase neighboring areas, or display subregions on your site.

Overview

Use the Regions block to:

Show a directory of available regions
Display regions in rows, grid, or carousel format
Filter, sort, and customize which regions are shown
Add a regions section to region, city, or category pages
Filter by specific regions when not on a region/itinerary/listing/event page

Block Features & Options

Display Modes:

Rows (Default): Two-column layout (image and content)
Grid (Badge): Multi-column card grid (set viewType="badge")
Carousel: Horizontal slider (set viewType="carousel")
Custom Template: Use custom template override

Layout Options:

columns: Number of columns (1-4, default: 3; applies to grid/badge mode)
align: Alignment of the block (left, center, right, wide)
className: Custom CSS class for additional styling

Content & Filter Options:

linkedPageId: ID of your region template page (required for navigation)
viewType: Display style ("rows", "badge", "carousel", or "custom")
tagFilters: Filter by specific tags
tagCategory: Filter by tag category
matchRecordsByTagCategory: Match records by tag category (boolean)
filterRecordsByRegion: Filter regions by region (boolean)
selectedRegionId: Manually select a specific region to filter by (string; only available when not on region/itinerary/listing/event pages)
regionFilteringMode: Choose how automatic region context behaves (siblings, subregions, or top-level)
onlyShowSubregions: Legacy toggle no longer visible (automatically maps to regionFilteringMode="only-subregions")
sortBy: Sort order (e.g., "name", "default")
buttonText: Text for the action button
customTemplateName: Use a custom template for display

Display Toggles:

showHero, showName, showSubtitle, showShortDescription, showDescription, showTags, showChallengeCount, showButton, showRelatedItineraries

How it Works

The block pulls regions from your Tourismo content and displays them in the selected format.
Region Filtering Basics:
- On region/itinerary/listing/event pages: Automatically filters relative to the current page's region, but still allows manual override
- On other pages: Lets you manually choose the region to filter by
- Manual Override: Selecting a specific region always takes precedence over automatic filtering

Region Filtering Modes (Regions Block)

When filterRecordsByRegion is enabled on a page that already has regional context, the sidebar now shows a Region Filtering Mode dropdown:

Mode	Description	Shortcode value
Show siblings of current region (default)	Displays regions that share the same parent as the current region. If the current region is top-level, only other top-level regions are shown.	`""` (attribute omitted) or `show-siblings`
Show subregions of current region	Displays direct children of the current region. Replaces the old `onlyShowSubregions` toggle.	`only-subregions`
Show top-level regions only	Lists only regions without parents, regardless of the current region.	`show-top-level`
Select a specific region	Picks an exact region and ignores automatic context.	Set `selected_region_id`

Manual selections always reset region_filtering_mode. Existing blocks that previously relied on only_show_subregions remain compatible—the attribute is still read and transparently maps to region_filtering_mode="only-subregions".

Filtering, sorting, and display options can be set in the block editor or via shortcode attributes.
The block is styled with .itin and .itinerator-regions classes for easy targeting.
Clicking a region navigates to the linked template page (set via linkedPageId).

How to Add & Configure

Open the block editor on any page or post
Click the + button to add a new block
Search for "Regions" in the block inserter
Select "Itinerator Regions" 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-regions linked_page_id="YOUR_PAGE_ID"]

With Options

[tourismo-regions linked_page_id="YOUR_PAGE_ID" view_type="badge" columns="3" show_hero="true" show_name="true" align="center"]

Shortcode Options

Attribute	Type	Default	Required	Description
linked_page_id	string	""	Yes	ID of your region template page
view_type	string	"rows"	No	Display style: "rows", "badge", "carousel"
columns	string	"3"	No	Number of columns (1-4, grid/badge only)
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 (auto-enabled if onlyShowSubregions is set)
selected_region_id	string	""	No	Manually select a region to filter by
region_filtering_mode	string	""	No	Choose automatic mode: `show-siblings` (default/blank), `only-subregions`, or `show-top-level`
only_show_subregions	boolean	true	No	Legacy attribute preserved for backward compatibility; maps to `region_filtering_mode="only-subregions"`
sort_by	string	"default"	No	Sort order
button_text	string	"Explore"	No	Text for the action button
custom_template_name	string	""	No	Use a custom template for display
class_name	string	""	No	Custom CSS class
align	string	"wide"	No	Alignment (left, center, right, wide)
show_hero	boolean	true	No	Show/hide region hero images
show_name	boolean	true	No	Show/hide region name
show_subtitle	boolean	true	No	Show/hide subtitle
show_short_description	boolean	true	No	Show/hide short description
show_description	boolean	true	No	Show/hide full description
show_tags	boolean	false	No	Show/hide tags
show_challenge_count	boolean	false	No	Show/hide challenge count
show_button	boolean	false	No	Show/hide action button
show_related_itineraries	boolean	false	No	Show/hide related itineraries

Examples

Rows (Default) Example:

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

Grid (Badge) Example:

[tourismo-regions linked_page_id="123" view_type="badge" columns="3" show_hero="true" show_name="true"]

Carousel Example:

[tourismo-regions linked_page_id="123" view_type="carousel" show_hero="true" show_name="true"]

Manual Region Selection Example:

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

Subregions of Current Region:

[tourismo-regions linked_page_id="123" filter_records_by_region="true" region_filtering_mode="only-subregions" show_short_description="true"]

Show Top-Level Regions Only:

[tourismo-regions linked_page_id="123" filter_records_by_region="true" region_filtering_mode="show-top-level"]

Show Current Region Plus Siblings (Explicit):

[tourismo-regions linked_page_id="123" filter_records_by_region="true" region_filtering_mode="show-siblings"]

Content Displayed

Region name, subtitle, and hero image
Short and/or full description
Challenge count (if enabled)
Tags and categories
Related itineraries (if enabled)
Action button (if enabled)

Layout options:

Rows (two column, default)
Grid (multi-column cards, set viewType="badge")
Carousel (horizontal slider, set viewType="carousel")
Custom template (set customTemplateName)

Technical Implementation Notes:

Query Key Logic: The block always filters by parent_region_id, with client-side adjustments that ensure top-level and sibling views stay accurate.
Automatic Context: region_filtering_mode drives whether the API request targets siblings, subregions, or top-level regions.
Manual Context: Providing selected_region_id bypasses automatic context and filters relative to the specified region, regardless of mode.
Backward Compatibility: only_show_subregions is still read and simply toggles region_filtering_mode="only-subregions" behind the scenes.

Related Blocks

Region – Display a single region with map
Filter – Add content filtering
Title – Add section headers