Placeholder

An easy-to-use jQuery plugin that adds an intuitive, interactive, dynamic guided tour to your website.

', { + 'class': 'guides-fade-in guides-guide ' + this._class, + 'html': '' + this.guide.html + '' + }); + this._position(); + return this; +}; + +Guide.prototype._position = function () { + if (this.$highlightedElement && this.$highlightedElement.length > 0) { + this._attachToElement(); + this.$guide.appendTo(this.$container); + this._renderArrow(); + } else { + this._center(); + } + this._scrollIntoView(); +}; + +Guide.prototype._center = function () { + this.$guide + .css('visibility', 'hidden') + .appendTo(this.$container) + .addClass('guides-center') + .css({ + left: 0, + right: 0, + textAlign: 'center', + top: (window.innerHeight / 2) - (this.$guide.outerHeight() / 2) + }).css('visibility', 'visible'); +}; + +Guide.prototype._attachToElement = function () { + var elOffset = this.$highlightedElement.offset(), + docWidth = $('body').width(), + docHeight = $('body').height(), + leftSpace = elOffset.left, + topSpace = elOffset.top, + highlightedElementWidth = this.$highlightedElement.outerWidth(), + highlightedElementHeight = this.$highlightedElement.outerHeight(), + rightSpace = docWidth - leftSpace - highlightedElementWidth, + bottomSpace = docHeight - topSpace - highlightedElementHeight, + css = { + color: this._color, + top: docHeight / 2 > elOffset.top ? elOffset.top : 'auto', + left: docWidth / 2 > elOffset.left ? elOffset.left : 'auto', + right: docWidth / 2 > elOffset.left ? 'auto' : docWidth - elOffset.left - highlightedElementWidth, + bottom: docHeight / 2 > elOffset.top ? 'auto' : elOffset.bottom + }; + + switch (Math.max(leftSpace, rightSpace, topSpace, bottomSpace)) { + case leftSpace: + this.position = 'left'; + css.paddingRight = this._distance; + css.right = $(document).width() - elOffset.left; + css.left = 'auto'; + break; + case topSpace: + this.position = 'top'; + css.paddingBottom = this._distance; + css.bottom = $(document).height() - elOffset.top; + css.top = 'auto'; + break; + case rightSpace: + this.position = 'right'; + css.paddingLeft = this._distance; + css.left = elOffset.left + highlightedElementWidth; + css.right = 'auto'; + break; + default: + this.position = 'bottom'; + css.paddingTop = this._distance; + css.top = elOffset.top + highlightedElementHeight; + css.bottom = 'auto'; + break; + } + this.$guide.addClass('guides-' + this.position).css(css); +}; + +Guide.prototype._renderArrow = function() { + this._width = this.$guide.outerWidth(); + this._height = this.$guide.outerHeight(); + this.$guide.append(format(this._arrowTemplate, + this._width, this._distance, this[this.position](), this._arrowSize, this._color)); +}; + +Guide.prototype.top = function () { + var coord = this._verticalAlign(); + return this._getPath(coord); +}; + +Guide.prototype.bottom = function () { + var coord = this._verticalAlign(true); + return this._getPath(coord); +}; + +Guide.prototype.left = function () { + var coord = this._horizontalAlign(); + return this._getPath(coord); +}; + +Guide.prototype.right = function () { + var coord = this._horizontalAlign(true); + return this._getPath(coord); +}; + +Guide.prototype._getPath = function (coord) { + return format(this._path, coord.x1, coord.y1, coord.dx1, coord.dy1, coord.dx2, coord.dy2, coord.x2, coord.y2); +}; + +Guide.prototype._getFluctuation = function () { + return Math.floor(Math.random() * 20) + 10; +}; + +Guide.prototype._verticalAlign = function (bottom) { + var x1 = this._width / 2, + y1 = bottom ? this._distance : 0, + x2 = Math.max( + Math.min( + this.$highlightedElement.offset().left + (this.$highlightedElement.outerWidth() / 2) - this.$guide.offset().left, + this._width - this._arrowSize), + this._arrowSize), + y2 = bottom ? this._arrowSize : this._distance - this._arrowSize; + return { + x1: x1, + y1: y1, + x2: x2, + y2: y2, + dx1: Math.max(0, Math.min(Math.abs((2 * x1) - x2) / 3, this._width) + this._getFluctuation()), + dy1: bottom + ? Math.max(0, y2 + (Math.abs(y1 - y2) * 3 / 4)) + : Math.max(0, y1 + (Math.abs(y1 - y2) * 3 / 4)), + dx2: Math.max(0, Math.min(Math.abs(x1 - (x2 * 3)) / 2, this._width) - this._getFluctuation()), + dy2: bottom + ? Math.max(0, y2 + (Math.abs(y1 - y2) * 3 / 4)) + : Math.max(0, y1 + (Math.abs(y1 - y2) * 3 / 4)) + } +}; + +Guide.prototype._horizontalAlign = function (right) { + var x1 = right ? this._distance : this._width - this._distance, + y1 = this._height / 2, + x2 = right ? this._arrowSize : this._width - this._arrowSize, + y2 = Math.max( + Math.min( + this.$highlightedElement.offset().top + (this.$highlightedElement.outerHeight() / 2) - this.$guide.offset().top, + this._height - this._arrowSize), + this._arrowSize); + return { + x1: x1, + y1: y1, + x2: x2, + y2: y2, + dx1: right + ? Math.max(0, x2 + (Math.abs(x1 - x2) * 3 / 4)) + : Math.max(0, x1 + Math.abs(x1 - x2) * 3 / 4), + dy1: Math.max(0, Math.min(Math.abs((2 * y1) - y2) / 3, this._height) + this._getFluctuation()), + dx2: right + ? Math.max(0, x2 + (Math.abs(x1 - x2) * 3 / 4)) + : Math.max(0, x1 + Math.abs(x1 - x2) * 3 / 4), + dy2: Math.max(0, Math.min(Math.abs(y1 - (y2 * 3)) / 2, this._height) + this._getFluctuation()) + } +}; + +Guide.prototype._scrollIntoView = function () { + if (this.$highlightedElement.length === 0) { + $('html,body').animate({ + scrollTop: 0 + }, 500); + return; + } + var guideOffset = this.$guide.offset(), + top = guideOffset.top, + bottom = guideOffset.top + this.$guide.outerHeight(), + left = guideOffset.left, + right = guideOffset.left + this.$guide.outerWidth(), + scrollTop = $(document).scrollTop(), + scrollLeft = $(document).scrollLeft(); + + //scroll vertically to element if it is not visible in the view port + if (scrollTop > top || scrollTop + $(window).height() < bottom) { + $('html,body').animate({ + scrollTop: this.position === 'bottom' ? top - 100 : top + }, 500); + } + + //scroll horizontally to element if it is not visible in the view port + if (scrollLeft > left || scrollLeft + $(window).width() < right) { + $('html,body').animate({ + scrollLeft: this.position === 'righ' ? left - 100 : left + }, 500); + } +}; + +Guide.prototype.destroy = function() { + this.$highlightedElement.removeClass('guides-current-element'); + this.$guide.remove(); +}; + +module.exports = Guide; \ No newline at end of file Index: reference/jquery-plugins/guided-tour-arrow/src/modules/Guides.js =================================================================== diff -u --- reference/jquery-plugins/guided-tour-arrow/src/modules/Guides.js (revision 0) +++ reference/jquery-plugins/guided-tour-arrow/src/modules/Guides.js (revision 10417a3908ef7516203be30712af4d355287973b) @@ -0,0 +1,156 @@ +var Guide = require('./Guide'); + +var Guides = function (element, options) { + this.element = element; + this.$element = $(element); + this.options = {}; + this._current = 0; + this.setOptions(options); + if (element) { + this.$element.on('click.guides', $.proxy(this.start, this)); + } +}; + +Guides.DEFAULTS = { + distance: 100, + color: '#fff', + cssClass: '', + guides: [] +}; + +Guides.prototype.start = function(e) { + if (e) { + e.preventDefault(); + } + if (this._isAlreadyRunning()) { + return this; + } + this._current = 0; + this._renderCanvas() + ._renderGuide(this.options.guides[this._current]) + ._callback('start'); + return this; +}; + +Guides.prototype.end = function() { + if (this.$canvas) { + this.$canvas.remove(); + this.$canvas = null; + } + if (this._currentGuide) { + this._currentGuide.destroy(); + this._currentGuide = null; + } + $(document).off('keyup.guides'); + this._callback('end'); + return this; +}; + +Guides.prototype.next = function () { + this._renderGuide(this.options.guides[++this._current]) + ._callback('next'); + return this; +}; + +Guides.prototype.prev = function () { + if (!this._current) { + return; + } + this._renderGuide(this.options.guides[--this._current]) + ._callback('prev'); + return this; +}; + +Guides.prototype.setOptions = function(options) { + if (typeof options !== 'object') { + return this; + } + this.options = $.extend({}, Guides.DEFAULTS, this.options, options); +}; + +Guides.prototype.destroy = function() { + this.end(); + this.$element.off('click.guides'); + this._callback('destroy'); + return this; +}; + +Guides.prototype._callback = function (eventName) { + var callback = this.options[eventName], + eventObject = { + sender: this + }; + + if (this._currentGuide) { + eventObject.$element = this._currentGuide.guide.element; + eventObject.$guide = this._currentGuide.$element; + } + + if ($.isFunction(callback)) { + callback.apply(this, [eventObject]); + } +}; + +Guides.prototype._isAlreadyRunning = function () { + return !!this.$canvas; +}; + +Guides.prototype._renderCanvas = function () { + this.$canvas = $('

', { + 'class': 'guides-canvas guides-fade-in', + 'html': '

' + }).appendTo('body'); + this._bindNavigation(); + return this; +}; + +Guides.prototype._renderGuide = function (guide) { + if (!guide) { //no more guides + this.end(); + return this; + } + + if (this._currentGuide) { + this._currentGuide.destroy(); + } + + this._callback('render', guide); + + if ($.isFunction(guide.render)) { + guide.render.apply(this, [guide]); + } + + this._currentGuide = new Guide(guide, this.$canvas, this.options); + return this; +}; + +Guides.prototype._bindNavigation = function () { + this.$canvas.on('click.guides', $.proxy(this._onCanvasClick, this)); + $(document).on('keyup.guides', $.proxy(this._onDocKeyUp, this)); + return this; +}; + +Guides.prototype._onCanvasClick = function (e) { + this.next(); +}; + +Guides.prototype._onDocKeyUp = function (e) { + switch (e.which) { + case 27: //esc + this.end(); + break; + case 39: //right arrow + case 32: //space + this.next(); + break; + case 37: //left arrow + case 8: //backspace + e.preventDefault(); + this.prev(); + break; + default: + break; + } +}; + +module.exports = Guides; \ No newline at end of file Index: reference/jquery-plugins/guided-tour-arrow/src/modules/format.js =================================================================== diff -u --- reference/jquery-plugins/guided-tour-arrow/src/modules/format.js (revision 0) +++ reference/jquery-plugins/guided-tour-arrow/src/modules/format.js (revision 10417a3908ef7516203be30712af4d355287973b) @@ -0,0 +1,8 @@ +module.exports = function format () { + var s = arguments[0]; + for (var i = 0; i < arguments.length - 1; i++) { + var reg = new RegExp("\\{" + i + "\\}", "gm"); + s = s.replace(reg, arguments[i + 1]); + } + return s; +}; \ No newline at end of file Index: reference/jquery-plugins/guided-tour-arrow/test/Guide.spec.js =================================================================== diff -u --- reference/jquery-plugins/guided-tour-arrow/test/Guide.spec.js (revision 0) +++ reference/jquery-plugins/guided-tour-arrow/test/Guide.spec.js (revision 10417a3908ef7516203be30712af4d355287973b) @@ -0,0 +1,164 @@ +var Guide = require('../src/modules/Guide'); + +describe('Guide class tests', function() { + var $element, + $container = $('

', { + position: 'absolute', + top: 0, + left: 0, + bottom: 0, + right: 0, + height: window.innerHeight, + width: window.innerWidth + }).appendTo('body'), + options = { + color: '#fff', + cssClass: '', + distance: 100 + }; + + beforeEach(function () { + $element = $('

Test

', {position: 'absolute'}).appendTo('body'); + }); + + afterEach(function () { + $element.remove(); + }); + + it('auto positions - right', function() { + $element.width(20); + $element.height(window.innerHeight); + $element.offset({top: 0, left: 0}); + guide = new Guide({ + element: $element, + html: 'Magna esse aliquet laborum et felis euismod' + }, $container, options); + expect(guide.position).toBe('right'); + }); + + it('auto positions - bottom', function() { + $element.width(window.innerWidth); + $element.height(20); + $element.offset({top: 0, left: 0}); + guide = new Guide({ + element: $element, + html: 'Magna esse aliquet laborum et felis euismod' + }, $container, options); + expect(guide.position).toBe('bottom'); + }); + + it('auto positions - left', function() { + $element.width(20); + $element.height(window.innerHeight); + $element.offset({ + top: 0, + left: $(document).width() - $element.width() + }); + guide = new Guide({ + element: $element, + html: 'Magna esse aliquet laborum et felis euismod' + }, $container, options); + expect(guide.position).toBe('left'); + }); + + it('auto positions - top', function() { + $element.width(window.innerWidth); + $element.height(20); + $element.offset({ + top: $(document).height() - $element.height(), + left: 0 + }); + guide = new Guide({ + element: $element, + html: 'Magna esse aliquet laborum et felis euismod' + }, $container, options); + expect(guide.position).toBe('top'); + }); + + it('creates an svg with a curve that fits the container (top)', function() { + $element.width(window.innerWidth); + $element.height(20); + $element.offset({ + top: $(document).height() - $element.height(), + left: 0 + }); + guide = new Guide({ + element: $element, + html: 'Magna esse aliquet laborum et felis euismod' + }, $container, options); + + var coord = guide._verticalAlign(); + expect(coord.x1 < 0).toBe(false); + expect(coord.x1 > this._width).toBe(false); + expect(coord.y1 < 0).toBe(false); + expect(coord.y1 > this._distance).toBe(false); + expect(coord.dx1 < 0).toBe(false); + expect(coord.dx1 > this._width).toBe(false); + expect(coord.dy1 < 0).toBe(false); + expect(coord.dy1 > this._distance).toBe(false); + }); + + it('creates an svg with a curve that fits the container (bottom)', function() { + $element.width(window.innerWidth); + $element.height(20); + $element.offset({top: 0, left: 0}); + guide = new Guide({ + element: $element, + html: 'Magna esse aliquet laborum et felis euismod' + }, $container, options); + + var coord = guide._verticalAlign(); + expect(coord.x1 < 0).toBe(false); + expect(coord.x1 > this._width).toBe(false); + expect(coord.y1 < 0).toBe(false); + expect(coord.y1 > this._distance).toBe(false); + expect(coord.dx1 < 0).toBe(false); + expect(coord.dx1 > this._width).toBe(false); + expect(coord.dy1 < 0).toBe(false); + expect(coord.dy1 > this._distance).toBe(false); + }); + + it('creates an svg with a curve that fits the container (left)', function() { + $element.width(20); + $element.height(window.innerHeight); + $element.offset({ + top: 0, + left: $(document).width() - $element.width() + }); + guide = new Guide({ + element: $element, + html: 'Magna esse aliquet laborum et felis euismod' + }, $container, options); + + var coord = guide._verticalAlign(); + expect(coord.x1 < 0).toBe(false); + expect(coord.x1 > this._width).toBe(false); + expect(coord.y1 < 0).toBe(false); + expect(coord.y1 > this._distance).toBe(false); + expect(coord.dx1 < 0).toBe(false); + expect(coord.dx1 > this._width).toBe(false); + expect(coord.dy1 < 0).toBe(false); + expect(coord.dy1 > this._distance).toBe(false); + }); + + it('creates an svg with a curve that fits the container (right)', function() { + $element.width(20); + $element.height(window.innerHeight); + $element.offset({top: 0, left: 0}); + guide = new Guide({ + element: $element, + html: 'Magna esse aliquet laborum et felis euismod' + }, $container, options); + + var coord = guide._verticalAlign(); + expect(coord.x1 < 0).toBe(false); + expect(coord.x1 > this._width).toBe(false); + expect(coord.y1 < 0).toBe(false); + expect(coord.y1 > this._distance).toBe(false); + expect(coord.dx1 < 0).toBe(false); + expect(coord.dx1 > this._width).toBe(false); + expect(coord.dy1 < 0).toBe(false); + expect(coord.dy1 > this._distance).toBe(false); + }); + +}); \ No newline at end of file Index: reference/jquery-plugins/guided-tour-arrow/test/Guides.spec.js =================================================================== diff -u --- reference/jquery-plugins/guided-tour-arrow/test/Guides.spec.js (revision 0) +++ reference/jquery-plugins/guided-tour-arrow/test/Guides.spec.js (revision 10417a3908ef7516203be30712af4d355287973b) @@ -0,0 +1,114 @@ +var Guides = require('../src/modules/Guides'); + +describe("Guides class tests", function() { + + var $element = $('

Test

', {position: 'fixed'}).appendTo('body'), + guides; + + $element.width(window.innerWidth); + $element.height(20); + $element.offset({top: 0, left: 0}); + + beforeEach(function (done) { + guides = new Guides($element, { + guides: [{ + element: $element, + html: 'Welcome to Guides.js' + }, { + element: $element, + html: 'Navigate through guides.js website' + }, { + element: $element, + html: 'See how it works' + }, { + element: $element, + html: 'Download guides.js' + }, { + element: $element, + html: 'Check out how to get started with guides.js' + }, { + element: $element, + html: 'Read the docs' + }] + }); + done(); + }); + + afterEach(function (done) { + guides.destroy(); + done(); + }); + + it('only one element is created if start is called twice', function() { + guides.start().start(); + expect($('.guides-canvas').length).toBe(1); + }); + + it('does not throw an error if a method other than start is called before start', function() { + expect(guides.next).not.toThrow(Error); + expect(guides.prev).not.toThrow(Error); + expect(guides.end).not.toThrow(Error); + expect(guides.destroy).not.toThrow(Error); + }); + + it('sets the correct step when the start method is called', function() { + guides.start(); + expect(guides._current).toBe(0); + }); + + it('sets the correct step when the next method is called', function() { + guides.start().next(); + expect(guides._current).toBe(1); + }); + + it('sets the correct step when the prev method is called', function() { + guides.start().next().prev(); + expect(guides._current).toBe(0); + }); + + it('removes dom elements when the end method is called', function() { + guides.start().end(); + expect(guides.$canvas).toBe(null); + expect($('.guides-canvas').length).toBe(0); + }); + + it('sets the new options correctly when setOptions method is called', function() { + guides.setOptions({ + start: function () {} + }); + expect(typeof guides.options.guides).toBe('object'); + expect(typeof guides.options.start).toContain('function'); + }); + + it('calls event handlers', function() { + var test = 0; + guides.setOptions({ + start: function () { + test = 1; + } + }); + guides.start(); + expect(test).toBe(1); + }); + + it('uses guide color setting', function() { + guides.options.color = 'red'; + guides.options.guides[0].color = 'blue'; + guides.start(); + expect(guides._currentGuide._color).toBe('blue'); + }); + + it('falls back to global color setting', function() { + guides.setOptions({ + color: 'red' + }); + guides.start(); + expect(guides._currentGuide._color).toBe('red'); + }); + + it('removes dom elements when destroy method is called', function() { + guides.start().destroy(); + expect(guides.$canvas).toBe(null); + expect($('.guides-canvas').length).toBe(0); + }); +}); \ No newline at end of file Index: reference/jquery-plugins/guided-tour-arrow/test/format.spec.js =================================================================== diff -u --- reference/jquery-plugins/guided-tour-arrow/test/format.spec.js (revision 0) +++ reference/jquery-plugins/guided-tour-arrow/test/format.spec.js (revision 10417a3908ef7516203be30712af4d355287973b) @@ -0,0 +1,29 @@ +var format = require('../src/modules/format'); + +describe("format string function tests", function() { + + it("keeps the string the same if there are no placeholders", function() { + expect(format('ala bala', 'portokala')).toBe('ala bala'); + }); + + it("keeps the string the same if there are no placeholders and no arguments", function() { + expect(format('ala bala')).toBe('ala bala'); + }); + + it("keeps the string the same if there are no arguments", function() { + expect(format('ala {0} bala')).toBe('ala {0} bala'); + }); + + it("formats correcly {0} {1}", function() { + expect(format('{0} {1}', 'ala', 'bala')).toBe('ala bala'); + }); + + it("formats correcly {1} {0}", function() { + expect(format('{1} {0}', 'ala', 'bala')).toBe('bala ala'); + }); + + it("formats correcly {1} {1} {0}", function() { + expect(format('{1} {1} {0}', 'ala', 'bala')).toBe('bala bala ala'); + }); + +}); \ No newline at end of file