ng3-tour-test v0.1.7

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 { }

2. Import the NgTourModule in your Feature Modules:

    @NgModule({
        declarations: [FeatureComponent],
        imports: [
            NgTourModule.forChild(),
        ],
        providers: [],
        })
    export class FeatureModule { }

3. Use ngIfTour directive inside app.component.html. A good choice is marking <router-outlet> with it.

    <route-outlet ngIfTour></route-outlet>

5. Mark your target HTML elements with the ngTourStep directive with a unique name.

    <div ngTourStep="first">...</div>
    <span ngTourStep="second">...</span>

5. 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) { }
    }

6. Create a configuration object and pass it as an argument to the startTour method

const tour = {
    steps: [
        {
            stepName: "first",
            route: "home",
            title: 'My first lazily loaded feature',
            description: "My first feature description", 
            options: {backdrop: true}
        },
        {
            stepName: "nextStep",
            route: "about",
            title: "My second lazily loaded feature",
            description: "My second feature description",
            options:{placement: 'top', smoothScroll: true}
        }
    ],
    tourOptions: {
        backdrop: false,
    }
}

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="step$" tourStepData (next)="onNext($event)" (done)="onDone($event)">
    <div  class="tour-step-modal__content" *ngIf="refToExportAs.step$ | 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)" (done)="onDone($event)">
                &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.adds}}
                </p>
                <p class="tour-step-modal__adds">
                {{step.customData}}
                </p>
                <p *ngIf="step.index===3" class="tour-step-modal__adds"> 
                StepName of this step is {{step.StepName}}
                </p>
            </div>
            <div class="tour-step-modal__footer">
                <div *ngIf="!step.options.withoutCounter" class="tour-step-modal__counter">
                {{step.index + 1}} of {{step.total}}
                </div>
                <button
                *ngIf="!step.options.withoutPrev && step.index" 
                type="button" 
                class="tour-btn"
                stepEvent="prev"
                >
                {{step.ctrlBtns.prev}}
                </button>
                <button
                *ngIf="step.index + 1 !== step.total"
                type="button"
                class="tour-btn tour-btn-next"
                stepEvent="next"  
                (next)="onNext($event)"
                >
                {{step.ctrlBtns.next}}
                </button>
                <button
                *ngIf="step.index + 1 === step.total"
                type="button"
                class="tour-btn tour-btn-done"
                stepEvent="close"
                (done)="onDone($event)"
                >
                {{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.

ctrlBtns: {
  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',
  },
}

API reference

Tour Properties

Tour configuration object contains steps array and could include common options, event handlers and set of control button names Name | Required | Type | Destination -----|----|----|--------| steps | yes | TourStep[] | This option define Tour Steps and its order | tourEvents | no | TourEventsI | define event handlers for 'tour start', 'tour break', 'tour end', 'next step', 'prev step' | tourOption | no | TourStepI | Set common options. Could be redefined with Step options ctrlBtns | no | CtrlBtnsI | Set 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).

Step Properties (StepOptions)

DefaultCtrlBtns:

{
    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',
    },
}

Services

TourService methods:

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 @Input | Required | Description | Values/Type --------|----------|-------------|------------- ngTourStep | yes | The value should be unique string | string

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.

Components

ng-tour-step-template

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