Skip to content

NMilicic/ngx-bootstrap-product-tour

Repository files navigation

ngx-bootstrap-product-tour

npm version

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

  1. npm i ngx-bootstrap-product-tour ngx-bootstrap bootstrap
  2. Import NgxBootstrapProductTourModule.forRoot() into your app module
  3. Make sure RouterModule is imported in your app module
  4. Include bootstrap css.

Usage

  1. Add <ngx-bootstrap-product-tour></ngx-bootstrap-product-tour> to your root app component

  2. Define anchor points for the tour steps by adding the tourAnchor directive throughout your app.

    <div tourAnchor="some.anchor.id">...</div>
  3. 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',
    }]);
  4. 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.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>