Skip to main content

WordPress Plugin Documentation

Show your tourism content in WordPress! Itinerator connects to the Tourismo API to display your content in a beautiful way.

D
Written by Dustin Grof
Updated over a week ago

Table of Contents

  1. Getting Started

  2. Plugin Configuration

  3. Available Blocks

  4. Block Details

  5. Shortcode Reference

  6. Template Customization

  7. Custom View Templates

  8. Available API Data

  9. Development Scripts

  10. Requirements

  11. License

Getting Started

Installation

  1. Install the plugin by uploading the plugin files to /wp-content/plugins/itinerator

  2. Activate the plugin through the 'Plugins' screen in WordPress

  3. Navigate to Settings > Itinerator to configure your API credentials:

    • API Key: Required for accessing basic Tourismo content

    • DMO Secret Key: Required only if using the Itineraries Widget feature

Required Template Pages

Create the following pages and set their "Page Type" using the Itinerator Meta Box in the page sidebar:

  • Single Listing

  • Single Region

  • Single Itinerary

  • Single Event (optional)

  • Single Challenge (optional)

These templates determine how individual resources are displayed when clicked from a grid or listing view.

Plugin Configuration

API Credentials

  • Platform API Key: Required for accessing basic Tourismo content

  • DMO/Partner API Key: Required only if using DMO-specific features

  • Google Maps API Key: Required for map functionality

  • Google Maps Map ID: Optional custom map styling ID

  • Snowplow Tracking Slug: Enable analytics tracking (optional)

Cache Settings

  • API Response Caching: Toggle to enable/disable 24-hour caching of API responses

  • Clear Cache: Manually clear all cached API responses

Bootstrap Compatibility

This plugin uses Bootstrap 4.6.1 for layouts and components. There are two ways to manage potential conflicts with your theme:

  1. JavaScript Whitelist

    • Enter comma-separated page/post IDs where plugin scripts should load

    • Example: 123,456,789

    • Scripts will only load on:

      • Whitelisted pages/posts

      • Single resource pages

      • Plugin settings pages

    • Leave empty to load on all pages

  2. Bootstrap Loading

    • Option to disable Bootstrap if your theme already includes it

    • Only disable if you're certain your theme uses Bootstrap 4.x

Theme Settings

Customize the appearance of plugin elements:

Colors:

  • Primary Color

  • Secondary Color

  • Light Color

  • Dark Color

  • Text Color

  • Heading Color

  • Link Color

Button Styling:

  • Background Color

  • Border Color

  • Link Color

  • Border Radius

  • Border Width

Note: Theme settings can also be managed through the Itinerator Admin Interface.

Available Blocks

Content Display Blocks

  • Title: Simple block to display a resource's name, feature image, and subtitle

  • Content: Displays the main content body with toggleable title and description sections in a single column layout

  • Description: Shows either full or short description of a resource in a single column format

  • Tags: Displays associated tags filtered by category in a horizontal flow layout

  • Carousel: Full-width image/video slider with optional captions, autoplay, and wrap-around navigation

  • Socials: Links to associated social media profiles in a horizontal list

  • Map: Interactive Google Maps integration with customizable markers and info windows, typically full-width

  • Filter/Search: Search input and dropdown filters in a single row layout with optional button groups

  • Form: Dynamic form builder with responsive single-column layout for form fields

  • Listing Buttons: Action buttons displayed in a horizontal row or stacked on mobile

  • Listing Info: Two-column layout with image on left (6 cols) and business details on right (5 cols)

  • Related Posts: Grid layout with configurable number of columns

  • Website Button: Single button that can be aligned left, center, or right

Resource Grid/List Blocks

  • Regions: Two-column row layout with details on left (6 cols) and image on right (6 cols), stacks on mobile

  • Itineraries: Two-column layout similar to Regions, with image right and content left including stops/days count

  • Listings: Three display options:

    • Grid: 3-column card layout with image, name, and description

    • Badge: 4-column card layout with featured image and name

    • Alpha: Multi-column alphabetical list with configurable columns (1-4)

  • Additional Listings: Similar to Listings grid but with toggleable elements

  • Featured Listings: Carousel layout with full-width slides showing image and optional name

  • Events: 3-column grid layout (4 cols on large screens) with image cards and event details

  • Challenges: Two-column row layout with image right (6 cols) and challenge details left (6 cols)

  • DMO Itineraries: Two layout options:

    • Grid: Responsive grid with configurable columns and styling

    • Carousel: Full-width slider with platform logo and overlay content

  • DMOs: Two layout options:

    • Grid: Responsive card grid with configurable columns (up to 4)

    • Carousel: Auto-playing slider with logo images and names

Block Details

Additional Listings Block

Displays additional listings related to the current content:

  • Linked page selection

  • Title display toggle

  • Image display toggle

  • Name display toggle

  • Description display toggle

  • Custom template option

Carousel Block

Displays a slideshow of images:

  • Image navigation

  • Caption display

  • Custom template option

Challenges Block

Shows challenge content in a grid or list format:

  • Linked page selection

  • Region-based filtering

  • Display options for dates, descriptions, images, locations, and names

  • Tag category filtering

  • Custom template option

Content Block

Displays the main content body:

  • Content type selection

  • Description display toggle

  • Title display toggle

  • Custom template option

Description Block

Shows either full or short description content:

  • Description type selection (full/short)

  • Custom template option

DMO Itineraries Block

Displays DMO-specific itineraries:

  • View type selection (grid/carousel)

  • Column count configuration

  • Grid styling options (border radius, gap)

  • Platform logo customization

  • Filtering of itineraries

  • Custom template option

Events Block

Displays events in a grid layout:

  • Linked page selection

  • Region-based filtering

  • Display options for descriptions, images, and names

  • Tag category filtering

  • Custom template option

Featured Listings Block

Showcases featured listings:

  • Linked page selection

  • Description display toggle

  • Title display toggle

  • Custom template option

Filter Block

Provides search and filtering capabilities:

  • Filter type selection

  • Custom placeholder text

  • Tag category filtering

  • Custom template option

Form Block

Displays form elements:

  • Form selection

  • Name display toggle

  • Description display toggle

  • Custom alignment

  • Custom classes

  • Custom template option

Itineraries Block

Shows itinerary collections:

  • Linked page selection

  • Region-based filtering

  • Tag category filtering

  • Custom template option

Listing Buttons Block

Displays action buttons for listings:

  • Button type selection

  • Custom styling classes

  • Custom template option

Listing Info Block

Shows detailed listing information:

  • Address display toggle

  • Hours display toggle

  • Image display toggle

  • Website display toggle

  • Custom template option

Map Block

Displays location information:

  • Marker customization (color, size, labels)

  • Boundary styling options

  • Region and listing display toggles

  • Custom template option

Regions Block

Shows region information:

  • Linked page selection

  • Region-based filtering

  • Subregion display toggle

  • Tag category filtering

  • Custom template option

Related Posts Block

Displays related WordPress posts:

  • Display count configuration

  • Custom template option

Socials Block

Shows social media links:

  • Icon display toggle

  • URL display toggle

  • Custom template option

Tags Block

Displays associated tags:

  • Tag category filtering

  • Custom template option

Title Block

Shows the resource title:

  • Name display toggle

  • Image display toggle

  • Subtitle display toggle

  • Custom template option

Website Button Block

Displays external website links:

  • Button text customization

  • Button type selection

  • Custom styling classes

  • Custom template option

Shortcode Reference

All blocks are also available as shortcodes with the prefix tourismo-. Below are the available shortcodes and their attributes:

Content Display Shortcodes

Carousel

[tourismo-carousel custom_template_name=""]

Content

[tourismo-content content_type="" custom_template_name="" show_description="true" show_title="true"]

Note: content_type is required

Description

[tourismo-description custom_template_name="" description_type="full"]

Form

[tourismo-form-block selected_form="FORM_ID" custom_template_name="" show_name="true" show_description="true" class_name="" align=""]

Note: Replace FORM_ID with your specific form ID

Listing Info

[tourismo-listing-info custom_template_name="" show_address="true" show_hours="true" show_image="true" show_website="true"]

Map

[tourismo-map boundary_fill_color="#222" boundary_fill_opacity="0.3" boundary_stroke_color="#000" boundary_stroke_opacity="1" boundary_stroke_weight="1" custom_template_name="" linked_page_id="YOUR_PAGE_ID" linked_region_page_id="YOUR_REGION_PAGE_ID" marker_fill_color="#EA4335" show_listings_boundaries="false" show_regions_boundaries="false" ]

Note: Replace YOUR_PAGE_ID and YOUR_REGION_PAGE_ID with your specific page IDs

Socials

[tourismo-socials show_icon="true" show_url="false" custom_template_name=""]

Tags

[tourismo-tags custom_template_name="" tag_category="amenity"]

Title

[tourismo-title custom_template_name="" show_image="true" show_name="true" show_subtitle="true"]

Resource Grid/List Shortcodes

Challenges

[tourismo-challenges linked_page_id="YOUR_PAGE_ID" custom_template_name="" filter_records_by_region="true" show_dates="true" show_description="true" show_image="true" show_location="true" show_name="true" ]

Note: Replace YOUR_PAGE_ID with your specific page ID

DMO Itineraries

[tourismo-dmo-itineraries custom_template_name="" view_type="grid" columns="3" platform_logo_border_radius="5px" overlay_border_radius="10px" grid_item_border_radius="0" grid_gap="1rem" filter_by_ids="123, 456" ]

Events

[tourismo-events custom_template_name="" filter_records_by_region="true" linked_page_id="YOUR_PAGE_ID" show_description="true" show_image="true" show_name="true" ]

Note: Replace YOUR_PAGE_ID with your specific page ID

Featured Listings

[tourismo-featured custom_template_name="" linked_page_id="YOUR_PAGE_ID" show_description="false" show_title="true" ]

Note: Replace YOUR_PAGE_ID with your specific page ID

Itineraries

[tourismo-itineraries custom_template_name="" filter_records_by_region="true" linked_page_id="YOUR_PAGE_ID" match_records_by_tag_category="false" ]

Note: Replace YOUR_PAGE_ID with your specific page ID

Listings

[tourismo-listings columns="3" linked_page_id="YOUR_PAGE_ID" view_type="badge" show_image="true" show_name="true" show_city="true" show_description="true" ]

Note: Replace YOUR_PAGE_ID with your specific page ID

Additional Listings

[tourismo-listings-additional linked_page_id="YOUR_PAGE_ID" show_image="true" show_name="true" show_description="true" ]

Note: Replace YOUR_PAGE_ID with your specific page ID

Regions

[tourismo-regions custom_template_name="" filter_records_by_region="true" linked_page_id="YOUR_PAGE_ID" only_show_subregions="true" ]

Note: Replace YOUR_PAGE_ID with your specific page ID

Page-Specific Shortcodes

When setting up your template pages (Single Listing, Single Region, etc.), you can use these shortcodes to display specific data fields. All shortcodes can be rendered without markdown formatting by adding the -stripped suffix (e.g., [itin-stripped-name]).

Single Region Page

[itin-name] # Region name 
[itin-subtitle] # Region subtitle 
[itin-description] # Full description 
[itin-short_description] # Short description 
[itin-parent_slug] # Parent region slug

Single Listing Page

[itin-name] # Business name 
[itin-email] # Contact email 
[itin-city] # City 
[itin-full_address] # Complete address 
[itin-street_address] # Street address 
[itin-province] # Province/State 
[itin-postal_code] # Postal/ZIP code 
[itin-country] # Country 
[itin-phone_number] # Contact phone 
[itin-website] # Website URL 
[itin-booking_website] # Booking website URL 
[itin-subtitle] # Business subtitle 
[itin-description] # Full description 
[itin-short_description] # Short description

Single Itinerary Page

[itin-name] # Itinerary name 
[itin-title] # Itinerary title 
[itin-subtitle] # Itinerary subtitle 
[itin-description] # Full description 
[itin-region_slug] # Associated region slug

Single Event Page

[itin-name] # Event name 
[itin-cost] # Event cost 
[itin-description] # Event description 
[itin-ticket_url] # Ticket booking URL 
[itin-email] # Contact email 
[itin-website] # Event website 
[itin-phone_number] # Contact phone

Single Challenge Page

[itin-name] # Challenge name 
[itin-target_name] # Target location/activity name 
[itin-description] # Challenge description

Note: These shortcodes are specifically for use in the template pages. For displaying content in other parts of your site, use the block shortcodes above instead.

Template Customization

To customize any template:

  1. Create an itinerator folder in your theme root directory

  2. Copy the template file you want to customize from the plugin's templates folder

  3. Paste it into your theme's itinerator folder

  4. Modify the template as needed

Example:

your-theme/ 
├── itinerator/ 
│ ├── carousel.php 
│ └── listing-info.php 
└── ...

Custom View Templates

Many blocks support custom templates through the "Custom Template Name" field. This allows you to create alternative layouts for blocks while maintaining the core functionality.

To create a custom template:

  1. In the block editor, enter a name in the "Custom Template Name" field

    • Example: entering "simple" for an Itinerary block

    • Save the block

  2. Create a corresponding PHP file in your theme's itinerator folder

    • File naming format: {block-name}-{custom-template-name}.php

    • Example: itinerary-simple.php

Example folder structure:

your-theme/ 
├── itinerator/ 
│ ├── itinerary-simple.php # Custom template 
│ ├── itinerary.php # Override default template
│ └── listings-grid.php # Another custom template 
└── ...

You can create multiple custom templates for the same block type by using different template names. This allows you to maintain several layout variations that can be selected through the block editor.

Note: If you don't specify a custom template name, you can still override the default template by creating a file with just the block name (e.g., itinerary.php).

Blocks that support custom templates:

  • Carousel

  • Challenges

  • Content

  • Description

  • DMO Itineraries

  • Events

  • Featured Listings

  • Filter

  • Form

  • Itineraries

  • Listing Info

  • Map

  • Regions

  • Socials

  • Tags

  • Title

Available API Data

When customizing templates, these are the main data fields available for each resource type:

Listings

  • Basic Info: name, description (full/short), subtitle, slug

  • Contact: email, phone_number, website, booking_website

  • Location:

    • full_address, street_address, city, province, postal_code, country

    • lat/lng coordinates

    • google_maps_url

  • Media: hero image, carousel_images, images

  • Operating Hours

  • Social Media Links

  • Tags

  • Content Sections

Itineraries

  • Basic Info: name, title, subtitle, description (full/short), main_content

  • Media: hero image, carousel_images, images

  • Legs (Sections):

    • title, description, introduction

    • order_on_itin

    • Stops for each leg

  • Region association

  • Tags

  • Content Sections

Events

  • Basic Info: name, description, cost, status

  • Dates:

    • event_times (multiple)

    • recurring options

    • start/end dates

  • Contact: email, website, phone_number, ticket_url

  • Location data for each event time

  • Media: hero image, meta_image

  • Tags

Challenges

  • Basic Info: name, description, status

  • Target Info: target_name, target_type, target_id

  • Dates: event_times

  • Media: hero image, carousel_images

  • Rewards

  • Content Sections

Regions

  • Basic Info: name, description

  • Geographic data

  • Associated listings

  • Subregions

  • Media: hero image, images

  • Tags

  • Content Sections

Note: Each resource type supports custom templates through the "Custom Template Name" field. Access these fields in your PHP templates to create custom layouts.

Development Scripts

This project was bootstrapped with Create Guten Block.

👉 npm start

  • Use to compile and run the block in development mode.

  • Watches for any changes and reports back any errors in your code.

👉 npm run build

  • Use to build production code for your block inside dist folder.

  • Runs once and reports back the gzip file sizes of the produced code.

👉 npm run deploy

  • Creates a new versioned release

  • Updates version numbers across configuration files

  • Builds and packages the plugin for distribution

Development Environment

For local development, you can use:

./dev-itin-plugin # For Bedrock-based WordPress installations ./dev-itin-plugin-vanilla # For standard WordPress installations

Requirements

  • WordPress 5.0+

  • PHP 7.2+

  • Composer

  • Node.js (for development)

License

GPL2+ License

Built by The Number Creative

Did this answer your question?