JarCasting
⛔️
DEPRECATED
This repo is no longer being maintained (issues and pull requests are not being monitored). Consider using https://github.com/tourjs/Tour instead. If you would like to take over, please open an issue.
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.jsanddist/nz-tour.min.cssfiles. - Add
nzTouras a dependency in your app. - Inject the
nzTourservice 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!