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