Guides
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:
| Mode | Description | Shortcode value | | --- | --- | --- | | Show siblings of current record (default) | Displays
guides that share the same parent as the current guide. If the current guide is top-level, only other top-level guides
are shown. | "" (attribute omitted) or show-siblings | | Show sub-records of current record | Displays direct children
of the current guide. | only-subregions | | Show top-level records only | Lists only guides without parents, regardless
of the current guide. | show-top-level | | Select a specific region or guide | Picks an exact parent and ignores
automatic context. | Set selected_region_id |
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].
| Resource | What filter[guide_id] means | | --- | --- | | Listings | Inside the guide's bounds and share the guide's
tags | | Events | Event locations inside the guide's bounds and share the guide's tags | | Itineraries | Stops/listings
inside the guide's bounds and share the guide's tags | | Challenges | Challenges with tasks targeting listings/events in
the guide (bounds + shared tags), or the guide itself |
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
| Attribute | Type | Default | Required | Description |
|--------------------------|----------|-------------|----------|---------------------------------------------| |
linked_page_id | string | "" | Yes | ID of your Single Guide template page | | view_type | string | "rows" | No |
Display style: "rows", "badge", "carousel" | | columns | string | "3" | No | Number of columns (1-4, grid/badge only) |
| featured_only | boolean | false | No | Show only featured guides | | 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 hierarchy | | selected_region_id | string | "" | No | Manually select a region or guide to filter by | |
region_filtering_mode | string | "" | No | show-siblings (default/blank), only-subregions, or show-top-level | | 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 guide hero images | | show_name | boolean | true | No | Show/hide guide 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 | |
show_stats | boolean | false | No | Load stats onto each card after page load | | stats_category | string | "" | No |
Stats category slug (blank = summary) |
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