# 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

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

| 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](../content-blocks/region.md) – Display a single region with map
- [Filter](../content-blocks/filter.md) – Add content filtering
- [Title](../content-blocks/title.md) – Add section headers