ngx-bootstrap-product-tour
About
This is a product tour library built with Angular (2+).
NgxBootstrapProductTourModule
is an implementation of the tour ui that uses ngx-bootstrap popovers to display tour steps.
For Angular 4 use package version 1.0.6
For Angular 5 use package version 2.0.x
Installation
npm i ngx-bootstrap-product-tour ngx-bootstrap bootstrap
- Import
NgxBootstrapProductTourModule.forRoot()
into your app module - Make sure
RouterModule
is imported in your app module - Include bootstrap css.
Usage
-
Add
<ngx-bootstrap-product-tour></ngx-bootstrap-product-tour>
to your root app component -
Define anchor points for the tour steps by adding the
tourAnchor
directive throughout your app.... -
Define your tour steps using
tourService.initialize(steps)
this.tourService.initialize; -
Start the tour with
tourService.start()
Demo
Demo page can be found here and it's source code here.
TourService
The TourService
controls the tour. Some key functions include
Function | Description |
---|---|
start() | Starts the tour |
startAt(stepId: number | string) | Start the tour at the step with stepId or at the specified index |
end() | Ends the tour |
pause() | Pauses the tour |
resume() | Resumes the tour |
next() | Goes to the next step |
prev() | Goes to the previous step |
Step Configuration
Each step can have the following properties.
Name | Type | Default | Description |
---|---|---|---|
stepId | string | "" | A unique identifier for the step |
anchorId | string | required | The anchor to which the step will be attached |
title | string | "" | The title of the tour step |
content | string | "" | The content text of the tour step |
route | string | UrlSegment[] | undefined |
nextStep | number | string | undefined |
prevStep | number | string | undefined |
placement | 'top' | 'bottom' | 'right' | 'left' | 'top' | Where the tour step should placed with respect to the anchor. |
preventScrolling | boolean | false | Tour steps automatically scroll to the middle of the screen, if they are off the screen when shown. Setting this value to true will disable the scroll behavior. |
containerClass | string | "" | Css class for popover container. |
orphan | boolean | false | Tour popover will be placed in the center of the screen, must have anchorId but it won't be shown next to that element. |
promise | promise<any> | "" | Step shows after promise has been resolved. |
delay | number | 0 | Time in milliseconds before showing the tour step. |
backdrop | boolean | false | Shows/hides backdrop. You need to set backgroud color and z-index on class .tour-backdrop and higher z-index on .tour-step-backdrop. |
Defaults
You can set default values in the TourService.initialize
function.
this.tourService.initializesteps, } route: '', placement: 'left', preventScrolling: true,};
Any value explicitly defined in a step will override the default value.
Event Observables
The TourService
emits events that can be subscribed to like this:
this.tourService.initialize$.subscribe console.log'tour configured with these steps:', steps;};
Name | Payload | Emitted When |
---|---|---|
stepShow$ | IStep | A step is shown |
stepHide$ | IStep | A step is hidden |
initialize$ | IStep[] | The tour is configured with a set of steps |
start$ | IStep | The tour begins |
end$ | any | The tour ends |
pause$ | IStep | The tour is paused |
resume$ | IStepI | The tour resumes |
anchorRegister$ | string | An anchor is registered with the tour |
anchorUnregister$ | string | An anchor is unregistered from the tour |
Custom template
You can also customize the tour step template by providing an <ng-template>
inside the <ngx-bootstrap-product-tour>
The default template is equivalent to this:
{{tourService.currentStep.content}} « Prev Next » End