Ngx-bootstrap-product-tour NPM

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.
```
<div tourAnchor="some.anchor.id">...</div>
```

Define your tour steps using tourService.initialize(steps)

this.tourService.initialize([{
  anchorId: 'some.anchor.id',
  content: 'Some content',
  title: 'First',
}, {
  anchorId: 'another.anchor.id',
  content: 'Other content',
  title: 'Second',
}]);

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	The route to which the tour should navigate before attempting to show this tour step. If undefined, no navigation is attempted.
nextStep	number	string	undefined	The step index or stepId of the next step. If undefined, the next step in the steps array is used.
prevStep	number	string	undefined	The step index or stepId of the previous step. If undefined, the previous step in the steps array is used.
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.initialize(steps, {{ '{' }}
  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((steps: IStep[]) => {{ '{' }}
  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:

<ngx-bootstrap-product-tour>
  <ng-template #tourStep>
    <p class="tour-step-content">{{tourService.currentStep.content}}</p>
    <div class="tour-step-navigation">
      <button *ngIf="tourService.hasPrev(tourService.currentStep)" class="btn btn-sm btn-default" (click)="tourService.prev()">« Prev</button>
      <button *ngIf="tourService.hasNext(tourService.currentStep)" class="btn btn-sm btn-default" (click)="tourService.next()">Next »</button>
      <button class="btn btn-sm btn-error" (click)="tourService.end()">End</button>
    </div>
  </ng-template>
</ngx-bootstrap-product-tour>