node package manager
Orgs are free. Discover, share, and reuse code in your team. Create a free org »

nz-tour

nzTour

Join the chat at https://gitter.im/nozzle/nzTour Touring and on-boarding made simple for AngularJS.

Awesome Demo

Features

  • Responsive & Intelligent
  • Automagic Positioning
  • Promise Driven Events & Hooks (Because we <3 Angular)
  • nzTour doesn't touch your DOM (more info below)

Installation & Usage

  1. $ bower/npm install nz-tour --save
  2. Include jQuery (before Angular)
  3. Include dist/nz-tour.min.js and dist/nz-tour.min.css files.
  4. Add nzTour as a dependency in your app.
  5. Inject the nzTour service anywhere in your app.

Simple Usage

var tour = {
    config: {} // see config 
    steps: [{
        target: '#first-element',
        content: 'This is the first step!',
    }, {
        target: '.some .other .element',
        placementPriority: [ 'right', 'top', 'bottom', 'left' ],
        content: 'Blah blah blah. I prefer to show up on the right.',
    }, {
        target: '#menu-element',
        content: 'I guess this is a menu!',
    }, {
        target: '#last-element',
        content: 'It is over! :(',
    }]
};
 
nzTour.start(service.tours[tour])
    .then(function() {
        console.log('Tour Finished!');
    })
    .catch(function() {
        console.log('Tour Aborted!')
    });
 

Config

Defaults:

var tour = {
    config: {
        mask: {
            visible: true, // Shows the element mask 
            visibleOnNoTarget: false, // Shows a full page mask if no target element has been specified 
            clickThrough: false, // Allows the user to interact with elements beneath the mask 
            clickExit: false, // Exit the tour when the user clicks on the mask 
            scrollThrough: true // Allows the user to scroll the scrollbox or window through the mask 
            color: 'rgba(0,0,0,.7)' // The mask color 
        },
        scrollBox: 'body', // The container to scroll when searching for elements 
        previousText: 'Previous',
        nextText: 'Next',
        finishText: 'Finish',
        showPrevious: true, // Setting to false hides the previous button 
        showNext: true // Setting to false hides the next button 
        animationDuration: 400, // Animation Duration for the box and mask 
        placementPriority: ['bottom', 'right', 'top','left'],
        dark: false, // Dark mode (Works great with `mask.visible = false`) 
        disableInteraction: false, // Disable interaction with the highlighted elements 
        highlightMargin: 0, // Margin of the highglighted area 
        disableEscExit: false // Disable end of tour when pressing ESC, 
        onClose: function() {} //Function called when the tour is closed 
        onComplete: function() {} //Function called when the tour is completed 
    },
    steps: []
}

Shortcut Keys

  • Left/Right Arrow keys - Previous/Next
  • Esc - Abort the tour
  • 1-9 - Goto step 1-9

API

.start(tour) - Starts a Tour

Params:

  • tour: Tour Object

Returns:

  • Promise that resolves when the tour is finished and rejected when aborted.

.stop() - Stops a Tour

Returns:

  • Promise that resolves when the tour is stopped.

.pause() - Pauses a Tour

Returns:

  • Promise that resolves when the tour is paused and hidden.

.next() - Goes to the next step in the current tour

Returns:

  • Promise that resolves when the next step is reached

.previous() - Goes to the previous step in the current tour

  • Promise that resolves when the previous step is reached

.gotoStep(step): - Goes to a specific step in the tour

Params:

  • step: The number of the step starting at 1,2,3...

Returns:

  • Promise that resolves when the specific step is reached

Promising Event Hooks

  • Before - function that returns a promise
  • After - function that returns a promise

Example

var tour = {
    steps: [{
        target: '#first-element',
        content: 'This is the first step!',
    }, {
        target: '.some .other .element',
        content: 'Blah blah blah.',
        showPrevious: false,
        before: function(direction){
            if(direction === -1)
                console.log('coming from next step');
            else if (direction === 1)
                console.log('coming from previous step');
            else
                console.log('started at this step');
 
         var d = $q.defer();
         // Do something amazing 
         d.resolve(); // or d.reject() 
         return d.promise
     }
    }, {
        target: '#menu-element',
        content: 'I guess this is a menu!',
        after: function(direction){
         var d = $q.defer();
         // Do some more cool stuff 
         d.resolve(); // or d.reject() 
         return d.promise
     }
    }, {
        target: '#last-element',
        content: 'It is over! :(',
    }]
}

Roadmap & Contributing

  • Update example
  • Reduce footprint
  • Dynamic Masking (opening select boxes and dynamically moving content)
  • Remove dependency on jQuery
  • Use angular $animate for animations and class changes
  • Add more hooks and config for customization

All PR's and contributions are more than welcome!