# 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](regions.md)).

## 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](regions.md) 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](listings.md), [Events](events.md), [Itineraries](itineraries.md), [Challenges](challenges.md), [Map](../content-blocks/map.md).

### 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](../../getting-started/getting-started.md).

## 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](regions.md) – Destination regions (non-guide)
- [Map](../content-blocks/map.md) – Map overlays on Single Guide pages
- [Related Posts](related-posts.md) – Posts tagged with Itinerator Guides
- [Filter](../content-blocks/filter.md) – Add content filtering
- [Title](../content-blocks/title.md) – Add section headers