TourGuide came about in response to a private client who hired us to create a custom calculator stack. The idea of giving users a quick guided tour of the new calculator was proposed, because the new calculator we built was radically different to the older one it replaced. After some research, it was found that the open source Bootstrap Tour plugin proved to be perfect for this task. The TourGuide stack you see here is heavily derived from this plugin codebase.

Any number of steps can be added to your tour. 'Orphaned' items open in the middle of the screen and point to no particular element. The tour can start with a click on a custom button or link. The content for each item can comprise of plain text and basic HTML code (like font formatting and links). TourGuide can 'point' to any stack elements or items elsewhere in your webpage like a theme navigation bar, ExtraContent area, sidebar or footer. As you would expect, TourGuide is fully mobile responsive.

TourGuide requires that you have a basic understanding of getting ID selector names in your webpage, using the browser developer tools or stacks like Codify and Elemental. It is these ID selector names that are used to direct TourGuide to the particular elements in your webpage you want to focus-in on. Of course, paid help is available upon request from us too, if you need this setup for you.

TourGuide is compatible with most themes, but not all. We recommend the stack is used with a quality theme that includes Bootstrap 4 or above, like the ones available on ThemeFlood. It is not impossible to make TourGuide work in some other themes without Bootstrap, but it can more challenging.

Example

In this example, we coded a simple contact form. TourGuide has been setup to guide the user through the contact form and provide information about what they need to enter. Click the button below to start the guided tour. Follow the on-screen instructions.
 

 
 
Obviously in the real world, forms should be simple enough so as to not require such detailed instructions! However this example nicely demonstrates all the main functionality TourGuide offers. It could prove to be a valuable tool on more complex webpages or webapps.

Setup

Follow these steps to setup TourGuide:
  1. Once installed into Stacks and RapidWeaver, open your Stacks Library. Search for 'TourGuide'.
  2. Drag and drop a copy of the stack into the page.
  3. Press the blue button to add steps to your guided tour.
  4. Each step requires the ID selector name of the page element you want to highlight. This ID selector name is obtainable from the web inspector developer tools in your browser, or using a stack like Codafy or Elemental.
  5. If you need to change the style or behaviour of your tooltip popups, this can be done by selecting the main stack and reviewing its settings.
  6. Preview the page to check the tour is running correctly. Export or publish the page when done.

We normally find that TourGuide works better when you set the popups to appear below the highlighted items (with the arrow pointing upwards). This can help the page scroll better and ensures the highlighted elements come into full view. Although newer branches of Bootstrap Tour have come into existence (like this one), that are suppose to improve popover positioning, we have found these newer variants to be less successful. Because instead of 'boxing-in' the highlighted element with 4 panels, they instead lift it forwards of the page using z-index. Our experiments found this made setup a lot more tedious and certainly broke a lot more stuff! The original Bootstrap Tour plugin seems to works much better, in this respect.

You should only include a single TourGuide stack on each page, preferably located towards the bottom after all other content has loaded. Any number of steps can be added to the tour. Each tour item comprises of a title and content. This content can be plain text or simple HTML code. Double-quote marks need to be escaped (replaced with entities) in any titles or content you type.

Starting your tour

You can have the tour start automatically as the page loads. Alternatively you can start the tour using a link or button like this:

<button class="start-tourguide btn btn-warning"><i class="fas fa-map-signs"></i> Start Guided Tour</button>

Basically any link or button with a class attribute and value of class="start-tourguide" can be used to start the guided tour.

If the user drops-out (finishes) their tour part-way through, it is possible for TourGuide to remember where they got to, when the Track Progress option is checked. The tour will operate in the same order that you setup the TourGuide items in.
 

Contribute

If you find this stack element useful in your personal or commercial web projects; please consider making a small contribution towards ongoing support and updates. There are many different ways you can contribute to the Stacks4Stacks project, and benefits for doing so.