Updated based on comment #8
Tour allows you to automatically start a tour on a given path, and link to a part of that tour, however this assumes that Tour's only live on specific paths, or that tours have only one condition (autostart). It would be very useful to be able to specify which tour should be run, so that tours can be triggered on different paths, or only loaded when requested. This opens up conditional tours, multi-step tours, multipage tours, and other niceties.
Problem/Motivation
Currently, to get a tour to load on a page, you must specify its path. That basically means we have ONE way of loading a tour onto a page, and that is path matching. You could consider this a 'default' tour behaviour. This creates several fixed outcomes:
- All tours get loaded at once and added together (which is frankly confusing)
- The order of tours can't be altered (which is worse)
- The "tip" selector can be provided, but all this does is select a different starting point on the existing tours. If there are multiple tours on the page, this effectively starts you in the middle of the tour somewhere, which is also a bit confusing.
Basically, there is no way to selectively enable a tour.
Proposed resolution
tour_preprocess_page() will include an additional check on the 'tour-id' query parameter, which can specify one or more tour IDs to load. These will be loaded INSTEAD of any tours on that path.
Use cases
This patch enables you to selectively trigger a tour, and ONLY THAT TOUR, on any path.
Why might you want to do that? Well, there are a number of reasons:
1) You want to help a user with a specific piece of complex functionality, wherever that functionality exists
For example, to allow the Toolbar Tour to be triggered ON ANY PAGE, and not just on the homepage. This allows the user to take the tour whenever is convenient (keeping in mind that we don't currently have a built in way to see what tours are available, though a block could do this, for example).
2) You want to make branching tours.
📌
Write tour integration for the first page after install showing extend and other things
Postponed
currently proposes a branched tour for the homepage, which allows users to click through to the parts of the tour that they are interested in. This allows the page tour to be a small index of available tours, rather than an unwieldy and massive single tour.
3) You want to load a specific tour when a condition is met that is not path based
For example, you may want to load a tour the first time a user visits a page containing a special block you have provided. This has nothing to do with paths.
What's the use to load tours with no matching path? Their tips will not match elements on the page, right?
Wrong. Whether a path exists has nothing to do with whether the selectors match, its just the way we've chosen to determine what should be visible BY DEFAULT. The selectors may still not be there (and if they aren't the tour isn't offered anyway). It's up to the developer of the tour to ensure that the correct selectors are available when the tour is loaded. This is the same whether its path-based, or triggered.
Because this patch implicitly requires an implementer to create links to the tour's they want, there is actually a GREATER chance that the selectors will be present.
Remaining tasks
This issue.
User interface changes
None
API changes
This issue will introduce a new alter hook, hook_tour_list_alter(), which will run after tours have been selected in tour_prepocess_page(), and give contrib an opportunity to influence which tours are loaded on the page.
Related Issues
#1942576: Tour tips to be able to link to other pages and start tour's automatically. →