diff --git a/README.md b/README.md index 6dad1ac..5fefaf3 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # guide.js -guide.js is a jQuery plugin that creates a clickable walkthrough of elements on your webpage +guide.js is a jQuery plugin that creates a clickable walkthrough of elements on your webpage. ## Installing @@ -19,52 +19,117 @@ Download [guide.js][0] and [guide.css][1] and add the following assets: ## Using -In you document ready, first attach the guide to the parent element you'd like to mask: +In your document ready, first create an instance of an overlay, and initialize it while passing in an element that encompasses all the nodes for this overlay. Typically, you'll just use `$('body')`. + +```javascript +var helpOverlay = $('body').guide(); +``` + +Then attach an event handler (or any method you desire) to start the overlay. + +```javascript +$('#my-button').on('click', function() { + helpOverlay.start(); +}); +``` + +guide.js will stop if you click on the darkened background. However, if you would like to add another method to close the overlay, such as a timer, you can do the following: + +```javascript +setTimeout(function() { + helpOverlay.end(); +}, 30000); // wait 30 seconds +``` + +### Options + +#### Blurb + +In order to add new steps to your overlay, add the `data-g-blurb` attribute to any element on your page. ```HTML -var guide = $("body").guide(); +
Hello, World!
``` -Then attach the steps to the elements to highlight, using jquery selectors: +#### Order + +Your blurb nodes will, by default, order by their position in your HTML structure. Nodes closer to the initial `` tag will show before nodes closer to your closing `` tag. If you would like to override this ordering, use the `data-g-order` option. ```HTML -guide.addStep("#hello", "This step says hello"); -guide.addStep("#world", "This step says world"); +
Hello, World!
``` -Then initiate the guide, manually or via a trigger event +You can order from 0 to any value you desire. + +By default, ordered elements will show before any un-ordered elements, despite what the actual order number is. The un-ordered elements will then appear in the order they appear in the HTML structure. If you accidentally give two nodes the same ordering, guide.js will order them in the order they appear in the HTML, while still maintaining their order among other ordered nodes. + +#### Direction + +guide.js also allows you to define which side of your element you'd like the bubble to appear on. Use the `data-g-direction` option. ```HTML -guide.start(); +
Hello, World!
``` +Your options for direction are 'top', 'bottom', 'left', and 'right'. The default is 'bottom'. -## Methods +#### Margin -### .guide([options]) +You can also specify the margin in which you'd like the bubble to assume around the element. Use the `data-g-margin` option for this. -Attach the guide to the selector +```HTML +
Hello, World!
+``` + +The above will result in a margin of 100 pixels. The default is 10 pixels. Note that the margin is the edge of the bubble, the margin does not account for the size of the comment arrow, which is the reason for the 10 pixel default. + +#### Multiple occurrences of same blurb + +You may find that there is a time you want to have two or more blurbs on the same page with the exact same text. Take a peek at the 'Nifty little ditties' section to see what we're doing to prevent accidental multiples. If you do want multiples however, you may use the `data-g-multiple` option on your element. + +```HTML +
My blurb will show!
+
So will mine!
+``` + +There are no options for `data-g-multiple`. Simply having the attribute present is enough. -**Parameters:** - - options : Object (optional) - Control the gap between the highlighted element and the mask with `margin` +## Nifty little ditties -### guide.addStep(selector, introduction, options) +guide.js loves you, and wants your dev cycle to be as quick and painless as possible. With that in mind, we've added a few nifty features that make guide.js as flexible as we had the foresight to see (let us know how we can help otherwise). -Add a step to the guide +#### Fixed elements -**Parameters:** - - selector : jQuery selector identifying the DOM element to highlight - - introduction : The string to display - - options : Object with optional settings for `margin` and `callback` +You may have experienced with other help overlays that once the bubble is set relative to the page, it's set. This is okay, except when the element you are wrapping is fixed on the page. When you begin to scroll, the overlay scrolls with the page, and your fixed element is left underneath the dark overlay. guide.js resolves this by performing a check on all nodes to determine if they are fixed on the page. If they are, the overlay will reflect that, and you can scroll your little hearts out. -### guide.start() +#### Front end PHP/Ruby, etc. -Start the guide... +We know that our users are skilled in the way of dev-fu, and that means that you'll be using guide.js with pages that aren't static. One problem that may arise is something like this: -## Roadmap +```php +$foods = array("pizza","sandwiches","ice cream","cake"); +foreach ($foods as $item) +{ + echo "
I enjoy $item.
"; +} +``` + +What would happen here is you would have four nodes that show in your tutorial cycle. All of them point to a food div, and give you the same story: 'Here is an example of a div with text in it.' Likely, you would rather only have the first one included in the tutorial, and guide.js gives you this ability. As guide.js loops your wrapper element searching for `data-g-blurb`, it keeps track of what blurbs you've been using. After adding a blurb to the first element in this list, it will note that you have added a blurb with the content 'Here is an example of a div with text in it.' On the next go-round, it will see that you are adding another blurb with the same text, and it will go to the second check: the `data-g-multiple` option. If the option is set on this element, it will include the blurb. If it is not, it will skip the blurb entirely. Note that the identical blurbs do not have to be right next to each other in the HTML as in our above example. They just have to be within the same overlay wrapper element. + +## End notes + +#### Created by +[Dozyatom][2] + +##### Contributors +[ethanwelborn][3] + +#### Roadmap - Abstract CSS (currently based on Bootstrap) - Remove jQuery dependency - Add keypress support + [0]: https://github.com/Dozyatom/guide.js/blob/master/guide.js - [1]: https://github.com/Dozyatom/guide.js/blob/master/guide.css \ No newline at end of file + [1]: https://github.com/Dozyatom/guide.js/blob/master/guide.css + [2]: https://github.com/Dozyatom + [3]: https://github.com/ethanwelborn diff --git a/example.html b/example.html index 3b2d0d8..e7209e0 100644 --- a/example.html +++ b/example.html @@ -1,24 +1,43 @@ - - - - - - -
Hello
-
World
- + + + -$(function() { - - var guide = $("body").guide(); + - guide.addStep("#hello", "This step says hello"); - guide.addStep("#world", "This step says world"); - - guide.start(); - -}); - - + +
Hello,
+ +
World!
+ +
I will show first. And I will not be skipped even though I have the same blurb as 'World!'
+ + \ No newline at end of file diff --git a/guide.css b/guide.css index 28920f5..8016805 100644 --- a/guide.css +++ b/guide.css @@ -4,7 +4,8 @@ width: 100%; left: 0px; top: 0px; - opacity: 0; + display:none; + opacity:0.5; } .guideBubble { position: absolute; @@ -36,14 +37,14 @@ content:''; position: absolute; } -.guideBubble-arrow.top { +.guideBubble-arrow.bottom { top: -10px; border-top-color:transparent; border-right-color:transparent; border-bottom-color:white; border-left-color:transparent; } -.guideBubble-arrow.right { +.guideBubble-arrow.left { right: -10px; top: 10px; border-top-color:transparent; @@ -51,18 +52,21 @@ border-bottom-color:transparent; border-left-color:white; } -.guideBubble-arrow.bottom { +.guideBubble-arrow.top { bottom: -10px; border-top-color:white; border-right-color:transparent; border-bottom-color:transparent; border-left-color:transparent; } -.guideBubble-arrow.left { +.guideBubble-arrow.right { left: -10px; top: 10px; border-top-color:transparent; border-right-color:white; border-bottom-color:transparent; border-left-color:transparent; +} +.guideBubble .btn-danger { + background-image: none; } \ No newline at end of file diff --git a/guide.js b/guide.js index 06f2fee..088e263 100644 --- a/guide.js +++ b/guide.js @@ -3,20 +3,84 @@ var guide = function() { var container, defaults = { - margin: 10 + margin: 10, + direction: 'bottom' }, topMask = $("
").addClass("guideMask"), bottomMask = $("
").addClass("guideMask"), leftMask = $("
").addClass("guideMask"), rightMask = $("
").addClass("guideMask"), bubble = $("
").addClass("guideBubble"), - holdingSteps, - steps, - position, + holdingSteps = [], + steps = [], + position = -1, + blurbs = [], + queued = [], + nonqueued = [], + blurb = '', + count = 0, + zIndex = 1000000, prevButton = $("