2 * jQuery Foundation Joyride Plugin 2.1
3 * http://foundation.zurb.com
5 * Free to use under the MIT license.
6 * http://www.opensource.org/licenses/mit-license.php
9 /*jslint unparam: true, browser: true, indent: 2 */
11 ;(function ($, window, undefined) {
16 'tipLocation' : 'bottom', // 'top' or 'bottom' in relation to parent
17 'nubPosition' : 'auto', // override on a per tooltip bases
18 'scroll' : true, // whether to scroll to tips
19 'scrollSpeed' : 300, // Page scrolling speed in milliseconds
20 'timer' : 0, // 0 = no timer , all other numbers = timer in milliseconds
21 'autoStart' : false, // true or false - false tour starts when restart called
22 'startTimerOnClick' : true, // true or false - true requires clicking the first button start the timer
23 'startOffset' : 0, // the index of the tooltip you want to start on (index of the li)
24 'nextButton' : true, // true or false to control whether a next button is used
25 'tipAnimation' : 'fade', // 'pop' or 'fade' in each tip
26 'pauseAfter' : [], // array of indexes where to pause the tour after
27 'tipAnimationFadeSpeed': 300, // when tipAnimation = 'fade' this is speed in milliseconds for the transition
28 'cookieMonster' : false, // true or false to control whether cookies are used
29 'cookieName' : 'joyride', // Name the cookie you'll use
30 'cookieDomain' : false, // Will this cookie be attached to a domain, ie. '.notableapp.com'
31 'cookiePath' : false, // Set to '/' if you want the cookie for the whole website
32 'localStorage' : false, // true or false to control whether localstorage is used
33 'localStorageKey' : 'joyride', // Keyname in localstorage
34 'tipContainer' : 'body', // Where will the tip be attached
35 'modal' : false, // Whether to cover page with modal during the tour
36 'expose' : false, // Whether to expose the elements at each step in the tour (requires modal:true)
37 'postExposeCallback' : $.noop, // A method to call after an element has been exposed
38 'preRideCallback' : $.noop, // A method to call before the tour starts (passed index, tip, and cloned exposed element)
39 'postRideCallback' : $.noop, // A method to call once the tour closes (canceled or complete)
40 'preStepCallback' : $.noop, // A method to call before each step
41 'postStepCallback' : $.noop, // A method to call after each step
42 'template' : { // HTML segments for tip layout
43 'link' : '<a href="#close" class="joyride-close-tip">X</a>',
44 'timer' : '<div class="joyride-timer-indicator-wrap"><span class="joyride-timer-indicator"></span></div>',
45 'tip' : '<div class="joyride-tip-guide"><span class="joyride-nub"></span></div>',
46 'wrapper' : '<div class="joyride-content-wrapper" role="dialog"></div>',
47 'button' : '<a href="#" class="joyride-next-tip"></a>',
48 'modal' : '<div class="joyride-modal-bg"></div>',
49 'expose' : '<div class="joyride-expose-wrapper"></div>',
50 'exposeCover': '<div class="joyride-expose-cover"></div>'
54 Modernizr = Modernizr || false,
60 init : function (opts) {
61 return this.each(function () {
63 if ($.isEmptyObject(settings)) {
64 settings = $.extend(true, defaults, opts);
66 // non configurable settings
67 settings.document = window.document;
68 settings.$document = $(settings.document);
69 settings.$window = $(window);
70 settings.$content_el = $(this);
71 settings.$body = $(settings.tipContainer);
72 settings.body_offset = $(settings.tipContainer).position();
73 settings.$tip_content = $('> li', settings.$content_el);
74 settings.paused = false;
75 settings.attempts = 0;
77 settings.tipLocationPatterns = {
79 bottom: [], // bottom should not need to be repositioned
80 left: ['right', 'top', 'bottom'],
81 right: ['left', 'top', 'bottom']
84 // are we using jQuery 1.7+
85 methods.jquery_check();
87 // can we create cookies?
88 if (!$.isFunction($.cookie)) {
89 settings.cookieMonster = false;
92 // generate the tips and insert into dom.
93 if ( (!settings.cookieMonster || !$.cookie(settings.cookieName) ) &&
94 (!settings.localStorage || !methods.support_localstorage() || !localStorage.getItem(settings.localStorageKey) ) ) {
96 settings.$tip_content.each(function (index) {
97 methods.create({$li : $(this), index : index});
101 if(settings.autoStart)
103 if (!settings.startTimerOnClick && settings.timer > 0) {
104 methods.show('init');
105 methods.startTimer();
107 methods.show('init');
113 settings.$document.on('click.joyride', '.joyride-next-tip, .joyride-modal-bg', function (e) {
116 if (settings.$li.next().length < 1) {
118 } else if (settings.timer > 0) {
119 clearTimeout(settings.automate);
122 methods.startTimer();
130 settings.$document.on('click.joyride', '.joyride-close-tip', function (e) {
132 methods.end(true /* isAborted */);
135 settings.$window.on('resize.joyride', function (e) {
137 if(settings.exposed && settings.exposed.length>0){
138 var $els = $(settings.exposed);
139 $els.each(function(){
141 methods.un_expose($this);
142 methods.expose($this);
145 if (methods.is_phone()) {
148 methods.pos_default();
159 // call this method when you want to resume the tour
160 resume : function () {
166 if (settings.$li.next().length < 1) {
168 } else if (settings.timer > 0) {
169 clearTimeout(settings.automate);
172 methods.startTimer();
179 tip_template : function (opts) {
180 var $blank, content, $wrapper;
182 opts.tip_class = opts.tip_class || '';
184 $blank = $(settings.template.tip).addClass(opts.tip_class);
185 content = $.trim($(opts.li).html()) +
186 methods.button_text(opts.button_text) +
187 settings.template.link +
188 methods.timer_instance(opts.index);
190 $wrapper = $(settings.template.wrapper);
191 if (opts.li.attr('data-aria-labelledby')) {
192 $wrapper.attr('aria-labelledby', opts.li.attr('data-aria-labelledby'))
194 if (opts.li.attr('data-aria-describedby')) {
195 $wrapper.attr('aria-describedby', opts.li.attr('data-aria-describedby'))
197 $blank.append($wrapper);
198 $blank.first().attr('data-index', opts.index);
199 $('.joyride-content-wrapper', $blank).append(content);
204 timer_instance : function (index) {
207 if ((index === 0 && settings.startTimerOnClick && settings.timer > 0) || settings.timer === 0) {
210 txt = methods.outerHTML($(settings.template.timer)[0]);
215 button_text : function (txt) {
216 if (settings.nextButton) {
217 txt = $.trim(txt) || 'Next';
218 txt = methods.outerHTML($(settings.template.button).append(txt)[0]);
225 create : function (opts) {
226 // backwards compatibility with data-text attribute
227 var buttonText = opts.$li.attr('data-button') || opts.$li.attr('data-text'),
228 tipClass = opts.$li.attr('class'),
229 $tip_content = $(methods.tip_template({
230 tip_class : tipClass,
232 button_text : buttonText,
236 $(settings.tipContainer).append($tip_content);
239 show : function (init) {
240 var opts = {}, ii, opts_arr = [], opts_len = 0, p,
244 if (settings.$li === undefined || ($.inArray(settings.$li.index(), settings.pauseAfter) === -1)) {
246 // don't go to the next li if the tour was paused
247 if (settings.paused) {
248 settings.paused = false;
250 methods.set_li(init);
253 settings.attempts = 0;
255 if (settings.$li.length && settings.$target.length > 0) {
256 if(init){ //run when we first start
257 settings.preRideCallback(settings.$li.index(), settings.$next_tip );
259 methods.show_modal();
262 settings.preStepCallback(settings.$li.index(), settings.$next_tip );
265 opts_arr = (settings.$li.data('options') || ':').split(';');
266 opts_len = opts_arr.length;
267 for (ii = opts_len - 1; ii >= 0; ii--) {
268 p = opts_arr[ii].split(':');
270 if (p.length === 2) {
271 opts[$.trim(p[0])] = $.trim(p[1]);
274 settings.tipSettings = $.extend({}, settings, opts);
275 settings.tipSettings.tipLocationPattern = settings.tipLocationPatterns[settings.tipSettings.tipLocation];
277 if(settings.modal && settings.expose){
281 // scroll if not modal
282 if (!settings.$target.is("body") && settings.scroll) {
286 if (methods.is_phone()) {
287 methods.pos_phone(true);
289 methods.pos_default(true);
292 $timer = $('.joyride-timer-indicator', settings.$next_tip);
294 if (/pop/i.test(settings.tipAnimation)) {
296 $timer.outerWidth(0);
298 if (settings.timer > 0) {
300 settings.$next_tip.show();
302 width: $('.joyride-timer-indicator-wrap', settings.$next_tip).outerWidth()
307 settings.$next_tip.show();
312 } else if (/fade/i.test(settings.tipAnimation)) {
314 $timer.outerWidth(0);
316 if (settings.timer > 0) {
318 settings.$next_tip.fadeIn(settings.tipAnimationFadeSpeed);
320 settings.$next_tip.show();
322 width: $('.joyride-timer-indicator-wrap', settings.$next_tip).outerWidth()
327 settings.$next_tip.fadeIn(settings.tipAnimationFadeSpeed);
332 settings.$current_tip = settings.$next_tip;
333 // Focus next button for keyboard users.
334 $('.joyride-next-tip', settings.$current_tip).focus();
335 methods.tabbable(settings.$current_tip);
336 // skip non-existent targets
337 } else if (settings.$li && settings.$target.length < 1) {
348 settings.paused = true;
354 // detect phones with media queries if supported.
355 is_phone : function () {
357 return Modernizr.mq('only screen and (max-width: 767px)');
360 return (settings.$window.width() < 767) ? true : false;
363 support_localstorage : function () {
365 return Modernizr.localstorage;
367 return !!window.localStorage;
372 if(settings.modal && settings.expose){
376 $('.joyride-modal-bg').hide();
378 settings.$current_tip.hide();
379 settings.postStepCallback(settings.$li.index(), settings.$current_tip);
382 set_li : function (init) {
384 settings.$li = settings.$tip_content.eq(settings.startOffset);
385 methods.set_next_tip();
386 settings.$current_tip = settings.$next_tip;
388 settings.$li = settings.$li.next();
389 methods.set_next_tip();
392 methods.set_target();
395 set_next_tip : function () {
396 settings.$next_tip = $('.joyride-tip-guide[data-index=' + settings.$li.index() + ']');
399 set_target : function () {
400 var cl = settings.$li.attr('data-class'),
401 id = settings.$li.attr('data-id'),
404 return $(settings.document.getElementById(id));
406 return $('.' + cl).filter(":visible").first();
412 settings.$target = $sel();
415 scroll_to : function () {
416 var window_half, tipOffset;
418 window_half = settings.$window.height() / 2;
419 tipOffset = Math.ceil(settings.$target.offset().top - window_half + settings.$next_tip.outerHeight());
421 $("html, body").stop().animate({
423 }, settings.scrollSpeed);
426 paused : function () {
427 if (($.inArray((settings.$li.index() + 1), settings.pauseAfter) === -1)) {
434 destroy : function () {
435 if(!$.isEmptyObject(settings)){
436 settings.$document.off('.joyride');
439 $(window).off('.joyride');
440 $('.joyride-close-tip, .joyride-next-tip, .joyride-modal-bg').off('.joyride');
441 $('.joyride-tip-guide, .joyride-modal-bg').remove();
442 clearTimeout(settings.automate);
446 restart : function () {
447 if(!settings.autoStart)
449 if (!settings.startTimerOnClick && settings.timer > 0) {
450 methods.show('init');
451 methods.startTimer();
453 methods.show('init');
455 settings.autoStart = true;
460 settings.$li = undefined;
461 methods.show('init');
465 pos_default : function (init) {
466 var half_fold = Math.ceil(settings.$window.height() / 2),
467 tip_position = settings.$next_tip.offset(),
468 $nub = $('.joyride-nub', settings.$next_tip),
469 nub_width = Math.ceil($nub.outerWidth() / 2),
470 nub_height = Math.ceil($nub.outerHeight() / 2),
471 toggle = init || false;
473 // tip must not be "display: none" to calculate position
475 settings.$next_tip.css('visibility', 'hidden');
476 settings.$next_tip.show();
479 if (!settings.$target.is("body")) {
481 topAdjustment = settings.tipSettings.tipAdjustmentY ? parseInt(settings.tipSettings.tipAdjustmentY) : 0,
482 leftAdjustment = settings.tipSettings.tipAdjustmentX ? parseInt(settings.tipSettings.tipAdjustmentX) : 0;
484 if (methods.bottom()) {
485 settings.$next_tip.css({
486 top: (settings.$target.offset().top + nub_height + settings.$target.outerHeight() + topAdjustment),
487 left: settings.$target.offset().left + leftAdjustment});
489 if (/right/i.test(settings.tipSettings.nubPosition)) {
490 settings.$next_tip.css('left', settings.$target.offset().left - settings.$next_tip.outerWidth() + settings.$target.outerWidth());
493 methods.nub_position($nub, settings.tipSettings.nubPosition, 'top');
495 } else if (methods.top()) {
497 settings.$next_tip.css({
498 top: (settings.$target.offset().top - settings.$next_tip.outerHeight() - nub_height + topAdjustment),
499 left: settings.$target.offset().left + leftAdjustment});
501 methods.nub_position($nub, settings.tipSettings.nubPosition, 'bottom');
503 } else if (methods.right()) {
505 settings.$next_tip.css({
506 top: settings.$target.offset().top + topAdjustment,
507 left: (settings.$target.outerWidth() + settings.$target.offset().left + nub_width) + leftAdjustment});
509 methods.nub_position($nub, settings.tipSettings.nubPosition, 'left');
511 } else if (methods.left()) {
513 settings.$next_tip.css({
514 top: settings.$target.offset().top + topAdjustment,
515 left: (settings.$target.offset().left - settings.$next_tip.outerWidth() - nub_width) + leftAdjustment});
517 methods.nub_position($nub, settings.tipSettings.nubPosition, 'right');
521 if (!methods.visible(methods.corners(settings.$next_tip)) && settings.attempts < settings.tipSettings.tipLocationPattern.length) {
523 $nub.removeClass('bottom')
525 .removeClass('right')
526 .removeClass('left');
528 settings.tipSettings.tipLocation = settings.tipSettings.tipLocationPattern[settings.attempts];
532 methods.pos_default(true);
536 } else if (settings.$li.length) {
538 methods.pos_modal($nub);
543 settings.$next_tip.hide();
544 settings.$next_tip.css('visibility', 'visible');
549 pos_phone : function (init) {
550 var tip_height = settings.$next_tip.outerHeight(),
551 tip_offset = settings.$next_tip.offset(),
552 target_height = settings.$target.outerHeight(),
553 $nub = $('.joyride-nub', settings.$next_tip),
554 nub_height = Math.ceil($nub.outerHeight() / 2),
555 toggle = init || false;
557 $nub.removeClass('bottom')
559 .removeClass('right')
560 .removeClass('left');
563 settings.$next_tip.css('visibility', 'hidden');
564 settings.$next_tip.show();
567 if (!settings.$target.is("body")) {
571 settings.$next_tip.offset({top: settings.$target.offset().top - tip_height - nub_height});
572 $nub.addClass('bottom');
576 settings.$next_tip.offset({top: settings.$target.offset().top + target_height + nub_height});
577 $nub.addClass('top');
581 } else if (settings.$li.length) {
583 methods.pos_modal($nub);
588 settings.$next_tip.hide();
589 settings.$next_tip.css('visibility', 'visible');
593 pos_modal : function ($nub) {
597 methods.show_modal();
601 show_modal : function() {
602 if ($('.joyride-modal-bg').length < 1) {
603 $('body').append(settings.template.modal).show();
606 if (/pop/i.test(settings.tipAnimation)) {
607 $('.joyride-modal-bg').show();
609 $('.joyride-modal-bg').fadeIn(settings.tipAnimationFadeSpeed);
618 randId = 'expose-'+Math.floor(Math.random()*10000);
619 if (arguments.length>0 && arguments[0] instanceof $){
621 } else if(settings.$target && !settings.$target.is("body")){
622 el = settings.$target;
628 console.error('element not valid', el);
632 expose = $(settings.template.expose);
633 settings.$body.append(expose);
635 top: el.offset().top,
636 left: el.offset().left,
637 width: el.outerWidth(true),
638 height: el.outerHeight(true)
640 exposeCover = $(settings.template.exposeCover);
642 zIndex: el.css('z-index'),
643 position: el.css('position')
645 el.css('z-index',expose.css('z-index')*1+1);
646 if(origCSS.position == 'static'){
647 el.css('position','relative');
649 el.data('expose-css',origCSS);
651 top: el.offset().top,
652 left: el.offset().left,
653 width: el.outerWidth(true),
654 height: el.outerHeight(true)
656 settings.$body.append(exposeCover);
657 expose.addClass(randId);
658 exposeCover.addClass(randId);
659 if(settings.tipSettings['exposeClass']){
660 expose.addClass(settings.tipSettings['exposeClass']);
661 exposeCover.addClass(settings.tipSettings['exposeClass']);
663 el.data('expose', randId);
664 settings.postExposeCallback(settings.$li.index(), settings.$next_tip, el);
665 methods.add_exposed(el);
668 un_expose: function(){
674 if (arguments.length>0 && arguments[0] instanceof $){
676 } else if(settings.$target && !settings.$target.is("body")){
677 el = settings.$target;
683 console.error('element not valid', el);
687 exposeId = el.data('expose');
688 expose = $('.'+exposeId);
689 if(arguments.length>1){
690 clearAll = arguments[1];
692 if(clearAll === true){
693 $('.joyride-expose-wrapper,.joyride-expose-cover').remove();
697 origCSS = el.data('expose-css');
698 if(origCSS.zIndex == 'auto'){
699 el.css('z-index', '');
701 el.css('z-index',origCSS.zIndex);
703 if(origCSS.position != el.css('position')){
704 if(origCSS.position == 'static'){// this is default, no need to set it.
705 el.css('position', '');
707 el.css('position',origCSS.position);
710 el.removeData('expose');
711 el.removeData('expose-z-index');
712 methods.remove_exposed(el);
715 add_exposed: function(el){
716 settings.exposed = settings.exposed || [];
718 settings.exposed.push(el[0]);
719 } else if(typeof el == 'string'){
720 settings.exposed.push(el);
724 remove_exposed: function(el){
728 } else if (typeof el == 'string'){
731 settings.exposed = settings.exposed || [];
732 for(var i=0; i<settings.exposed.length; i++){
733 if(settings.exposed[i] == search){
734 settings.exposed.splice(i,1);
740 center : function () {
741 var $w = settings.$window;
743 settings.$next_tip.css({
744 top : ((($w.height() - settings.$next_tip.outerHeight()) / 2) + $w.scrollTop()),
745 left : ((($w.width() - settings.$next_tip.outerWidth()) / 2) + $w.scrollLeft())
751 bottom : function () {
752 return /bottom/i.test(settings.tipSettings.tipLocation);
756 return /top/i.test(settings.tipSettings.tipLocation);
759 right : function () {
760 return /right/i.test(settings.tipSettings.tipLocation);
764 return /left/i.test(settings.tipSettings.tipLocation);
767 corners : function (el) {
768 var w = settings.$window,
769 window_half = w.height() / 2,
770 tipOffset = Math.ceil(settings.$target.offset().top - window_half + settings.$next_tip.outerHeight()),//using this to calculate since scroll may not have finished yet.
771 right = w.width() + w.scrollLeft(),
772 offsetBottom = w.height() + tipOffset,
773 bottom = w.height() + w.scrollTop(),
784 if(offsetBottom > bottom){
785 bottom = offsetBottom;
789 el.offset().top < top,
790 right < el.offset().left + el.outerWidth(),
791 bottom < el.offset().top + el.outerHeight(),
792 w.scrollLeft() > el.offset().left
796 visible : function (hidden_corners) {
797 var i = hidden_corners.length;
800 if (hidden_corners[i]) return false;
806 nub_position : function (nub, pos, def) {
807 if (pos === 'auto') {
814 startTimer : function () {
815 if (settings.$li.length) {
816 settings.automate = setTimeout(function () {
819 methods.startTimer();
822 clearTimeout(settings.automate);
826 end : function (isAborted) {
827 isAborted = isAborted || false;
829 // Unbind resize events.
831 settings.$window.off('resize.joyride');
834 if (settings.cookieMonster) {
835 $.cookie(settings.cookieName, 'ridden', { expires: 365, domain: settings.cookieDomain, path: settings.cookiePath });
838 if (settings.localStorage) {
839 localStorage.setItem(settings.localStorageKey, true);
842 if (settings.timer > 0) {
843 clearTimeout(settings.automate);
845 if(settings.modal && settings.expose){
848 if (settings.$current_tip) {
849 settings.$current_tip.hide();
852 settings.postStepCallback(settings.$li.index(), settings.$current_tip, isAborted);
853 settings.postRideCallback(settings.$li.index(), settings.$current_tip, isAborted);
855 $('.joyride-modal-bg').hide();
858 jquery_check : function () {
859 // define on() and off() for older jQuery
860 if (!$.isFunction($.fn.on)) {
862 $.fn.on = function (types, sel, fn) {
864 return this.delegate(sel, types, fn);
868 $.fn.off = function (types, sel, fn) {
870 return this.undelegate(sel, types, fn);
880 outerHTML : function (el) {
881 // support FireFox < 11
882 return el.outerHTML || new XMLSerializer().serializeToString(el);
885 version : function () {
886 return settings.version;
889 tabbable : function (el) {
890 $(el).on('keydown', function( event ) {
891 if (!event.isDefaultPrevented() && event.keyCode &&
893 event.keyCode === 27 ) {
894 event.preventDefault();
895 methods.end(true /* isAborted */);
899 // Prevent tabbing out of tour items.
900 if ( event.keyCode !== 9 ) {
903 var tabbables = $(el).find(":tabbable"),
904 first = tabbables.filter(":first"),
905 last = tabbables.filter(":last");
906 if ( event.target === last[0] && !event.shiftKey ) {
908 event.preventDefault();
909 } else if ( event.target === first[0] && event.shiftKey ) {
911 event.preventDefault();
918 $.fn.joyride = function (method) {
919 if (methods[method]) {
920 return methods[method].apply(this, Array.prototype.slice.call(arguments, 1));
921 } else if (typeof method === 'object' || !method) {
922 return methods.init.apply(this, arguments);
924 $.error('Method ' + method + ' does not exist on jQuery.joyride');