# Featured Listings Block

The **Featured Listings block** displays a carousel of featured listings from your Tourismo content. Use it to showcase highlighted businesses, attractions, or services in an engaging horizontal slider format.

## Overview

Use the Featured Listings block to:
- Showcase featured or highlighted listings in a carousel format
- Display business information with contact details and descriptions
- Create engaging content sections for homepage or region pages
- Highlight premium or sponsored listings

## Block Features & Options

**Display Modes:**
- **Carousel (Default):** Horizontal slider with auto-play and wrap-around functionality

**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 listing template page (**required for navigation**)
- `custom_template_name`: Use a custom template for display

**Display Toggles:**
- `show_image`, `show_name`, `show_city`, `show_description`, `show_short_description`, `show_address`, `show_phone`, `show_email`, `show_website`, `show_booking_link`, `show_tags`, `show_region`, `show_related_itineraries`

## How it Works

- The block pulls featured listings from your Tourismo content and displays them in an auto-playing carousel.
- Each listing card shows selected information fields and links to the listing's detail page.
- The carousel automatically plays and wraps around to the beginning when reaching the end.
- The block is styled with `.itin` and `.itinerator-featured-listing` classes for easy targeting.

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

### With Options
```
[tourismo-listings-featured linked_page_id="YOUR_PAGE_ID" show_image="true" show_name="true" show_description="true" show_website="true"]
```

### Shortcode Options

| Attribute                | Type     | Default     | Required | Description                                 |
|--------------------------|----------|-------------|----------|---------------------------------------------|
| linked_page_id           | string   | ""          | Yes      | ID of your listing template page            |
| custom_template_name     | string   | ""          | No       | Use a custom template for display           |
| class_name               | string   | ""          | No       | Custom CSS class                            |
| align                    | string   | ""          | No       | Alignment (left, center, right)             |
| show_image               | boolean  | true        | No       | Show/hide listing images                    |
| show_name                | boolean  | true        | No       | Show/hide listing name                      |
| show_city                | boolean  | false       | No       | Show/hide city information                  |
| show_description         | boolean  | false       | No       | Show/hide full description                  |
| show_short_description   | boolean  | false       | No       | Show/hide short description                 |
| show_address             | boolean  | false       | No       | Show/hide address information               |
| show_phone               | boolean  | false       | No       | Show/hide phone number                      |
| show_email               | boolean  | false       | No       | Show/hide email address                     |
| 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 information                |
| show_related_itineraries | boolean  | false       | No       | Show/hide related itineraries               |

### Examples

**Simple Featured Listings Carousel:**
```
[tourismo-listings-featured linked_page_id="123" show_image="true" show_name="true" show_description="true"]
```

**Featured Listings with Contact Info:**
```
[tourismo-listings-featured linked_page_id="123" show_image="true" show_name="true" show_phone="true" show_email="true" show_website="true" show_address="true"]
```

**Featured Listings with Related Content:**
```
[tourismo-listings-featured linked_page_id="123" show_image="true" show_name="true" show_tags="true" show_related_itineraries="true"]
```

## Content Displayed

- Listing name, hero image, and descriptions
- Contact information (phone, email, address)
- Website and booking links
- Region and city information
- Tags and related itineraries
- Auto-playing carousel with wrap-around functionality

**Layout:** Horizontal carousel with auto-play and navigation

## Related Blocks

- [Listings](listings.md) – Display a list or grid of all listings
- [Listings Additional](listings-additional.md) – Display additional listings
- [Listing Info](../content-blocks/listing-info.md) – Display detailed listing information
- [Listing Website Button](../content-blocks/listing-website-button.md) – Add website links