Skip to content

semos/nzTour

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

94 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

nzTour

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

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!

About

Touring and on-boarding made simple for AngularJS -

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 77.7%
  • CSS 13.0%
  • HTML 9.3%