# Itineraries Block

The **Itineraries block** displays a list, grid, or carousel of itineraries from your Tourismo content. Use it to create itinerary directories, featured sections, or itinerary carousels on your site. (For DMO-specific itineraries, use the DMO Itineraries block.)

## Overview

Use the Itineraries block to:
- Show a directory or catalog of available itineraries
- Display itineraries in a two-column row, grid, or carousel format
- Filter, sort, and customize which itineraries are shown
- Add a featured itineraries section to your homepage or region pages
- Filter by specific regions when not on a region/itinerary/listing/event page

## Block Features & Options

**Display Modes:**
- **Row (Default):** Two-column layout (image and content)
- **Grid (Badge):** Multi-column card grid (set `custom_template_name="badge"`)
- **Carousel:** Horizontal slider (set `custom_template_name="carousel"`)

**Layout Options:**
- `align`: Alignment of the block (left, center, right)
- `class_name`: Custom CSS class for additional styling

**Content & Filter Options:**
- `linked_page_id`: ID of your itinerary template page (**required for navigation**)
- `custom_template_name`: Use a custom template for display ("badge", "carousel", or your own)
- `tag_filters`: Filter by specific tags
- `tag_category`: Filter by tag category
- `match_records_by_tag_category`: Match records by tag category (boolean)
- `filter_records_by_region`: Filter itineraries by region (boolean)
- `selected_region_id`: Manually select a specific region to filter by (string; only available when not on region/itinerary/listing/event pages)
- `sort_by`: Sort order (e.g., "name", "default")
- `button_text`: Text for the action button

**Display Toggles:**
- `show_hero`, `show_name`, `show_subtitle`, `show_counts`, `show_region`, `show_short_description`, `show_description`, `show_tags`, `show_button`

## How it Works

- The block pulls itineraries from your Tourismo content and displays them in the selected format.
- Filtering, sorting, and display options can be set in the block editor or via shortcode attributes.
- The block is styled with `.itin` and `.itinerator-itineraries` classes for easy targeting.
- Clicking an itinerary navigates to the linked template page (set via `linked_page_id`).

**Region Filtering:**
- **On region/itinerary/listing/event pages:** Automatically filters by the current page's region, but allows manual override
- **On other pages:** Allows manual selection of a specific region to filter by
- **Manual Override:** When a specific region is selected, it takes precedence over automatic filtering on all page types

### Region Filtering Modes

When `filter_records_by_region` is enabled on a page that already has regional context (region, itinerary, listing, or event templates), the sidebar shows a **Region Filtering Mode** dropdown. It maps to the `region_filtering_mode` shortcode attribute:

| Mode | Description | Shortcode value |
| --- | --- | --- |
| Use current page region (automatic) | Default behavior; uses only the current page's region | `""` (attribute omitted) |
| Use current region and children (descendants) | Includes the current region plus every descendant region | `"current-and-children"` |
| Use current region and parents (ancestors) | Includes the current region plus every ancestor region | `"current-and-parents"` |
| Use current region and entire lineage | Combines ancestors, current region, and descendants | `"current-and-lineage"` |
| Select a specific region | Picks an exact region regardless of page context | Set `selected_region_id` |

Manual selection always clears `region_filtering_mode` and will work on any page, even if there is no automatic region context available.

## 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 "Itineraries"** in the block inserter
4. **Select "Itinerator Itineraries"** 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-itineraries linked_page_id="YOUR_PAGE_ID"]
```

### With Options
```
[tourismo-itineraries linked_page_id="YOUR_PAGE_ID" show_hero="true" show_name="true" show_button="true" align="center"]
```

### Shortcode Options

| Attribute                | Type     | Default     | Required | Description                                 |
|--------------------------|----------|-------------|----------|---------------------------------------------|
| linked_page_id           | string   | ""          | Yes      | ID of your itinerary template page          |
| custom_template_name     | string   | ""          | No       | Use a custom template for display           |
| 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                            |
| selected_region_id       | string   | ""          | No       | Manually select a region to filter by       |
| region_filtering_mode    | string   | ""          | No       | Controls automatic region context when a current page region exists (`current-and-children`, `current-and-parents`, `current-and-lineage`) |
| class_name               | string   | ""          | No       | Custom CSS class                            |
| align                    | string   | ""          | No       | Alignment (left, center, right)             |
| button_text              | string   | "Explore"   | No       | Text for the action button                  |
| sort_by                  | string   | "default"   | No       | Sort order                                  |
| show_hero                | boolean  | true        | No       | Show/hide hero images                       |
| show_name                | boolean  | true        | No       | Show/hide itinerary name                    |
| show_subtitle            | boolean  | false       | No       | Show/hide subtitle                          |
| show_counts              | boolean  | true        | No       | Show/hide stop/day counts                   |
| show_region              | boolean  | true        | No       | Show/hide region info                       |
| show_short_description   | boolean  | false       | No       | Show/hide short description                 |
| show_description         | boolean  | false       | No       | Show/hide full description                  |
| show_tags                | boolean  | false       | No       | Show/hide tags                              |
| show_button              | boolean  | true        | No       | Show/hide action button                     |

### Examples

**Simple Itinerary List:**
```
[tourismo-itineraries linked_page_id="123" show_name="true" show_description="true" show_region="true" show_counts="true"]
```

**Grid (Badge) Example:**
```
[tourismo-itineraries linked_page_id="123" custom_template_name="badge" show_hero="true" show_name="true" show_button="true"]
```

**Carousel Example:**
```
[tourismo-itineraries linked_page_id="123" custom_template_name="carousel" show_hero="true" show_name="true" show_button="true"]
```

**Manual Region Selection:**
```
[tourismo-itineraries linked_page_id="123" filter_records_by_region="true" selected_region_id="3"]
```

**Current Region Plus Children:**
```
[tourismo-itineraries linked_page_id="123" filter_records_by_region="true" region_filtering_mode="current-and-children"]
```

**Region-Specific Itineraries:**
Note: Must be placed on a region template or other single page template.
```
[tourismo-itineraries linked_page_id="123" show_short_description="true" filter_records_by_region="true"]
```

## Content Displayed

- Itinerary name, subtitle, and hero image
- Short and/or full description
- Region information
- Stop and day counts
- Tags and categories
- Featured status (property available on itinerary objects)
- Action button (if enabled)

**Layout options:**
- Row (two column, default)
- Grid (multi-column cards, set custom_template_name="badge")
- Carousel (horizontal slider, set custom_template_name="carousel")

## Related Blocks

- [Itinerary](itinerary.md) – Display a single itinerary with map
- [Filter](../content-blocks/filter.md) – Add content filtering
- [Title](../content-blocks/title.md) – Add section headers