Home Collection Blocks Listings

Listings

Last updated on Nov 14, 2025

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