# Listings Block

The **Listings block** displays a directory, grid, or carousel of business listings from your Tourismo content. Use it to create business directories, featured listings sections, or listing carousels on your site.

## Overview

Use the Listings block to:
- Show a directory of businesses or locations
- Display listings in directory, tile, or carousel format
- Filter, sort, and customize which listings are shown
- Add a listings 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:**
- **Directory (Alpha):** Multi-column alphabetical list (viewType="alpha")
- **Tiles (Badge):** Grid of cards (viewType="badge")
- **Carousel:** Horizontal slider (viewType="carousel")

**Layout Options:**
- `columns`: Number of columns (1-4, default: 3; applies to grid/tile mode)
- `align`: Alignment of the block (left, center, right, wide)
- `className`: Custom CSS class for additional styling

**Content & Filter Options:**
- `linkedPageId`: ID of your listing template page (**required for navigation**)
- `viewType`: Display style ("alpha", "badge", or "carousel")
- `tagFilters`: Filter by specific tags
- `tagCategory`: Filter by tag category
- `matchRecordsByTagCategory`: Match records by tag category (boolean)
- `filterRecordsByRegion`: Filter listings by region (boolean)
- `selectedRegionId`: Manually select a specific region to filter by (string; only available when not on region/itinerary/listing/event pages)
- `listingType`: Filter by main type (comma-separated string)
- `sortBy`: Sort order (e.g., "name", "default")
- `buttonText`: Text for the action button
- `customTemplateName`: Use a custom template for display

**Display Toggles:**
- `showImage`, `showName`, `showShortDescription`, `showDescription`, `showCity`, `showAddress`, `showSubtitle`, `showPhone`, `showEmail`, `showWebsite`, `showBookingLink`, `showTags`, `showRegion`, `showRelatedItineraries`

## How it Works

- The block pulls listings from your Tourismo content and displays them in the selected format.
- **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 specific regions 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 carries regional context (region, itinerary, listing, or event templates), the sidebar exposes a **Region Filtering Mode** dropdown. It maps directly 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 region picks always reset `region_filtering_mode` and remain available on any page, even if there is no automatic region context.
- Filtering, sorting, and display options can be set in the block editor or via shortcode attributes.
- The block is styled with `.itin` and `.itinerator-listings` classes for easy targeting.
- Clicking a listing 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 "Listings"** in the block inserter
4. **Select "Itinerator Listings"** 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-listings linked_page_id="YOUR_PAGE_ID"]
```

### With Options
```
[tourismo-listings linked_page_id="YOUR_PAGE_ID" view_type="badge" columns="3" show_image="true" show_name="true" show_city="true" align="center"]
```

### Shortcode Options

| Attribute                | Type     | Default     | Required | Description                                 |
|--------------------------|----------|-------------|----------|---------------------------------------------|
| linked_page_id           | string   | ""          | Yes      | ID of your listing template page            |
| view_type                | string   | "badge"     | No       | Display style: "alpha", "badge", "carousel"|
| columns                  | string   | "3"         | No       | Number of columns (1-4, grid/tile 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                            |
| 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`) |
| main_type                | string   | ""          | No       | Filter by main type (comma-separated)       |
| 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_image               | boolean  | true        | No       | Show/hide listing image                     |
| show_name                | boolean  | true        | No       | Show/hide listing name                      |
| show_subtitle            | boolean  | false       | No       | Show/hide listing subtitle                      |
| show_short_description   | boolean  | false       | No       | Show/hide short description                 |
| show_description         | boolean  | false       | No       | Show/hide full description                  |
| show_city                | boolean  | true        | No       | Show/hide city                              |
| show_address             | boolean  | false       | No       | Show/hide address                           |
| show_phone               | boolean  | false       | No       | Show/hide phone number                      |
| show_email               | boolean  | false       | No       | Show/hide email                             |
| show_website             | boolean  | false       | No       | Show/hide website link                      |
| show_booking_link        | boolean  | false       | No       | Show/hide booking link                      |
| show_tags                | boolean  | false       | No       | Show/hide tags                              |
| show_region              | boolean  | false       | No       | Show/hide region info                       |
| show_related_itineraries | boolean  | false       | No       | Show/hide related itineraries               |

### Examples

**Directory (Alpha) Example:**
```
[tourismo-listings linked_page_id="123" view_type="alpha" columns="3" show_name="true" show_city="true"]
```

**Tiles (Badge) Example:**
```
[tourismo-listings linked_page_id="123" view_type="badge" columns="3" show_image="true" show_name="true" show_city="true"]
```

**Carousel Example:**
```
[tourismo-listings linked_page_id="123" view_type="carousel" show_image="true" show_name="true"]
```

**Filtered by Main Type Example:**
```
[tourismo-listings linked_page_id="123" main_type="member,featured" view_type="badge" columns="3"]
```

**Manual Region Selection Example:**
```
[tourismo-listings linked_page_id="123" filter_records_by_region="true" selected_region_id="1" view_type="badge" columns="3"]
```

**Current Region Plus Lineage Example:**
```
[tourismo-listings linked_page_id="123" filter_records_by_region="true" region_filtering_mode="current-and-lineage" view_type="badge" columns="3"]
```

## Content Displayed

- Listing name, image, and subtitle
- Short and/or full description
- City, address, phone, email, website, booking link
- Tags and region info
- Related itineraries (if enabled)

## Related Blocks

- [Itineraries](itineraries.md) – Display a list of itineraries
- [Filter](../content-blocks/filter.md) – Add content filtering
- [Title](../content-blocks/title.md) – Add section headers