Help App: Guided Tours API
Incorporating guided tours
To use the guided tours API, first import a Javascript file:
<script src="/help/guidedtours/guided-tours.js"></script>
Registering a guided tour
Register a guided tour with the command registerTourAsync(). Call the command from the GuidedTours object attached to window.
Currently, a maximum of 10 tours can be persistently registered per app, client and user at the same time. You can use the deleteTourAsync method to delete a tour to make room for new tours. If you do not need persistence, you can use the disablePersistence attribute.
Example: registering a guided tour
let tour = await window.GuidedTours.registerTourAsync({
id: "app-overview-tour",
steps: [
{
id: "step-1",
title: "Welcome to the guided tour",
text: "This tour introduces you to the most important features of the app.",
},
{
id: "step-2",
title: "Login",
text: "Login here. Enter your username and password.",
attachTo: {
element: "#login-dialog"
}
},
//...
]
})
Parameters of the registerTourAsync method
| Property | Type | Required field | Description |
|---|---|---|---|
| id | String | Yes | Identifier for the guided tour. The ID may be a maximum of 128 characters long and may contain only the following characters: (a-z), (A-Z), (0-9), "-", "_" |
| steps | Array | Yes | An array of step objects describing the steps of the guided tour. |
| useModalOverlay | Boolean | No | By default, the application background is dimmed to highlight the guided tour. Set the parameter to false if you do not want to use dimming. |
| maxWidth | Number | No | Sets the maximum width of the tooltip. If not set, a width of 400 is used. |
| disablePersistence | Boolean | No | Disables the persistence of the tour status. If this attribute is enabled, the tour status will be reset when the browser is reloaded. |
Properties of the step object
| Property | Type | Required field | Description |
|---|---|---|---|
| id | String | Yes | Identifier for the tour step. |
| title | String | Yes | Title of the tour step. |
| text | String | Yes | Descriptive text that is displayed in the tooltip. |
| link | String | No | Link to further information. The link is displayed in the tooltip with the text Learn more. |
| img | String | No | URL to an image or GIF. |
| attachTo.element | String or HTML element | No | CSS selector or HTML object for the element where the tooltip should be displayed. If the parameter is empty, the tooltip is displayed in the center of the screen. |
| attachTo.on | String | No | Determines the orientation of the tooltip relative to the element specified previously. The possible values are: 'auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'right', 'right-start', 'right-end', 'left', 'left-start', 'left-end' |
| attachTo.preventInteraction | Boolean | No | Prevents user interaction with the highlighted element. The element specified in attachTo.element receives the CSS attribute pointer-events: none. |
Using the guided tour
The registerTourAsync method returns a tour class that can be used for various actions, for example to start and stop the guided tour.
Attributes of the tour class
| Property | Type | Description |
|---|---|---|
| id | String (read only) | Identifier for the guided tour. The ID may be a maximum of 128 characters long and may contain only the following characters: (a-z), (A-Z), (0-9), "-", "_" |
| steps | Array (read only) | An array of steps describing the steps of the guided tour. |
| useModalOverlay | Boolean (read only) | Determines whether the application background is dimmed. |
Methods of the tour class
| Methods | Description |
|---|---|
| start(): void | Starts the guided tour. |
| complete(): void | Ends the guided tour. |
| pause(): void | Pauses the guided tour. |
| continue(): void | Continues the tour after it has been paused or canceled. The tour starts at the last step displayed. |
| next(): void | Opens the next step in the tour. |
| previous(): void | Opens the previous step in the tour. |
| getCurrentStep(): Step | Returns the step currently displayed. |
| async getStatus(): Promise<TourStatus | undefined> | Returns the current status of the tour. Possible values are: 'OPEN', 'IN_PROGRESS', 'PAUSED', 'CANCELED', 'COMPLETED'. |
| async setStatus(value: TourStatus): Promise<void> | Sets the status of the tour. Possible values are: 'OPEN', 'IN_PROGRESS', 'PAUSED', 'CANCELED', 'COMPLETED'. |
| on(event: string, callback: Function): void | Registers a callback function for a specific event. Possible events are show, cancel and complete. The method will throw an error if an unknown event is specified. |
Attributes of the step class
The attributes of the step class are analogous to the properties of the step object.
Methods of the step class
| Methods | Description |
|---|---|
| beforeNext(callback: Function, preventDefault: boolean = false) | You can add a callback function to the beforeNext() method, which will be called before the next step is displayed. You can use the preventDefault parameter to prevent the next step from being displayed when “Next” is clicked. In this case, you have to call the next() method manually. |
| beforePrevious(callback: Function, preventDefault: boolean = false) | You can add a callback function to the beforePrevious() method, which will be called before the previous step is displayed. You can use the preventDefault parameter to prevent the previous step from being displayed when “Back” is clicked. In this case, you have to call the previous() method manually. |
Displaying a feature highlight
The guided tour API allows you to highlight a feature. You can use this highlighting to draw attention to new features in the app, for example. To display a feature highlight, you can register a tour that contains only one step. The feature highlight API is identical to the guided tour API.
Example: registering a feature highlight
let tour = await window.GuidedTours.registerTourAsync({
id: "feature-highlight",
steps: [
{
id: "step-1",
title: "Guided Tours",
text: "You can now start a guided tour that gives you an overview of the app via this button.",
},
]
})
Delete a tour
Currently, a maximum of 10 tours per app, client and user can be registered persistently at the same time. The deleteTourAsync(id: string) method can be used to delete tours that are no longer required.
Example of deleting a tour
await window.GuidedTours.deleteTourAsync("app-overview-tour")
Disabling all tours for test systems
In test systems, automated tests may fail because certain elements are blocked by a guided tour. To eliminate this problem, you can disable all guided tours. Add the cookie DisableGuidedTours=true.