Tour UI
Provides a user interface for managing Drupal core's Tour module, enabling administrators to create, edit, and delete guided tours through an intuitive admin interface.
tour_ui
Install
composer require 'drupal/tour_ui:^2.0'
Overview
Tour UI extends Drupal core's Tour module by providing a complete administrative interface for managing guided tours. Without this module, tours must be created by manually writing YAML configuration files, which requires technical knowledge and access to the file system.
With Tour UI, site administrators can create interactive guided tours directly through the Drupal admin interface. Tours consist of a series of tips (tooltips) that guide users through specific pages or features of the site. Each tip can be positioned relative to any DOM element and can contain formatted text with HTML.
The module includes built-in tours for its own interface, demonstrating how to use the tour creation features. It also provides autocomplete functionality for finding routes and module names, making it easier to configure where tours should appear.
Features
- Full CRUD operations for tours through the admin interface - create, view, edit, and delete tours without writing code
- Manage tour tips with add, edit, delete, and drag-and-drop reordering functionality
- Route autocomplete feature that searches the router table to help find the correct route names for tour targeting
- Module name autocomplete for specifying which module the tour configuration belongs to
- Support for route parameters allowing tours to target specific pages (e.g., a specific node)
- Multiple positioning options for tooltips including auto, top, bottom, left, right, and their start/end variants
- Built-in self-documenting tours that demonstrate how to use Tour UI itself
- Extended text tip plugin with form-based configuration for creating rich tooltip content
- Tip weight system for controlling the order in which tour steps appear
Use Cases
Onboarding New Site Administrators
Create a guided tour for the Drupal admin interface to help new administrators learn where to find common settings. For example, create a tour for the /admin/config route that walks through each configuration category, explaining what each section contains and when they might need to use it.
Training Content Editors
Build tours for content creation workflows. Create a tour on the node/add/article route that guides content editors through each field, explaining best practices for titles, body content, images, and taxonomy terms.
Module Documentation
When developing custom modules, use Tour UI to create interactive documentation. Create tours that explain custom admin pages, configuration options, and workflows specific to your module.
Feature Announcements
After deploying new features, create temporary tours to highlight changes. For example, after redesigning a dashboard, create a tour that points out new elements and explains their purpose.
Complex Form Guidance
For forms with many fields or complex options, create tours that explain each section. This is particularly useful for configuration forms where incorrect settings could cause issues.
Tips
- Use the Devel module's /devel/routes page to easily find route names for targeting tours
- When creating tours for production sites, export the configuration to a custom module rather than leaving it in tour_ui - Tour UI is intended as a development tool
- Route parameters (like - node:2) allow targeting specific content pages, but be aware this feature has limitations documented in issue #2978327
- Tips appear in order based on their weight - lower weights appear first in the tour sequence
- The selector field accepts any valid CSS selector, making it easy to target specific elements on the page
- Empty selectors cause the tooltip to appear centered on the screen, useful for introductory or summary tips
- Consider the user's viewport when choosing tip positions - 'auto' will attempt to find the best position automatically
- HTML is supported in tip body content, allowing for formatted text, links, and even images in your tour content
Technical Details
Admin Pages 7
/admin/config/user-interface/tour
The main tours management page that lists all available tours in the system. Displays a table with tour ID, label, routes (pages where the tour appears), number of tips, and operations. From this page you can add new tours or edit/delete existing ones.
/admin/config/user-interface/tour/add
Form to create a new guided tour. Specify the tour name, module it belongs to, and the routes where it should appear. After creating the tour, you can add individual tips (tour steps).
/admin/config/user-interface/tour/manage/{tour}
Form to edit an existing tour. Modify tour settings and manage the tour tips. Tips can be reordered using drag-and-drop, and new tips can be added using the tip type selector.
/admin/config/user-interface/tour/manage/{tour}/tip/add/{type}
Form to add a new tip (tour step) to a tour. The form fields vary based on the tip type selected. The Text tip type is the most common and allows creating tooltips with formatted content.
/admin/config/user-interface/tour/manage/{tour}/tip/edit/{tip}
Form to edit an existing tour tip. Same fields as the add tip form, but pre-populated with the current tip values.
/admin/config/user-interface/tour/manage/{tour}/tip/delete/{tip}
Confirmation form to delete a tour tip. Displays the tour and tip names and asks for confirmation before deletion.
/admin/config/user-interface/tour/manage/{tour}/delete
Confirmation form to delete an entire tour including all its tips.
Permissions 1
Hooks 4
hook_entity_type_alter
Alters the Tour entity type to add custom form classes, access handler, list builder, and link templates for the Tour UI administration interface.
hook_tour_tips_info_alter
Alters tour tip plugin definitions to override the core text plugin with an extended version that includes form-based configuration.
hook_module_implements_alter
Ensures tour_ui's entity_type_alter hook runs before other modules so its alterations take precedence.
hook_help
Provides help text for the Tour UI module on the help page.
Troubleshooting 6
Verify the route name is correct using Devel module's /devel/routes page. Also ensure the user has the 'access tour' permission from the core Tour module.
Check the weight values on the tour edit page. Lower weights appear first. Use drag-and-drop to reorder tips and save the tour.
The element may not be visible when the tour loads, or the CSS selector may match multiple elements. Try using a more specific selector like an ID rather than a class.
This occurs when a tip plugin doesn't implement getConfiguration(). This can happen with custom tip plugins that aren't compatible with Tour UI.
Type at least one character to trigger the autocomplete. The module must be enabled to appear in suggestions.
You must type at least 4 characters before the route search is triggered. The search matches against both route names and path patterns.
Security Notes 3
- The 'Administer tour' permission is marked as 'restrict access' and should only be granted to trusted administrators
- Tour tip body content accepts HTML, which could potentially be used for XSS if untrusted users are given the administer tour permission - only trusted HTML tags are allowed (using Xss::getAdminTagList())
- Tour UI is primarily a development tool and may not need to be enabled on production sites once tours are created and exported to module configuration