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, showStats

When Show Stats is on, cards fetch stats after the page loads. Leave Stats Category blank for the default summary, or enter a category slug such as summary_custom_bcat. Custom templates can call $this->render_stats_placeholder($record) to include the same mount.

The mount is templates/partials/stats.php. Override it in the theme as itinerator/partials/stats.php, or per block as itinerator/partials/stats-regions.php. Keep the data-itin-stats* attributes so JS can fetch. Optional: a <template> for chip HTML, data-itin-stats-skip-icons to omit API SVGs, and data-itin-stats-icon-src with {stat_type} for theme image files.

Each painted item has data-stat-type (API slug, e.g. shopping) and itin-stats-count-{n}. Zero-count chips are hidden by default. Hide one type in a theme stylesheet:

.itin-stats-item[data-stat-type="shopping"] {
  display: none;
}

Theme icons from the project folder (example):

<div class="itin-stats"
     data-itin-stats="true"
     data-itin-stats-type="<?php echo esc_attr($stats_type); ?>"
     data-itin-stats-id="<?php echo esc_attr((string) $stats_id); ?>"
     data-itin-stats-category="<?php echo esc_attr($stats_category); ?>"
     data-itin-stats-skip-icons
     data-itin-stats-icon-src="<?php echo esc_attr(get_stylesheet_directory_uri() . '/assets/icons/{stat_type}.svg'); ?>">
  <template>
    <span class="itin-stats-item">
      <img class="itin-stats-icon" alt="">
      <span class="itin-stats-value"></span>
      <span class="itin-stats-name"></span>
    </span>
  </template>
</div>

Or remove a type after paint with the bubbling itin:stats:loaded event:

document.addEventListener("itin:stats:loaded", (event) => {
  event.target
    .querySelectorAll('.itin-stats-item[data-stat-type="shopping"]')
    .forEach((item) => item.remove());
});

How it Works

• The block pulls regions from your Tourismo content and displays them in the selected format.
• Region Filtering Basics:
  • On region/guide/itinerary/listing/event pages: Automatically filters relative to the current page context, with manual override available
  • On other pages: Manually choose a region or guide to filter by
  • Manual Override: Selecting a specific region or guide always takes precedence over automatic filtering
  • Destination guides are not listed by this block — use the Guides block for guide collections

Region Filtering Modes (Regions Block)

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

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

1. Open the block editor on any page or post
2. Click the + button to add a new block
3. Search for "Regions" in the block inserter
4. Select "Itinerator Regions" from the results
5. 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

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

• Guides Block – Themed guides (separate from destination regions)
• Region – Display a single region with map
• Filter – Add content filtering
• Title – Add section headers