Skip to end of metadata
Go to start of metadata

To assist new users you can add an inbuilt tour into a JSP page and it can lead the users through the main items on the screen.

We use Bootstrap Tour to implement the tour. Their website has details of the API. Our current tour only uses part of the functionality of Bootstrap Tour so if you need additional functionality check their website.

Bootstrap Tour allows you to define a series of steps for the tour and link the steps to elements on the page (using jquery selectors for class and id). Then when the user runs the tour it will display a small dialog box near the linked element for each step and the user can use "next" and "prev" to explore the items in your tour. If the user closes the tour without doing end, then it will take them back to the same step in the tour next time they run the tour on the same browser (it is stored in local storage).

Bootstrap Tour will also allow you to make a tour that is based on the user selecting an element but we have not used that option.

A tour may be found on the main LAMS page. To see how the tour is implemented, look at main.jsp and mainTour.jsp in lams_central.

To create your own tour which describes the screen blah.jsp:

  • blah.jsp must use the Bootstrap LAMS css files.
  • Find a place for the tour details. If it is a simple tour, the tour details can go in the .jsp file for which the tour applies. If it is a long tour, we suggest creating a separate blahTour.jsp file and including it in the main jsp file. Create the secondary file as a .jsp file as there will be many <fmt:message/> entries and this is easier to do with a .jsp than a .js file.
  • In blah.jsp include /lams/css/bootstrap-tour.min.css,  /lams/includes/javascript/bootstrap.min.js and /lams/includes/javascript/bootstrap-tour.min.js. Include the tour file if you are using a separate file. Finally, create a button to trigger the tour and have that button call startTour();
  • Copy this code (or use the code in mainTour.jsp) as a template and paste in blah.jsp or blahTour.jsp, modify and test. Don't forget the messages will need to be internationalised before you finish the tour. Note that most options can be defaulted as a default at the tour level, and then overridden at the step level. We have our own template definition which does not have the pause button - if you need the pause button have a look at the original template in BootstrapTour.js. We have changed to definition to add a new button in monitoring and to internationalize the buttons.

Element and Orphan

Element is the crucial step entry that ties an on screen element to the step of a tour. If you have ids for most of the elements you are using, the you can use the "#id" syntax, otherwise define a class for each element and use the ".class" syntax. We suggest making the class elements "tour-blah-blah" so that their use is obvious. Warning: if you have a class that is used in multiple spots on the screen, the Tour dialog will appear against each instance. So if you have 5 fields with the same class, you will see the message 5 times simultaneously. If you have a message like the start and end messages that are not ties.

We have left the "orphan" option defaulting to false, which means if the element does not appear on the screen then skip the step. This is useful on the main screen as it allows the tour to automatically skip the steps where the button does not appear on the screen. For example, you do not need to programmatically work out if this user has a monitor lesson button and skip the step if they do not, with orphan set to false the tour will skip it automatically.

So if you want to display a message that does not related to a particular element, you will need to not set element, and set orphan = true for that step only. For example the start and final messages in the tour.

Backdrop

Backdrop = true will grey out the overall screen and leave just the related element visible. While this makes the element much more obvious, if the user tries out the element (say by pressing the button to show something) the action is still done but the results can't be seen clearly due to being greyed out.

So leave backdrop = false as the default at the tour level and if you have a particular case you want to highlight, set backgroup = true at the step level. We have done this for the lesson area for the main screen and you can see the syntax in the template for tour-element2.

backdrop = false (default)

backdrop = true

Other Tour / Step Options and I18N

These are the options that are commonly used.

debug

tour

While developing the tour, set debug to true. This will give you a useful trace in the javascript console log. For example it will help you pick up a step being skipped because you misspelt a class name.

onEnd, onStart, onShow, onHidden

tour, step

There are a series on on handlers that can be defined the tour overall and for individual steps. Useful if you need to manipulate the screen, or just to another screen, between steps. In the main page tour, onEnd, onShow and onHidden are used to display the course list on the left and then return it to the way it was before the tour started.

title

step

Header text for the dialog box that appears

content

step

Content text for the dialog box that appears

Many of the step titles can use I18N labels that already exist, such as the button name that the step is describing. Please reuse an existing label rather than creating a new one with the same text.

You will need to add new I18N entries for the content - we suggest calling them tour.blah.content or similar so they are easily distinguishable.

BootstrapTour itself is not I18N'd so the our template used in lams_central has our own button translations. If you use the standard template, you will need to add the following to your I18N file:

If you need to add an extra button (say to open the Wiki help pages), have a look to at monitorTour.jsp (in lams_monitoring) to see the template changes and related javascript.

  • No labels