# Events Block

The Events block displays a collection of events from your Tourismo admin platform. It's designed for collection pages where you want to showcase upcoming events with filtering, date selection, and detailed event information.

## Overview

The Events block is ideal for:
- Event listing pages
- Tourism websites showcasing local events
- Business directories with event calendars
- Regional event hubs
- Festival and conference websites

## Block Features & Options

### Display Modes
- **Grid Layout**: Default card-based grid display
- **Carousel Layout**: Horizontal scrolling carousel (via template override)

### Layout Options
- **Show Image**: Display event hero images (default: enabled)
- **Show Featured Status**: Highlight featured events with star icon
- **Show Name**: Display event titles (default: enabled)
- **Show Event Date/Times**: Display event scheduling information (default: enabled)
- **Show Cost**: Display event pricing information (default: enabled)
- **Show Description**: Display event descriptions with "Read More" link (default: enabled)
- **Show Date Filter**: Enable interactive date range filtering (default: enabled)

### Content & Filter Options
- **Show Phone**: Display contact phone numbers
- **Show Email**: Display contact email addresses
- **Show Website**: Display event website links
- **Show Ticket Link**: Display ticket purchase links
- **Show Tags**: Display event tags/categories
- **Show Location**: Display event venue information
- **Tag Filters**: Filter events by specific tags
- **Tag Category**: Filter by tag category
- **Match Records By Tag Category**: Enable tag category matching
- **Filter Records By Region**: Filter events by region (default: enabled)
- **Selected Region ID**: Manually select a specific region to filter by (string; only available when not on region/itinerary/listing/event pages)

### Display Toggles
- **Custom Template Name**: Use custom template override
- **Button Text**: Customize "Read More" button text (default: "Explore")
- **Alignment**: Full-width alignment support

## How it Works

The Events block fetches events from your Tourismo admin platform and displays them in a responsive grid layout. Events are automatically sorted by featured status and start date. The block supports interactive date filtering, recurring event detection, and region-based filtering.

**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 region picks always reset `region_filtering_mode` and can be used on any page, even without automatic context.

## How to Add & Configure

1. **Add the Events block** to a collection page (not a template page)
2. **Configure the Linked Page**: Select an event template page for individual event details
3. **Set Display Options**: Choose which event information to show
4. **Configure Filters**: Set up tag and region filtering as needed
5. **Enable Date Filter**: Turn on interactive date range selection
6. **Customize Layout**: Adjust image display and content visibility

## Shortcode Usage

### Basic Shortcode
```
[tourismo-events]
```

### Complete Options Table

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `linked_page_id` | string | "" | **Required** - ID of the event template page |
| `custom_template_name` | string | "" | Custom template override name |
| `tag_filters` | array | [] | Array of tag IDs to filter by |
| `tag_category` | string | "" | Tag category to filter by |
| `match_records_by_tag_category` | boolean | false | Enable tag category matching |
| `filter_records_by_region` | boolean | true | Filter events by region |
| `selected_region_id` | string | "" | Manually select a region to filter by |
| `region_filtering_mode` | string | "" | Control automatic region context when the current page has a region (`current-and-children`, `current-and-parents`, `current-and-lineage`) |
| `class_name` | string | "" | Additional CSS classes |
| `align` | string | "" | Block alignment |
| `button_text` | string | "Explore" | Custom button text |
| `show_image` | boolean | true | Display event images |
| `show_featured_status` | boolean | false | Show featured event indicators |
| `show_name` | boolean | true | Display event names |
| `show_event_date_times` | boolean | true | Show event dates and times |
| `show_cost` | boolean | true | Display event costs |
| `show_phone` | boolean | false | Show contact phone numbers |
| `show_email` | boolean | false | Show contact email addresses |
| `show_website` | boolean | false | Show event website links |
| `show_ticket_link` | boolean | false | Show ticket purchase links |
| `show_tags` | boolean | false | Display event tags |
| `show_location` | boolean | false | Show event locations |
| `show_description` | boolean | true | Display event descriptions |
| `show_date_filter` | boolean | true | Enable date range filtering |

### Practical Examples

**Basic Events Display**
```
[tourismo-events linked_page_id="123"]
```

**Events with Contact Information**
```
[tourismo-events linked_page_id="123" show_phone="true" show_email="true" show_website="true"]
```

**Filtered Events by Tags**
```
[tourismo-events linked_page_id="123" tag_filters='["45", "67"]' show_tags="true"]
```

**Manual Region Selection**
```
[tourismo-events linked_page_id="123" filter_records_by_region="true" selected_region_id="5"]
```

**Current Region Plus Parents**
```
[tourismo-events linked_page_id="123" filter_records_by_region="true" region_filtering_mode="current-and-parents"]
```

**Events with Date Filtering Disabled**
```
[tourismo-events linked_page_id="123" show_date_filter="false"]
```

**Custom Template Events**
```
[tourismo-events linked_page_id="123" custom_template_name="events-carousel"]
```

## Content Displayed

The Events block displays:

- **Event Cards**: Each event appears in a responsive card layout
- **Event Images**: Hero images with aspect ratio 1:1 (when enabled)
- **Event Information**: Name, dates, times, cost, description
- **Contact Details**: Phone, email, website, ticket links (when enabled)
- **Location Information**: Event venue details (when enabled)
- **Tags**: Event categories and classifications (when enabled)
- **Featured Indicators**: Star icons for featured events (when enabled)
- **Date Filter**: Interactive date range selector (when enabled)
- **Recurring Event Indicators**: Calendar icons for recurring events

Events are automatically sorted by featured status (featured first) and then by start date (earliest first).

## Related Blocks

- **Event Block** - Individual event display for template pages
- **Itineraries Block** - Display itinerary collections
- **Listings Block** - Display business/attraction listings
- **Regions Block** - Display region collections
- **Map Block** - Interactive map display