# Challenges Block

The **Challenges block** displays a collection of challenges from your Tourismo admin platform. It's designed for collection pages where you want to showcase challenges with filtering, rewards, and detailed challenge information.

## Overview

The Challenges block is ideal for:
- Challenge listing pages
- Tourism websites showcasing local challenges
- Business directories with challenge calendars
- Regional challenge 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 challenge hero images (default: enabled)
- **Show Name**: Display challenge titles (default: enabled)
- **Show Dates**: Display challenge scheduling information (default: enabled)
- **Show Rewards**: Display challenge rewards information (default: enabled)
- **Show Description**: Display challenge descriptions with "Read More" link (default: enabled)

### Content & Filter Options
- **Show Tags**: Display challenge tags/categories
- **Tag Filters**: Filter challenges by specific tags
- **Tag Category**: Filter by tag category
- **Match Records By Tag Category**: Enable tag category matching
- **Filter Records By Region**: Filter challenges 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 Challenges block fetches challenges from your Tourismo admin platform and displays them in a responsive grid layout. Challenges are automatically sorted by featured status and start date. The block supports interactive filtering, reward 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 provides 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 selections always clear `region_filtering_mode` and work on any page, even without automatic region context.

## How to Add & Configure

1. **Add the Challenges block** to a collection page (not a template page)
2. **Configure the Linked Page**: Select a challenge template page for individual challenge details
3. **Set Display Options**: Choose which challenge information to show
4. **Configure Filters**: Set up tag and region filtering as needed
5. **Customize Layout**: Adjust image display and content visibility

## Shortcode Usage

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

### Complete Options Table

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `linked_page_id` | string | "" | **Required** - ID of the challenge 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 challenges 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 challenge images |
| `show_name` | boolean | true | Display challenge names |
| `show_dates` | boolean | true | Show challenge dates and times |
| `show_rewards` | boolean | true | Display challenge rewards |
| `show_description` | boolean | true | Display challenge descriptions |
| `show_tags` | boolean | false | Display challenge tags |

### Practical Examples

**Basic Challenges Display**
```
[tourismo-challenges linked_page_id="123"]
```

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

**Current Region Plus Descendants**
```
[tourismo-challenges linked_page_id="123" filter_records_by_region="true" region_filtering_mode="current-and-children"]
```

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

**Custom Template Challenges**
```
[tourismo-challenges linked_page_id="123" custom_template_name="challenges-carousel"]
```

## Content Displayed

The Challenges block displays:

- **Challenge Cards**: Each challenge appears in a responsive card layout
- **Challenge Images**: Hero images with aspect ratio 1:1 (when enabled)
- **Challenge Information**: Name, dates, rewards, description
- **Tags**: Challenge categories and classifications (when enabled)
- **Reward Indicators**: Reward information for challenges (when enabled)

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

## Related Blocks

- **Challenge Block** - Individual challenge 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