Code Monkey home page Code Monkey logo

nztour's Introduction

⛔️ 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

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!

nztour's People

Contributors

tannerlinsley avatar masimplo avatar bmartinelle avatar lebolo avatar danielpquinn avatar lucas-garcia avatar nozzle avatar gitter-badger avatar steve-mc avatar

Stargazers

Ridineu de Moraes Neto avatar Christoffer Klemming avatar Joe Chung avatar Chris Posada avatar  avatar Israel Oliveira avatar Justin avatar Matt Blum avatar  avatar Paulo avatar Alin Dobra avatar Mike P. Sinn avatar Rock Liu avatar Endre Varga avatar ms_bit avatar Nicolai Robles avatar Vladimir Komarov avatar Erich Schutz avatar Andrii Iasko avatar Arvind Ravulavaru avatar Oliver avatar Tim Elfelt avatar  avatar  avatar Pablo Maurer avatar Aleksander avatar  avatar Michael Robinson avatar Peter Connolly avatar Ivan Ivanov avatar Johnny IV Young Ospino avatar Sebastian Lietzijewitsch avatar LogikIO avatar  avatar Nucleas avatar Daniel Leite de Oliveira avatar  avatar Cristian Cedeño avatar datboylalaki avatar Morgan Intrator avatar BryanW avatar Ali Niknafs avatar  avatar  avatar David Hill avatar  avatar liusong avatar  avatar hcxiong avatar Adam Jaffe Back avatar Emile Keith avatar Ashish Tilara avatar Yin Gang avatar XianDian avatar Jordan Berry avatar Loring Dodge avatar Francisco Hernandez avatar JP Camara avatar  avatar David Li avatar James Crowson avatar Projets DIY avatar Rajul avatar Panos Vog avatar Ophir Stern avatar Jamie Holly avatar  avatar Zack Vera avatar Sean Duncan avatar Tyler Renelle avatar Joe Bergevin avatar Derek Perkins avatar  avatar

Watchers

Wojciech Zimirski avatar  avatar Gabriela Assis avatar James Cloos avatar  avatar Joe Bergevin avatar Derek Perkins avatar Beacon avatar  avatar Emile Keith avatar  avatar  avatar  avatar

nztour's Issues

direction is returning 'undefined' instead of -1 or 1

Hi,

I was trying to use one of the in built functionality to track the movement of tooltip (forward or backward) using:

before: function(direction){
                console.log("direction",direction); // returns undefined
                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;
            }

but the direction is always undefined

Can you please help me out with this?

elem[_addEventListener] is not a function

Hello,

I must say I am impressed with your tour! I was having problems with z-index with previous tours where this one seems to work with no issues! I am however experiencing an error in the console.

elem[_addEventListener] is not a function

This only happens when I set scrollThrough option to false. It seems to be thrown from the following lines
if (config.mask.scrollThrough === false) {
window.addWheelListener(els.masks_wrap, stopMaskScroll);
}

Also, I am using UI router in a SPA if that matters.

Thanks.

Is it possible to disable shortcuts

I have some functionality in the "after" of some of my steps. I would like the user not to be able to get back to that step without restarting. Is this possible, Also on a side note can the previous button be disabled? At the moment I am simply hiding it.

Change scrollBox Config when nzTour Active?

Hello, everyone.

First, i thank you for this great Angular Tour plugin.

Currently, i am developing tour feature using this plugin. I want to ask, is there a way to change 'scrollBox' configuration when the plugin is active?

Thank you

Mask not visible

I'm not getting the mask for some reason, I don't suppose I've done something wrong?

            config: {
                mask: {
                    visible: true, // Shows the element mask
                    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 while hovered over the mask
                    color: 'rgba(0,0,0,.7)' // The mask color
                },
                container: '.container-fluid', // The container to mask
                scrollBox: '.container-fluid', // The container to scroll when searching for elements
                previousText: 'Previous',
                nextText: 'Next',
                finishText: 'Finish',
                animationDuration: 400, // Animation Duration for the box and mask
                dark: false // Dark mode (Works great with `mask.visible = false`)
            }

Tooltip partly offscreen (left v. right)

I have a tooltip showing on the left, that should show on the right, on an iPhone 5S - it goes offscreen on the side it's shown. Is this something I'm doing wrong? Is there some way I could get this working without having to hard-code the side ot show it on?

tooltip on wrong side

Thanks,
Craig

ngshow not working

Hello, the next button is hide. i work with angular 1.4.3

Html output:

Entendido

{
"dependencies": {
"nz-tour": "~1.0.1"
},
"devDependencies": {
"ionic": "ionic-team/ionic-bower#1.2.1",
}
}

How do check if a tour is active?

The api doesn't explain how I should check if a tour is currently active. Trying to advance the tour automatically when the user interacts with the ui (via nzTour.gotoStep()) but if the tour is currently not active, then we get this error:

screen shot 2016-05-20 at 9 07 01 am

innerContent is not defined

Hi,

I'm getting innerContent is not defined when I scroll a step box with a lot of text inside.
The error is in onBoxScroll function at line 472

innerContent should be accessible from els variable, this code fix the issue :
if (!up && (els.innerContent.height() - els.content.height() == scrollTop)) { return prevent(e); }

Masks all stacked at top of page

I'm not sure exactly what change I did to my css that would cause this, but the masks for nzTour now all appear to be stacked at the top left of the page.

eg, .mask.bottom css has bottom at 0 and height set, but it doesn't sit at the bottom of the page, it's basically at top: 0 with the height set.

Saving events to localStorage/cookies

Hi,

I was finally able to implement this into a complex app. But now I'm trying to store the user's actions to localStorage or $cookies so that the tour will only appear once for a user.

Any advice?

CC: @nozzle

slight flicker

Hello,

I am seeing a white line 'flicker' when the tour starts, especially when scrolling. I see it in IE and chrome.

Edit - Also happening on the example provided

Multiple Page Tours

Is there support for multiple-page tours? Perhaps something like:
steps: [{ url:"/", target: '#icons', content: "testing" }]

Firefox autoscroll is not working

Hi, The tour is working on Chrome and IE. However only on firefox autoscrolling doesn't work when the next section in tour points to a place where we need to scroll.

Service is not defined issue.

I am getting Following Error :-

ReferenceError: service is not defined
My code is as following

.controller('PlaylistsCtrl', function($scope,nzTour) {
  var tour = {
     config: {
        mask: {
            visible: true, // Shows the element mask
            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 while hovered over the mask
            color: 'rgba(0,0,0,.7)' // The mask color
        },
        container: 'body', // The container to mask
        scrollBox: 'body', // The container to scroll when searching for elements
        previousText: 'Previous',
        nextText: 'Next',
        finishText: 'Finish',
        animationDuration: 400, // Animation Duration for the box and mask
        dark: false // Dark mode (Works great with `mask.visible = false`)
    } ,
    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!')
    });

Tour box has been cut off

I am using nz-tour 1.2.0 in my cordova project and having my box being chop off from left. Any advices is appreciated . thanks

screen shot 2017-01-15 at 4 32 10 pm

Here is the config object

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

Masks separate momentarily during some animations

Known issue. The graphical portion of the masks will most likely be replaced soon by a canvas element that is more graphically capable of accurate transitions. The mouse-event catcher will probably stay as transparent versions of the current masks.

CSS issues with viewing on mobile browser

Hey! Nice work! I found this project via the angular buddies chat. I tested it on mobile (iPhone 6) and it displayed weird.

I'll be looking into this in further detail later.

On iphone 6, landscape the popup is off the screen

The popup on iphone 6 is off the screen and a black bar shows up instead. We tried this with your plunkr code and showed the same issue. I have attached 3 files.

  1. Shows popup screen offscreen

0-ea-d1-be6bff4d834bf00b0aa32ffe0f8d3ac7
2. You have to manually scroll to see the popup

0-ea-d1-1d13e011c6228ebcb380200bee085ce3
3. When you go to the Next step a black line appears

0-ea-d2-6538b4bb8ae919f3bfab03f52d8cc083

$compile syntax error

nzTour Version >= 1.1.0 throws errors if content contains punctuation marks. For example:
var stepHtml = 'Welcome. Click Next to get started!'
--> Syntax error, unrecognized expression: Welcome. Click Next to get started!

The following code is the error source:
var compiledHtml = $compile(stepHtml)($scope);

I use Angular 1.5.7

Support for images inside a step

First of all, great project and work. Really enjoy the many features, especially promised based before & after support.

Have you considered adding support for letting the user specify images inside a step?

What I found out is that I can use markup inside the content, such as this:

tour.steps = [{ target: '#tour-field-list-container', content: '<strong>When creating reports</strong><br>Select fields by checking the box or dragging to the columns list.', }, {

This would create a dialog looking like this:
screen shot 2016-05-20 at 8 15 06 am

Next I was going to try to provide an image tag to see if that would work... but it would be great to be able to provide:
title: <title>,
content: <... the above...>
image:

To build something out of the box...

Thoughts?

Working with Modals

Has anyone experienced issues with scrolling and modals?

Update - works after setting scrollBox: '.modal', but the last step won't scroll to the bottom of the modal. Any attempt to scroll down forces the user back up.

Update - Uncaught ReferenceError: innerContent is not define

I fixed by using the following (it's hacky but I need to finish implementing this)
before: function(){
var d = $q.defer();
$(".modal").scrollTop(0);
d.resolve(); // or d.reject()
return d.promise
}

Disabling Tagged Elements During Tour

Is there a way to disable the tagged elements, if applicable, while the tour is happening?

I run into the issue that one of my tour steps is a button and people are inclined to press the button during the tour, instead of next. I'd like to disable the button.

.left and .center classed applied in wrong case

When the highlighted area is left of the tip, the small arrow is white and at the wrong place.

Problem is (I think) that .left and .center get applied:

.nz-tour #nzTour-box.dark-box #nzTour-tip.center { left: 50%; }

.nz-tour #nzTour-box.dark-box #nzTour-tip.left { left: 5px; }

Screenshot: http://imgur.com/ma477zG

Scroll is not working

Hi,
I've one scroll at the right sidebar, on the main body I don't have scroll but on the right side some data with the scroll.
I've applied tour on that data but when step moves to down it does not scroll. I've attached scroll shot of my
When the tour starts right side scroll is the overlay.
screenshot at Oct 01 19-13-50

Icon on a header-bar is not recignized

Hello, I was testing your tour and I found it amazing. I'm testing now with Ionic and the menu but while works perfectly with other icons, if I try to add a icon that is on the header bar, the tour goes on the top but doesn't get the icone neither on the left nor on the right.

Any ideas?

Then and catch don't work

I know this isn't an actively worked on project, but just documenting for others to see.
.then(function() { console.log('Tour Finished!'); }) .catch(function() { console.log('Tour Aborted!') });

The "Tour Finished" fires off immediately when you launch and the catch never executes whether you click X or click outside on the backdrop to close.

Internationalization

Thanks a lot for this great plugin!
I just wonder if it's possible to use internationalization/translation with it (something like https://github.com/angular-translate/angular-translate for instance)? I'm unfortunately not an Angular pro yet, but I think the reason why it currently doesn't work is because of the $compile():

var compiledHtml = $compile(stepHtml)($scope);

Or is there any way already how to use translation with nzTour?

(Could be related to #28 - "I would first explore making it so directives compile inside the content")

service.cleanup is not a function

When closing the tour I get this logged service.cleanup is not a function and then although the backdrop is removed I cannot click / scroll on the page.

I noticed in your code that you are declaring $scope.cleanup, but then are using service.cleanup. Is this some kind of mixup?

Scroll is not working on overlay

When the tour starts then it overlays body and scroll is not working.

If my content is on the below then it's don't got to down and scroll to that particular step. Stuck at the last stage and I need to escape the tour.

screenshot at oct 05 18-02-58

how to prevent click on highlight eliment

I was expecting "disableInteraction: true" might prevent the click on targeted element. But it doesn't seem to work for me. Is there a way to explicitly disable click event on it ? Thanks .

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.