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
$ bower/npm install nz-tour --save
- Include jQuery (before Angular)
- Include
dist/nz-tour.min.js
anddist/nz-tour.min.css
files. - Add
nzTour
as a dependency in your app. - 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! :(' ; nzTourstartservicetourstour ;
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, {} //Function called when the tour is closed {} //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 { ifdirection === -1 console; else if direction === 1 console; else console; var d = $qdefer; // Do something amazing d; // or d.reject() return dpromise } target: '#menu-element' content: 'I guess this is a menu!' { var d = $qdefer; // Do some more cool stuff d; // or d.reject() return dpromise } 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!