ngx_drive

Installation

Install using npm ->

1. npm i ngx-drive
2. npm i driver.js (peer dependency)
3. "node_modules/driver.js/dist/driver.min.css" (Angular.Json Styles)

SetUp

In AppComponent init ngx-drive ->

import { NgxDriveService } from 'ngx-drive';
constructor(private readonly tourDriver : NgxDriveService){}

In AppModule -->

import { NgxDriveModule } from 'ngx-drive';
imports: [
  NgxDriveModule
],

Basic Usage

1. In AppComponent import your config Data in the struture ngx-drive defines for (later in docs) ->

import * as <dataVar> from <PATH_TO_CONFIG-TS>

Example -

import tourData from './tour/tourConfig'

2. In AppComponent Start the tour by binding the below code snippet to a button-event (Function) ->

this.driver.tourStart(data);

Example -

onClick(){
    this.driver.tourStart(data, <initDelay : number>); // initDelay is a number in ms to delay the tour to start in the starting (for targetElement i.e. first-step to render completely) [OPTIONAL]
  }

Resume Tour Functionality -

To call in for resume tour pass a parameter as shown below -

start(){
    this.driver.tourStart(data, 500, parseInt((localStorage.getItem("lastStep")))); // stored in local storage as key-value pair, updated automatically.
  }

Config File

The previously described Config File must be of the below interface ->

const data = {}

export { data }

{
    // libConfig are Global Config Object, these can be overwrite for specific steps too (later) 
    // [All are optional to pass]
    "libConfig" : {
        "className" : "scoped-class", // className to wrap popover
        "closeBtnText" : "Close", // Text on Close button
        "nextBtnText" : "Next", // Text on Next button
        "prevBtnText" : "Previous", // Text on Previous button
        "allowClose" : false, // Whether the click on overlay(Background) should close or not
        "animate" : false, // Whether to animate or not
        "opacity" : 0.75, // Background opacity (0 means only popovers and without overlay)
        "padding" : 10, // Distance of element from around the edges
        "keyboardControl" : true, // Allow controlling through keyboard (escape to close, arrow keys to move)
        "showButtons" : true, // Do not show control buttons in footer
        "stageBackground" : "#ffffff",  // Background color for the staged behind highlighted element
        "nextDelay" : 200,  // waitingTime in between steps when moving next (applicable on all steps)
        "previousDelay" : 200,  // waitingTime in between steps when moving previous (applicable on all steps)
        "navDelay" : 300, // waitingTime for Multi-Page Navigation for full rendering of targetElement (applicable on all steps)
        "stepStatus" : true, // currStep / Total Step showcasing
      },
    // tour object is a [{}] with struture as following, 
    // you can overwrite the Global Config for specific Steps
    "tour" : [
        {
        "targetStep" : string, // example - "#hero1@/heroes" i.e. <ID-ELEMENT@ROUTE>, [REQUIRED]
        "stageBackground" : "#ffffff", // [OPTIONAL]
        "title" : "Title of popover, can also parse HTML",  // [OPTIONAL]
        "description" : "Description of popover, can also parse HTML",  // [OPTIONAL]
        "position" : "left"  // position can be left, left-center, left-bottom, top, top-center, top-right, right, right-center, right-bottom, bottom, bottom-center, bottom-right, mid-center [OPTIONAL] 
        "className" : "popover-class",  // className to wrap this specific step popover in addition to the general className in Driver options, useful for specific Styling Options [OPTIONAL]
        "showButtons" : false, // [OPTIONAL]
        "closeBtnText" : "close", // [OPTIONAL]      
        "nextBtnText" : "Next",  // [OPTIONAL]        
        "prevBtnText" : "Previous",  // [OPTIONAL]
        "nextTime" : 1000, // [OPTIONAL] waitingTime to be set for this specific step when moving forward in tour
        "prevTime" : 500 // [OPTIONAL] waitingTime to be set for this specific step when moving backward in tour
        }
    ]
}

CAUTION - Never contain a single step for a particular page when performing Multi page Navigation!

Basic Usage - Time based Tour

Follow all steps stated in the earlier Basic Usage -

Differences -

Step 2 =>

In AppComponent Start the tour by binding the below code snippet to a button-event (Function) ->

this.driver.timedTour(data);

Example -

onClick(){
    this.driver.timedTour(data);
  }

Configuration File -

const data = {}

export { data }

{
    // libConfig are Global Config Object, these can be overwrite for specific steps too (later) 
    // [All are optional to pass]
    "libConfig" : {
        "className" : "scoped-class", // className to wrap popover
        "animate" : false, // Whether to animate or not
        "opacity" : 0.75, // Background opacity (0 means only popovers and without overlay)
        "padding" : 10, // Distance of element from around the edges
        "stepStatus" : true, // currStep / Total Step showcasing
        "stageBackground" : "#ffffff",  // Background color for the staged behind highlighted element
        "waitingTime" : 2000 // time in between steps global value
      },
    // tour object is a [{}] with struture as following, 
    // you can overwrite the Global Config for specific Steps
    "tour" : [
        {
        "targetStep" : string, // example - "#hero1@/heroes" i.e. <ID-ELEMENT@ROUTE>, [REQUIRED]
        "stageBackground" : "#ffffff", // [OPTIONAL]
        "title" : "Title of popover, can also parse HTML",  // [OPTIONAL]
        "description" : "Description of popover, can also parse HTML",  // [OPTIONAL]
        "position" : "left"  // position can be left, left-center, left-bottom, top, top-center, top-right, right, right-center, right-bottom, bottom, bottom-center, bottom-right, mid-center [OPTIONAL] 
        "className" : "popover-class",  // className to wrap this specific step popover in addition to the general className in Driver options, useful for specific Styling Options [OPTIONAL]
        "waitingTime" : 1500 // time in between this step and next step
        }
    ]
}

Styling (Customization)

.className .driver-popover-tip {} // Styling for Tip (Arrow)
.className .driver-popover-title {} // Styling for Header
.className .driver-popover-description {} // Styling for Body
.className .driver-popover-footer {} // Styling for Footer
.className .driver-close-btn {} // Close button styling
.className .driver-btn-group .driver-prev-btn {} // Close button styling
.className .driver-btn-group .driver-next-btn {} // Close button styling
.className #ngx-status {} // currStep / Total Step styling

the default driver-popover-item styling options ->  (controlable by className and !important in global CSS)

background: #fff;
color: #2d2d2d;
margin: 0;
padding: 15px;
border-radius: 5px;
min-width: 250px;
max-width: 300px;
box-shadow: 0 1px 10px rgba(0,0,0,.4);

Future Updates -

1. Time based Navigation (Multi page navigation issue).
2. Child Steps.