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, showStats

How it Works

The block pulls listings from your Tourismo content and displays them in the selected format.
Region / Guide Filtering:
- On region pages: Automatically filters by the current region; children/parents/lineage modes are available
- On guide pages: Automatically filters by guide membership (filter[guide_id] — listings inside the guide's bounds that share its tags). Hierarchy modes are hidden; parent regions are not included
- On itinerary/listing/event pages: Automatically filters by the associated region
- On other pages: Manually select a region or guide
- Manual override: Selecting a specific region or guide always takes precedence

Filtering Modes

When filter_records_by_region is enabled, the sidebar Filtering Mode dropdown maps to region_filtering_mode / selected_region_id.

On Single Region pages (and other non-guide automatic context)

Mode	Description	Shortcode value
Use current page region (automatic)	Uses only the current page's region	`""` (attribute omitted)
Use current region and children (descendants)	Current region plus every descendant	`"current-and-children"`
Use current region and parents (ancestors)	Current region plus every ancestor	`"current-and-parents"`
Use current region and entire lineage	Ancestors, current region, and descendants	`"current-and-lineage"`
Select a specific region or guide	Exact pick; ignores automatic context	Set `selected_region_id`

On Single Guide pages

Mode	Description	Shortcode value
Use current guide (automatic)	Guide membership: bounds + shared tags (`filter[guide_id]`)	`""` (attribute omitted)
Select a specific region or guide	Exact pick; ignores automatic context	Set `selected_region_id`

Guide vs region: Guide membership is not the same as "listings in the parent region." A listing must sit inside the guide's polygon and share tags with the guide. Hierarchy modes (children/parents/lineage) are not offered on guide pages because they describe region geography, not guide membership.

Manual picks always reset region_filtering_mode and remain available on any page.

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

Open the block editor on any page or post
Click the + button to add a new block
Search for "Listings" in the block inserter
Select "Itinerator Listings" from the results
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 or guide
selected_region_id	string	""	No	Manually select a region or guide to filter by
region_filtering_mode	string	""	No	Region hierarchy modes when automatic region context applies (`current-and-children`, `current-and-parents`, `current-and-lineage`). Not used on Single Guide pages (automatic guide membership only).
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
show_stats	boolean	false	No	Load stats onto each card after page load
stats_category	string	""	No	Stats category slug (blank = summary)

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 – Display a list of itineraries
Filter – Add content filtering
Title – Add section headers