Socket
Socket
Sign inDemoInstall

ng3-tour

Package Overview
Dependencies
9
Maintainers
1
Versions
11
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

ng3-tour

An Angular Tour (ng3-tour) light library is built entirely in Angular and allows you easily master guide for your users through your site showing them all the sections and features including lazily loaded.


Version published
Maintainers
1
Weekly downloads
1
decreased by-50%

Weekly downloads

Readme

Source

ng3-Tour

An Angular Tour (ng3-tour) light library is built entirely in Angular and allows you easily master guide for your users through your site showing them all the sections and features including lazily loaded.

For Angular 2+ (2, 4, 5, 6, 7, 8)

Installation

npm install --save ng3-tour

Usage

  1. Import the NgTourModule in your AppModule:
import {AngularTourModule} from 'ng3-tour';

@NgModule({
    declarations: [AppComponent],
    imports: [
            RouterModule.forRoot([]),
            AngularTourModule.forRoot(),
            BrowserModule
    ],
    providers: [],
    bootstrap: [AppComponent]
    })
export class AppModule { }
  1. Import the NgTourModule in your Feature Modules:
    @NgModule({
        declarations: [FeatureComponent],
        imports: [
            NgTourModule.forChild(),
        ],
        providers: [],
        })
    export class FeatureModule { }
  1. Use ngIfTour directive inside app.component.html. A good choice is marking <router-outlet> with it.
    <route-outlet ngIfTour></route-outlet>
  1. Mark your target HTML elements with the ngTourStep directive with a unique name.
    <div ngTourStep="first">...</div>
    <span ngTourStep="second">...</span>
  1. Inject NgTourService in your Component (where Tour is being started).

    @Component({
        selector: 'component-of-your-choice',
        templateUrl: './your.component.html'
    })
    export class ComponentOfYourChoice {
        constructor(private readonly tourService: TourService) { }
    }
  1. Create a configuration object and pass it as an argument to the startTour method
const tour: Tour = {
    steps: [
        {
            stepName: "first",
            route: "first-feature",
            title: 'My first lazily loaded feature',
            description: "My first feature description", 
        },
        {
            stepName: "nextStep",
            route: "second-feature",
            title: "My second lazily loaded feature",
            description: "My second feature description",
            options:{placement: 'top', smoothScroll: true}
        }
    ],
    tourOptions: {
        backdrop: false,
        placement: 'right',
    }
}

Keep in mind if you implement your own Step template, you can use your own Step properties besides required ('stepName' and 'route')

ngOnInit() {
    this.tourService.startTour(tour);
}

or

onClick() {
    this.tourService.startTour(tour);
}

Customizing

If you want to use tour own Step template wrap it with <ng-tour-step-template> and place in app.component.html. Mark the provided template with reference with assigned value 'step$' that gives you access to steps Stream. To handle controls event you could use tourEvent directive with corresponded input value (one of 'next', 'prev', 'close')

<ng-tour-step-template #refToExportAs="steps$">
    <div  class="tour-step-modal__content" *ngIf="refToExportAs.steps$ | async as step">
        <div >
            <div class="tour-step-modal__header">
                <h3 class="tour-step-modal__title"> 
                    {{step.title}}
                </h3>
                <button
                    class="tour-btn-close"
                    type="button"
                    stepEvent="close"
                    (break)="onBreak($event)" // add this line if you want to handle the event is emitted after a corresponded user action. Of cause, the handler's name is up to you.
                    (done)="onDone($event)" // to handle the event is emitted after a corresponded user action
                >
                    &times;
                </button>
            </div>
            <div class="tour-step-modal__body">
                <p class="tour-step-modal__description">
                    {{step.description}}
                </p>
                <p class="tour-step-modal__adds">
                    {{step.customData}}
                </p>
            </div>
            <div class="tour-step-modal__footer">
                <div *ngIf="!step.options.withoutCounter" class="tour-step-modal__counter">
                    {{step.index + 1}} {{step.ctrlBtns.of} {{step.total}}
                </div>
                <button
                    *ngIf="!step.options.withoutPrev && step.index" 
                    type="button" 
                    class="tour-btn"
                    stepEvent="prev"
                    (prev)="onPrev($event)" // to handle the event is emitted after a corresponded user action
                >
                    {{step.ctrlBtns.prev}}
                </button>
                <button
                    *ngIf="step.index + 1 !== step.total"
                    type="button"
                    class="tour-btn tour-btn-next"
                    stepEvent="next"  
                    (next)="onNext($event)" // to handle the event is emitted after a corresponded user action
                >
                    {{step.ctrlBtns.next}}
                </button>
                <button
                    *ngIf="step.index + 1 === step.total"
                    type="button"
                    class="tour-btn tour-btn-done"
                    stepEvent="close"
                    (done)="onDone($event)" // to handle the event is emitted after a corresponded user action
                >
                    {{step.ctrlBtns.done}}
                </button>
            </div>
        </div>
    </div>
</ng-tour-step-template>

Keep in mind if you use <ng-tour-step-template> and ngIfTour at the same time 'customTemplate' option is set to true programmatically. If you omit ngIfTour and want to use your own Step template set this option to true manually.

Internalization

If you implement a custom Step template you can implement any Internalization you want, but if you use the provided Step template you can not do so. There is an embedded one for this case.

You can pass an object with the required translations to the Step properties the title and the description.

title: {
    'en-EN': 'My first feature',
    'ru-RU': 'Моя первая фича',
    'fr-FR': 'Mon premier caractéristique',
}

You also can define t he required translations for the Step controls. Simply pass the corresponded object to the Tour option ctrlBtns. There is default value below.

defaultTranslation {
    done: {
        'en-EN': 'done',
        'ru-RU': 'закр',
        'fr-FR': 'fini',
    },
    prev: {
        'en-EN': 'prev',
        'ru-RU': 'пред',
        'fr-FR': 'préc'
    },
    next: {
        'en-EN': 'next',
        'ru-RU': 'след',
        'fr-FR': 'proch',
    },
    of: {
        'en-EN': 'of',
        'ru-RU': "из",
        'fr-FR': 'de',
    }
}

API reference

Tour Properties

Tour configuration object contains steps array and could include common options, event handlers and set of control button names

NameRequiredTypeDestination
stepsyesTourStep[]This option define Tour Steps and its order
tourEventsnoTourEventsdefine event handlers for 'tour start', 'tour break', 'tour end', 'next step', 'prev step'
tourOptionnoTourStepSet common options. Could be redefined with Step options
ctrlBtnsnoCtrlBtnsSet translations of the control buttons for any languages you want
Tour Events

These events are functions witch is called within corresponded tourService methods. You can pass your own implementation of these functions within tourEvent property for example to collect some statistical data about user behavior. Keep in mind Tour Events unlike Step Events could fire without user activity in case continueIfTargetAbsent property is set to true (default value).

NameRequiredPropsDescription
tourStartno{tourEvent: string, tour?: Tour}Add logic executed before the Tour will be started
tourBreakno{tourEvent: string, step?: number, history?: number[]}Add logic executing before the Tour will be stoped untimely
tourEndno{tourEvent: string, step?: number, history?: number[]}Add logic executing before the Tour will be stopped after finishing (latest step was visited)
nextno{tourEvent: string, step?: number, history?: number[]}Add logic executing before the next step will be initiated
prevno{tourEvent: string, step?: number, history?: number[]}Add logic executing before the previous step will be initiated

Step Properties

NameRequiredTypeDestinationDefault value
stepNameyesstringDefine unique name of the Step
routeyesstringDefine route corresponded to the Step
indexnonumber'Index' value is set by TourService service according to the position of the Step in the Steps array
titlenostringSet title of the current Step""
descriptionnostringSet description of the current Step""
ctrlBtnsnoCtrlBtnsSet translations of the control buttons for any languages you want[see below] (#defaultCtrlBtns)
optionsnoStepOptionsTo customize separate Stepdescribed below
options:
classNamenostringSet custom class to the Step component""
themeColornostringDefine theme color'rgb(20, 60, 60)'
backdropnobooleanAdd backdrop if option set truetrue
opacitynonumberDefine the backdrop opacity.6
placementnostringThis option define position of step modal relative to target. Possible values: 'down', 'top', 'left', 'right', 'center', 'right-center', 'left-center', right-top', 'left-top' ( case no matter )"Down"
customTemplatenobooleanThis option has by default value true if you used <ng-tour-step-template> and directive ngIfTour simultaneously, otherwise false.true/false
withoutCounternobooleanIf true remove counter including a number of the step and total number of steps from the Step templatefalse
withoutPrevnobooleanIf true remove 'Prev' control button from the Step templatefalse
arrowToTargetnobooleanIf true add arrow in direction corresponded location of the Step targettrue
scrollTonobooleanIf value equals true, the window is scrolled to show Step target and modal (popup)true
scrollSmoothnobooleanIf true option behavior of the window scroll is set to smoothfalse
continueIfTargetAbsentnobooleanIf true and the Step target is absent will initialize the next Steptrue
animatedStepnobooleanIf true add classes to control css animationtrue
fixednobooleanIf value equals true position css property of the Step Component and Backdrop Component is set to the 'fixed', otherwise 'absolute'false
animationDelaynonumberRequired in case of routing with lazy loaded Feature Modules. Delay defined in ms500
stepTargetResizenonumber[]Change size in px of the Step target window. Number with index 0 define Width. Number with index 1 if exist define Height differ from the Width[0]
minWidthnostringDefine min-width of the Step modal'200px'
minHeightnostringDefine min-height of the Step modal'200px'
maxWidthnostringDefine max-width of the Step modal'400px'
maxHeightnostringDefine max-height of the Step modal'400px'
autofocusnobooleanIf true 'next' and 'done' buttons obtain focustrue
closeOnClickOutsidenobooleanIf true any click outside step modal will cause closing the Tour. This is maybe useful if you set backdrop options to false and user have access to your site controls (for example navigation menu)false

Services

TourService methods:
NameArgsDescriptionReturn
main:
startTourtour: Tourstart Tour (The only necessary to use this lib)void
prevStepCall initStep with previous stepNamevoid
nextStepCall initStep with next stepNamevoid
stopTourstop Tourvoid
additional:
getStepsStreamReturn the steps observablesteps$
resetStepstringnumber, TourStepChange Step configuration
getHistoryreturn array of the indexes of the passed StepsstepIndexes[]
getStepByNamestringreturn the Step with the given stepNameTourStep
getStepByIndexnumberreturn the Step with the given indexTourStep
getLastStepreturn the last initialized StepTourStep
isRouteChangedreturn true if the route property of the current Step differs from the previous oneboolean
getTourStatusreturn true if Tour startedboolean

Directives

ngIfTour

This directive is similar to a structural one if it is used solo without <ng-tour-step-template>. In this case, ngIfTour adds provided Step template to the DOM after the Tour is started and removes it after the Tour is stoped. If ngIfTour is used along with <ng-tour-step-template> (no matter which element was marked with directive <ng-tour-step-template> or some other) it make only one thing it set 'customTemplate' property to true.

ngTourStep

This directive is required to mark Step target

@InputRequiredDescriptionValues/Type
ngTourStepyesThe value should be unique stringstring
stepEvent

This directive binds listeners (with corresponded Tour methods) to Step's controls and emits corresponded events. It may come in handy if you want to master your own Step template.

@Input | Required | Destination --------|----------|-------|------------- stepEvent | required | Possible values are 'next' , 'prev' and 'close'. Value predefines which handler will be implemented for the click event.

@OutputPropsDestination
next{tourEvent: string, step: number, history: number[]}Emit 'next' event with described props. The destination is the same as tourEvents have
prev{tourEvent: string, step: number, history number[]}Emit 'prev' event with described props.
break{tourEvent: string, step: number, history: number[]}Emit 'break' event with described props.
done{tourEvent: string, step: number, history: number[]}Emit 'done' event with described props.

Components

ng-tour-step-template
OutputPropsDescription
next{tourEvent: string, step: number, history: number[]}Emit 'next' event with described props. The destination is the same as tourEvents have
prev{tourEvent: string, step: number, history: number[]}Emit 'prev' event with described props.
break{tourEvent: string, step: number, history: number[]}Emit 'break' event with described props.
done{tourEvent: string, step: number, history: number[]}Emit 'done' event with described props.

SCSS Customizing

You can easily redefine styles of the provided Step template in any scss files importing in style.scss file of your project.

Main selectors
NameSelect
.tour-step-modalStep (includes provided template and custom template)
.tour-step-modal__contentprovided Step template
.tour-step-modal__headerprovided Step header (includes title and Close control)
.tour-btn-closeClose control
.tour-step-modal__titleprovided Step title
.tour-step-modal__bodyprovided Step body (includes Step description)
.tour-step-modal__descriptionprovided Step description
.tour-step-modal__footerprovided Step footer (includes Step controls Next, Prev, Done, and Counter)
.tour-step-modal__counterCounter
.tour-btn-nextNext control
.tour-btn-prevPrev control
.tour-btn-doneDone control
.tour-btnCommon selector for Step footer controls

Keywords

FAQs

Last updated on 10 Mar 2020

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc