Guides Block

The Guides block displays a collection of themed guides from your Tourismo content. Guides are separate from destination regions — use this block for guide directories, nested guides, or featured guides on your site.

Overview

Use the Guides block to:

• Show a directory of available guides
• Display guides in rows, grid, or carousel format
• Filter, sort, and customize which guides are shown
• Add a guides section to Single Guide pages (siblings, sub-guides, or top-level)
• Show featured guides only via the featuredOnly toggle
• Filter by a specific region or guide when not on a page with automatic context

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 Single Guide template page (required for navigation)
• viewType: Display style ("rows", "badge", "carousel", or "custom")
• featuredOnly: Show only featured guides from /guides/featured (boolean)
• tagFilters: Filter by specific tags
• tagCategory: Filter by tag category
• matchRecordsByTagCategory: Match records by tag category (boolean)
• filterRecordsByRegion: Filter by region or guide hierarchy (boolean)
• selectedRegionId: Manually select a specific region or guide to filter by
• regionFilteringMode: Choose how automatic context behaves (siblings, sub-records, or top-level)
• 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. Override the mount in itinerator/partials/stats.php (see Regions).

How it Works

• The block pulls guides from /guides (or /guides/featured when featuredOnly is enabled).
• Destination regions are not included — use the Regions block for those.
• Filtering basics:
  • On guide/region/itinerary/listing/event pages: Automatically filters relative to the current page context, with manual override available
  • On other pages: Choose a specific region or guide from the Filter by Region or Guide control
  • Manual override: Selecting a specific region or guide always takes precedence over automatic filtering

Filtering Modes (Guides Block)

When filterRecordsByRegion is enabled on a page with automatic context, the sidebar shows a Filtering Mode dropdown:

Manual selections always reset region_filtering_mode.

Related blocks on Single Guide pages

When Listings, Events, Itineraries, or Challenges blocks filter by the current guide (or a manually selected guide), the plugin sends filter[guide_id] to the API — not filter[region_id].

In the block editor on a Single Guide page, those collection blocks only offer Use current guide (automatic) plus manual region/guide picks. Region hierarchy modes (children / parents / lineage) are hidden there — they describe region geography, not guide membership, and do not expand to a parent region.

See also: Listings, Events, Itineraries, Challenges, Map.

Related Posts and taxonomies

WordPress posts can be tagged with Itinerator Guides (itin-guides), synced from /guides/list. On a Single Guide page, the Related Posts block can use Filter by Current Guide.

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

Upgrading to Guides (Regions / Guides API split)

Most WordPress sites never listed guides as regions. The usual pattern was destination regions in the Regions block, with tag filters keeping themed guides out of those lists. Guides were already first-class on apps / Next.js; this plugin release catches WordPress up.

What to expect

• Regions stay on /regions; guides live on /guides (numeric IDs unchanged)
• Existing region collection pages typically need no migration
• The plugin never used API filter[themed] / filter[not_themed] — tag filters were the WP pattern

Checklist (only if you used guides on WP before)

1. Deploy the plugin and API together, then clear Itinerator cache
2. If any Single page for a guide is still typed as Region, set Page Type to Single Guide (otherwise /regions/{slug} 404s)
3. If Related Posts used guide IDs under Itinerator Regions, re-tag those posts under Itinerator Guides (itin-guides) and use Filter by Current Guide
4. If a collection block manually selected a guide without selectedFilterType: "guide", re-pick it from the Guides section in the filter control

To start showing guides on WP (new capability): add a Guides block + Single Guide template page. See Getting Started.

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 "Guides" in the block inserter
4. Select "Itinerator Guides" from the results
5. Configure settings in the block sidebar
6. Set Linked Page to your Single Guide template page

Shortcode Usage

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

Basic Shortcode

[tourismo-guides linked_page_id="YOUR_PAGE_ID"]

With Options

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

Featured Guides

[tourismo-guides linked_page_id="YOUR_PAGE_ID" featured_only="true" view_type="carousel"]

Shortcode Options

Examples

Rows (Default) Example:

[tourismo-guides linked_page_id="123" show_name="true" show_description="true"]

Grid (Badge) Example:

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

Carousel Example:

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

Sub-guides of Current Guide:

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

Show Top-Level Guides Only:

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

Content Displayed

• Guide 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 filters by parent_region_id (API also accepts parent_guide_id as an alias), with client-side adjustments for top-level and sibling views.
• Hierarchy tree: Sibling/sub/top-level modes resolve against /guides/list?as_tree=true, not the regions tree.
• Manual Context: Providing selected_region_id bypasses automatic context and filters relative to the specified parent id.

Related Blocks

• Regions Block – Destination regions (non-guide)
• Map – Map overlays on Single Guide pages
• Related Posts – Posts tagged with Itinerator Guides
• Filter – Add content filtering
• Title – Add section headers