diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0a37f33 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +*.*.swp diff --git a/README.md b/README.md index ff123d2..789ad3f 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,16 @@ -Guiders.js (version 1.2.8) -========================== +Guiders.js (version 1.2.8) + WP-Guiders (not committed) +====================================================== +======= -Guiders are a user experience design pattern for introducing users to a web application. +Guiders are a user experience design pattern for introducing users to a web application. WP-Guiders is a WordPress plugin for integrating Guiders.js into the WordPress admin a la [WP-Pointers](http://wpeden.com/how-to-use-wp-pointer-tooltip-in-wordpress-3-3/) in WordPress 3.3 and later. Live Examples ------------- Here are a couple examples hosted online. You can also check out `README.html` for guiders in action! -[http://jeffpickhardt.com/guiders/](http://jeffpickhardt.com/guiders/) - -[https://optimizely.appspot.com/edit#url=www.google.com](https://optimizely.appspot.com/edit#url=www.google.com) +- [http://jeffpickhardt.com/guiders/](http://jeffpickhardt.com/guiders/) +- [https://optimizely.appspot.com/edit#url=www.google.com](https://optimizely.appspot.com/edit#url=www.google.com) Setup @@ -19,57 +19,67 @@ Setup Here is sample code for initializing a couple of guiders. Guiders are hidden when created, unless `.show()` is method chained immediately after `.createGuider`. ~~~ javascript -guiders.createGuider({ - buttons: [{name: "Next"}], - description: "Guiders are a user interface design pattern for introducing features of software. This dialog box, for example, is the first in a series of guiders that together make up a guide.", - id: "first", - next: "second", - overlay: true, - title: "Welcome to Guiders.js!" -}).show(); -/* .show() means that this guider will get shown immediately after creation. */ - -guiders.createGuider({ - attachTo: "#clock", - buttons: [{name: "Close, then click on the clock.", onclick: guiders.hideAll}], - description: "Custom event handlers can be used to hide and show guiders. This allows you to interactively show the user how to use your software by having them complete steps. To try it, click on the clock.", - id: "third", - next: "fourth", - position: 2, - title: "You can also advance guiders from custom event handlers.", - width: 450 -}); + + guiders.createGuider({ + buttons: [{name: "Next"}], + description: "Guiders are a user interface design pattern for introducing features of software. This dialog box, for example, is the first in a series of guiders that together make up a guide.", + id: "first", + next: "second", + overlay: true, + title: "Welcome to Guiders.js!" + }).show(); + /* .show() means that this guider will get shown immediately after creation. */ + + guiders.createGuider({ + attachTo: "#clock", + buttons: [{name: "Close, then click on the clock.", onclick: guiders.hideAll}], + description: "Custom event handlers can be used to hide and show guiders. This allows you to interactively show the user how to use your software by having them complete steps. To try it, click on the clock.", + id: "third", + next: "fourth", + position: 2, + title: "You can also advance guiders from custom event handlers.", + width: 450 + }); + ~~~~ +Note that if you can use `initGuider()` instead of `createGuider()`. The main difference is that `initGuider()` initializes a guider step without actually creating it. This is useful when you have steps where the guider being `attachTo`'d may ore may not be in the DOM yet. If you use `createGuider()` you would get an error like: `base is null [Break On This Error] var top = base top; + The parameters for creating guiders are: -~~~ -attachTo: (optional) selector of the html element you want to attach the guider to -autoFocus: (optional) if you want the browser to scroll to the position of the guider, set this to true -buttons: array of button objects - { - name: "Close", - classString: "primary-button", - onclick: callback function for when the button is clicked - (if name is "close", "next", or "prev", onclick defaults to guiders.hideAll, guiders.next, or guiders.prev respectively) - } -buttonCustomHTML: (optional) custom HTML that gets appended to the buttons div -classString: (optional) custom class name that the guider should additionally have -closeOnEscape: (optional) if true, the escape key will close the currently open guider -description: text description that shows up inside the guider -highlight: (optional) selector of the html element you want to highlight (will cause element to be above the overlay) -isHashable: (defaults to true) the guider will be shown auto-shown when a page is loaded with a url hash parameter #guider=guider_name -offset: fine tune the position of the guider, e.g. { left:0, top: -10 } -onClose: (optional) additional function to call if a guider is closed by the x button, close button, or escape key -onHide: (optional) additional function to call when the guider is hidden -onShow: (optional) additional function to call before the guider is shown -overlay: (optional) if true, an overlay will pop up between the guider and the rest of the page -position: (optional / required if using attachTo) clock position at which the guider should be attached to the html element. Can also use a description keyword (such as "topLeft" for 11 or "bottom" for 6) -title: title of the guider -width: (optional) custom width of the guider (it defaults to 400px) -xButton: (optional) if true, a X will appear in the top right corner of the guider, as another way to close the guider +- `attachTo`: (optional) selector of the html element you want to attach the guider to +- `autoAdvance` (optional): Array consisting of an element and event, that causes an auto-advance the guider when that event's element is triggered. This is a combination of `onShow()` binding of a `next()` plus a automatic removal of the bind when a `next()` happens. +- `autoFocus`: (optional) if you want the browser to scroll to the position of the guider, set this to true +- `bindAdvanceHandler` (optional): When using `autoAdvance` above, it will (by default) normally advance if the event occurs. But sometimes you want to change it so that it might advance only if the form has content, etc. If that is the case, set this to a closure so that this actually runs the auto-advance (or not). Note that commonly used handlers are stored in `guiders.handlers` array. If you want to create your own, realize the closure is bound to `_advanceHandler` for unbinding. +- `buttons`: array of button objects + +~~~~ javascript + + { + name: "Close", + classString: "primary-button", + onclick: callback function for when the button is clicked + (if name is "close" or "next", onclick defaults to guiders.hideAll and guiders.next respectively) + } + ~~~ +- `buttonCustomHTML`: (optional) custom HTML that gets appended to the buttons div +- `classString`: (optional) custom class name that the guider should additionally have to style different guiders differently based upon their classes +- `closeOnEscape`: (optional) if true, the escape key will close the currently open guider +- `description`: text description that shows up inside the guider +- `highlight`: (optional) selector of the html element you want to highlight (will cause element to be above the overlay) +- `isHashable`: (optional, default true) allows the use of hash in the query string to show the guider automatically when a page is loaded with a url hash parameter #gudier=guider_name (see below). +- `offset`: fine tune the position of the guider, e.g. `{ left:0, top: -10 }` +- `onClose`: (optional) additional function to call if a guider is closed by the x button, close button, or escape key +- `onHide`: (optional) additional function to call when the guider is hidden +- `onShow`: (optional) function that will be executed just before the guider is shown by `show()`. This function has a parameter which is the guider being shown. Note that if this function returns a guider, then it is assumed that you have shown() that and don't want to show the guider being onShow. For instance, you can have onShow test for something and return a `show()` of a different step. Then it shunts the current. +- `overlay`: (optional) if true, an overlay will pop up between the guider and the rest of the page. Note that you can give it a string value, which will inject that as a class name into the overlay. This is useful in conjunction with a css rule for coloring the background of an overlay red on `'error'` for error events and the like. +- `position`: (optional / required if using attachTo) clock position at which the guider should be attached to the html element. Can also use a description keyword (such as "topLeft" for 11 or "bottom" for 6) +- `shouldSkip`: (optional) a function handler that forces a skip of this step if the function returns true. +- `title`: title of the guider +- `width`: (optional) custom width of the guider (it defaults to `400px`) +- `xButton`: (optional) if true, a X will appear in the top right corner of the guider, as another way to close the guider Integration ----------- @@ -77,16 +87,30 @@ Integration Besides creating guiders, here is sample code you can use in your application to work with guiders: ~~~ javascript -guiders.hideAll(); // hides all guiders -guiders.next(); // hides the last shown guider, if shown, and advances to the next guider -guiders.show(id); // shows the guider, given the id used at creation -guiders.prev(); // shows the previous guider -~~~ -You'll likely want to change the default values, such as the width (set to 400px). These can be found at the top of `guiders.js` in the `_defaultSettings` object. You'll also want to modify the css file to match your application's branding. + guiders.hideAll(); // hides all guiders + guiders.endTour(); // like hideAll() but it remembers to remove the cookie also + guiders.next(); // hides the last shown guider, if shown, and advances to the next guider + guiders.prev(); // shows the previous guider + guiders.show(id); // shows the guider, given the id used at creation + guiders.resume(); //Start up the tour from the current place in the cookie (if set). This is useful when your tour leaves the page yoga re on. Unlike show() it will skip steps that need to be skipped. + +~~~ Creating a multi-page tour? If the URL of the current window is of the form `http://www.myurl.com/mypage.html#guider=foo`, then the guider with id equal to `foo` will be shown automatically. To use this, you can set the onHide of the last guider to an anonymous function: function() { window.location.href=`http://www.myurl.com/mypage.html#guider=foo`; } +Overrides +--------- + +There is the possibility you might want to change the default parameters or behavior of the Guiders themselves, instead of individual guides. + +Here are some default values you can override: + +- `_defaultSettings`: This is the default values of all guiders created using `guiders.createGuider()` For instance, you change the `width` to something other than `400px` to match your application's branding. Please check the `_defaultSettings` object at the top of the `guiders.js`. +- `cookie`: setting this allows you to name a cookie that gets updated every time `show()` is called. Note that doing this requires the [jQuery Cookies plugin](https://github.com/carhartl/jquery-cookie). +- `failStep`: guiders property allows you to name a step to `show()` if the `show()` case fails (for instance, if the attchTo element is missing). For obvious reasons, this (error) step should not have an `attachTo`. + +- `_buttonClass`: (optional, default 'guider_button') property allows you to change the default button "classname" for all guider buttons. For instance, for WP-Guiders, set this to "button-secondary". In Closing ---------- @@ -95,6 +119,7 @@ Guiders are a great way to improve the user experience of your web application. If you have questions about Guiders, you can email me (Jeff Pickhardt) at `jeff+pickhardt@optimizely.com`. Optimizely inquiries should be directed to `support@optimizely.com` or `sales@optimizely.com`. +If you have questions to the Guided Tours additions to guiders for WordPress (WP-Guiders) and Wikipedia gadget additions to guiders, email me at `tchay+guiders@wikimedia.org` License ------- diff --git a/guiders-1.2.8.css b/guiders-1.2.8.css index 1e2ceec..39828fc 100755 --- a/guiders-1.2.8.css +++ b/guiders-1.2.8.css @@ -43,10 +43,12 @@ } .x_button { - background-image: url('x_close_button.jpg'); cursor: pointer; height: 13px; width: 13px; + background-repeat: no-repeat; + background-image: url(data:image/jpeg;base64,/9j/4AAQSkZJRgABAgEASABIAAD/4QOzRXhpZgAATU0AKgAAAAgABwESAAMAAAABAAEAAAEaAAUAAAABAAAAYgEbAAUAAAABAAAAagEoAAMAAAABAAIAAAExAAIAAAAcAAAAcgEyAAIAAAAUAAAAjodpAAQAAAABAAAApAAAANAACvyAAAAnEAAK/IAAACcQQWRvYmUgUGhvdG9zaG9wIENTNCBXaW5kb3dzADIwMTA6MDk6MjQgMDg6MzY6NDEAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAADaADAAQAAAABAAAADQAAAAAAAAAGAQMAAwAAAAEABgAAARoABQAAAAEAAAEeARsABQAAAAEAAAEmASgAAwAAAAEAAgAAAgEABAAAAAEAAAEuAgIABAAAAAEAAAJ9AAAAAAAAAEgAAAABAAAASAAAAAH/2P/gABBKRklGAAECAABIAEgAAP/tAAxBZG9iZV9DTQAB/+4ADkFkb2JlAGSAAAAAAf/bAIQADAgICAkIDAkJDBELCgsRFQ8MDA8VGBMTFRMTGBEMDAwMDAwRDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAENCwsNDg0QDg4QFA4ODhQUDg4ODhQRDAwMDAwREQwMDAwMDBEMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwM/8AAEQgADQANAwEiAAIRAQMRAf/dAAQAAf/EAT8AAAEFAQEBAQEBAAAAAAAAAAMAAQIEBQYHCAkKCwEAAQUBAQEBAQEAAAAAAAAAAQACAwQFBgcICQoLEAABBAEDAgQCBQcGCAUDDDMBAAIRAwQhEjEFQVFhEyJxgTIGFJGhsUIjJBVSwWIzNHKC0UMHJZJT8OHxY3M1FqKygyZEk1RkRcKjdDYX0lXiZfKzhMPTdePzRieUpIW0lcTU5PSltcXV5fVWZnaGlqa2xtbm9jdHV2d3h5ent8fX5/cRAAICAQIEBAMEBQYHBwYFNQEAAhEDITESBEFRYXEiEwUygZEUobFCI8FS0fAzJGLhcoKSQ1MVY3M08SUGFqKygwcmNcLSRJNUoxdkRVU2dGXi8rOEw9N14/NGlKSFtJXE1OT0pbXF1eX1VmZ2hpamtsbW5vYnN0dXZ3eHl6e3x//aAAwDAQACEQMRAD8A74ehRj023172WNEODju36n3S76L0Q4p9RrdjfUNbnlm522Q5nt3bv3Hbd6jiueG17qqi70fabLHAbPz4b6Lmf8aoF7oafSb6PpOgeo/6G9n53o7/AE/7P8yip//Z/+0IRFBob3Rvc2hvcCAzLjAAOEJJTQQlAAAAAAAQAAAAAAAAAAAAAAAAAAAAADhCSU0D7QAAAAAAEABIAAAAAQABAEgAAAABAAE4QklNBCYAAAAAAA4AAAAAAAAAAAAAP4AAADhCSU0EDQAAAAAABAAAAHg4QklNBBkAAAAAAAQAAAAeOEJJTQPzAAAAAAAJAAAAAAAAAAABADhCSU0nEAAAAAAACgABAAAAAAAAAAI4QklNA/UAAAAAAEgAL2ZmAAEAbGZmAAYAAAAAAAEAL2ZmAAEAoZmaAAYAAAAAAAEAMgAAAAEAWgAAAAYAAAAAAAEANQAAAAEALQAAAAYAAAAAAAE4QklNA/gAAAAAAHAAAP////////////////////////////8D6AAAAAD/////////////////////////////A+gAAAAA/////////////////////////////wPoAAAAAP////////////////////////////8D6AAAOEJJTQQIAAAAAAAQAAAAAQAAAkAAAAJAAAAAADhCSU0EHgAAAAAABAAAAAA4QklNBBoAAAAAA0kAAAAGAAAAAAAAAAAAAAANAAAADQAAAAoAVQBuAHQAaQB0AGwAZQBkAC0AMQAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAADQAAAA0AAAAAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAQAAAAAAAG51bGwAAAACAAAABmJvdW5kc09iamMAAAABAAAAAAAAUmN0MQAAAAQAAAAAVG9wIGxvbmcAAAAAAAAAAExlZnRsb25nAAAAAAAAAABCdG9tbG9uZwAAAA0AAAAAUmdodGxvbmcAAAANAAAABnNsaWNlc1ZsTHMAAAABT2JqYwAAAAEAAAAAAAVzbGljZQAAABIAAAAHc2xpY2VJRGxvbmcAAAAAAAAAB2dyb3VwSURsb25nAAAAAAAAAAZvcmlnaW5lbnVtAAAADEVTbGljZU9yaWdpbgAAAA1hdXRvR2VuZXJhdGVkAAAAAFR5cGVlbnVtAAAACkVTbGljZVR5cGUAAAAA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bnMuYWRvYmUuY29tL3Bob3Rvc2hvcC8xLjAvIiB4bWxuczp0aWZmPSJodHRwOi8vbnMuYWRvYmUuY29tL3RpZmYvMS4wLyIgeG1sbnM6ZXhpZj0iaHR0cDovL25zLmFkb2JlLmNvbS9leGlmLzEuMC8iIHhtcDpDcmVhdG9yVG9vbD0iQWRvYmUgUGhvdG9zaG9wIENTNCBXaW5kb3dzIiB4bXA6Q3JlYXRlRGF0ZT0iMjAxMC0wOS0yNFQwODozNjo0MS0wNTowMCIgeG1wOk1ldGFkYXRhRGF0ZT0iMjAxMC0wOS0yNFQwODozNjo0MS0wNTowMCIgeG1wOk1vZGlmeURhdGU9IjIwMTAtMDktMjRUMDg6MzY6NDEtMDU6MDAiIGRjOmZvcm1hdD0iaW1hZ2UvanBlZyIgeG1wTU06SW5zdGFuY2VJRD0ieG1wLmlpZDoxQ0Q5QUNCNzQ4QzdERjExOUMyQkU4QkIzMTY5NzZDMCIgeG1wTU06RG9jdW1lbnRJRD0ieG1wLmRpZDoxQUQ5QUNCNzQ4QzdERjExOUMyQkU4QkIzMTY5NzZDMCIgeG1wTU06T3JpZ2luYWxEb2N1bWVudElEPSJ4bXAuZGlkOjFDRDlBQ0I3NDhDN0RGMTE5QzJCRThCQjMxNjk3NkMwIiBwaG90b3Nob3A6Q29sb3JNb2RlPSIzIiBwaG90b3Nob3A6SUNDUHJvZmlsZT0ic1JHQiBJRUM2MTk2Ni0yLjEiIHRpZmY6T3JpZW50YXRpb249IjEiIHRpZmY6WFJlc29sdXRpb249IjcyMDAwMC8xMDAwMCIgdGlmZjpZUmVzb2x1dGlvbj0iNzIwMDAwLzEwMDAwIiB0aWZmOlJlc29sdXRpb25Vbml0PSIyIiB0aWZmOk5hdGl2ZURpZ2VzdD0iMjU2LDI1NywyNTgsMjU5LDI2MiwyNzQsMjc3LDI4NCw1MzAsNTMxLDI4MiwyODMsMjk2LDMwMSwzMTgsMzE5LDUyOSw1MzIsMzA2LDI3MCwyNzEsMjcyLDMwNSwzMTUsMzM0MzI7NEZDNkYxNUZCODNCMjY3MjY4NzRCNjRFRTEzRkY2QjgiIGV4aWY6UGl4ZWxYRGltZW5zaW9uPSIxMyIgZXhpZjpQaXhlbFlEaW1lbnNpb249IjEzIiBleGlmOkNvbG9yU3BhY2U9IjEiIGV4aWY6TmF0aXZlRGlnZXN0PSIzNjg2NCw0MDk2MCw0MDk2MSwzNzEyMSwzNzEyMiw0MDk2Miw0MDk2MywzNzUxMCw0MDk2NCwzNjg2NywzNjg2OCwzMzQzNCwzMzQzNywzNDg1MCwzNDg1MiwzNDg1NSwzNDg1NiwzNzM3NywzNzM3OCwzNzM3OSwzNzM4MCwzNzM4MSwzNzM4MiwzNzM4MywzNzM4NCwzNzM4NSwzNzM4NiwzNzM5Niw0MTQ4Myw0MTQ4NCw0MTQ4Niw0MTQ4Nyw0MTQ4OCw0MTQ5Miw0MTQ5Myw0MTQ5NSw0MTcyOCw0MTcyOSw0MTczMCw0MTk4NSw0MTk4Niw0MTk4Nyw0MTk4OCw0MTk4OSw0MTk5MCw0MTk5MSw0MTk5Miw0MTk5Myw0MTk5NCw0MTk5NSw0MTk5Niw0MjAxNiwwLDIsNCw1LDYsNyw4LDksMTAsMTEsMTIsMTMsMTQsMTUsMTYsMTcsMTgsMjAsMjIsMjMsMjQsMjUsMjYsMjcsMjgsMzA7NkFFQjM0Q0IwNUE5MkY5RjlCMEU2RjQ1NTQxOUVCRkUiPiA8eG1wTU06SGlzdG9yeT4gPHJkZjpTZXE+IDxyZGY6bGkgc3RFdnQ6YWN0aW9uPSJjcmVhdGVkIiBzdEV2dDppbnN0YW5jZUlEPSJ4bXAuaWlkOjFDRDlBQ0I3NDhDN0RGMTE5QzJCRThCQjMxNjk3NkMwIiBzdEV2dDp3aGVuPSIyMDEwLTA5LTI0VDA4OjM2OjQxLTA1OjAwIiBzdEV2dDpzb2Z0d2FyZUFnZW50PSJBZG9iZSBQaG90b3Nob3AgQ1M0IFdpbmRvd3MiLz4gPC9yZGY6U2VxPiA8L3htcE1NOkhpc3Rvcnk+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4bXBtZXRhPiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg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); + *background-image: url('x_close_button.jpg'); } .guider_content p { @@ -133,4 +135,4 @@ .guider_highlight { position: relative; z-index: 101; -} \ No newline at end of file +} diff --git a/guiders-1.2.8.js b/guiders-1.2.8.js index a5f970b..4757dbb 100644 --- a/guiders-1.2.8.js +++ b/guiders-1.2.8.js @@ -16,6 +16,26 @@ * sales@optimizely.com or support@optimizely.com * * Enjoy! + * + * Changes: + * + * - cookie: guiders property allows you to name a cookie that gets updated every time show() is called. Requires jQuery Cookies plugin (https://github.com/carhartl/jquery-cookie) + * - failStep: guiders property allows you to name a step to show() if the show() case fails (attachTo element is missing). For obvious reasons, this should not have an attachTo + * - _buttonClass: property allows you to change the default button "classname" for all guider buttons (default: guider_button) + * + * - resume(): start up tour from current place in ookie (if set). This is useful when your tour leaves the page you are on. Unlike show, it will skip steps that need to be skipped. + * - endTour(): Like hideAll() but it remembers to remove the cookie position. + * - initGuider(): Allows for initializing Guiders without actually creating them (useful when guider is not in the DOM yet. Avoids error: base is null [Break On This Error] var top = base.top; + + * - autoAdvance: property allows binding to an element (and event) to auto-advance the guider. This is a combination of onShow() binding plus removing of bind when next is done. + * - shouldSkip: property defines a function handler forces a skip of this step if function returns true. + * - overlay "error": If not set to true, this defines the class of the overlay. (This is useful for coloring the background of the overlay red on error. + * - onShow: If this returns a guider object, then it can shunt (skip) the rest of show() + * + * @author tychay@php.net Patches for WordPress.com Guided Tour + * @todo Merge in this https://github.com/jeff-optimizely/Guiders-JS/pull/33 and modify so it so it checks either visibility or DOM + * @todo: add pulsing jquery.pulse https://github.com/jamespadolsey/jQuery-Plugins/tree/master/pulse/ + * @see https://github.com/tychay/Guiders-JS */ var guiders = (function($) { @@ -25,7 +45,24 @@ var guiders = (function($) { guiders._defaultSettings = { attachTo: null, // Selector of the element to attach to. - autoFocus: false, // Determines whether or not the browser scrolls to the element. + autoAdvance: null, //replace with array of selector, event to bind to cause auto-advance + autoFocus: false, // Determines whether or not the browser scrolls to the element." + bindAdvanceHandler: function(this_obj) { //see guiders.handlers below for other common options + if (!this_obj.autoAdvance) { return; } + this_obj._advanceHandler = function() { + $(this_obj.autoAdvance[0]).unbind(this_obj.autoAdvance[1], this_obj._advanceHandler); //unbind event before next + switch (this_obj.autoAdvance[1]) { + case 'hover': //delay hover so the guider has time to get into position (in the case of flyout menus, etc) + guiders.hideAll(); //hide immediately + setTimeout(function() { guiders.next(); }, 1000); //1 second delay + break; + case 'blur': + // fall through... + default: + guiders.next(); + } + }; + }, buttons: [{name: "Close"}], buttonCustomHTML: "", classString: null, @@ -41,12 +78,63 @@ var guiders = (function($) { onHide: null, onShow: null, overlay: false, - position: 0, // 1-12 follows an analog clock, 0 means centered. + position: 0, // 1-12 follows an analog clock, 0 means centered + shouldSkip: null, //function handler that allows you to skip this function if returns true. title: "Sample title goes here", width: 400, - xButton: false // This places a closer "x" button in the top right of the guider. + xButton: false, // this places a closer "x" button in the top right of the guider + _advanceHandler: null //action to do on advance. Set by bindAdvanceHandler closure done on show() }; + // Begin additional functionality + guiders.cookie = ""; //set this if you want to write the step to a cookie each show() + guiders.failStep = ""; + /** + * Various common utility handlers you can bind as advance handlers to your + * guider configurations + */ + guiders.handlers = { + /** + * Auto-advance if the element is missing + */ + advance_if_not_exists: function() { + return guiders._defaultSettings._bindAdvanceHandler; + }, + /** + * Advance if test_function() returns true + */ + advance_if_test: function(test_function) { + return function(this_obj) { + var bind_obj = $(this_obj.autoAdvance[0]); + this_obj._advanceHandler = function() { + if (!test_function()) { return; } //don't advance if test_function is false + bind_obj.unbind(this_obj.autoAdvance[1], this_obj._advanceHandler); //unbind event before next + guiders.next(); + }; + } + }, + /** + * Advance if the form element has content + */ + advance_if_form_content: function(this_obj) { + var bind_obj = $(this_obj.autoAdvance[0]); + this_obj._advanceHandler = function() { + if ($(this_obj.autoAdvance[0]).val() == '') { return; } //don't advance if you haven't added content + bind_obj.unbind(this_obj.autoAdvance[1], this_obj._advanceHandler); //unbind event before next + guiders.next(); + }; + }, + /** + * Skip if form element has content + * + * this context will be inside the actual guider step, not here + */ + skip_if_form_content: function() { //skip if form element has content + return ($(this.autoAdvance[0]).val() !== '') + } + }; + // end additional functionality + guiders._htmlSkeleton = [ "
", "
", @@ -65,9 +153,11 @@ var guiders = (function($) { guiders._backButtonTitle = "Back"; guiders._buttonElement = ""; guiders._buttonAttributes = {"href": "javascript:void(0);"}; + guiders._buttonClass = "guider_button"; //make this "button-secondary" for wordpress guiders._closeButtonTitle = "Close"; guiders._currentGuiderID = null; - guiders._guiders = {}; + guiders._guiderInits = {}; //stores uncreated guiders indexed by id + guiders._guiders = {}; //stores created guiders indexed by id guiders._lastCreatedGuiderID = null; guiders._nextButtonTitle = "Next"; guiders._offsetNameMapping = { @@ -87,6 +177,7 @@ var guiders = (function($) { guiders._windowHeight = 0; guiders._addButtons = function(myGuider) { + // Add buttons var guiderButtonsContainer = myGuider.elem.find(".guider_buttons"); if (myGuider.buttons === null || myGuider.buttons.length === 0) { @@ -97,7 +188,7 @@ var guiders = (function($) { for (var i = myGuider.buttons.length - 1; i >= 0; i--) { var thisButton = myGuider.buttons[i]; var thisButtonElem = $(guiders._buttonElement, - $.extend({"class" : "guider_button", "html" : thisButton.name }, guiders._buttonAttributes, thisButton.html || {}) + $.extend({"class" : guiders._buttonClass, "html" : thisButton.name }, guiders._buttonAttributes, thisButton.html || {}) ); if (typeof thisButton.classString !== "undefined" && thisButton.classString !== null) { @@ -107,6 +198,7 @@ var guiders = (function($) { guiderButtonsContainer.append(thisButtonElem); var thisButtonName = thisButton.name.toLowerCase(); + guiders._buttonClass = "guider_button"; //make this "button-secondary" for wordpress if (thisButton.onclick) { thisButtonElem.bind("click", thisButton.onclick); } else { @@ -255,18 +347,37 @@ var guiders = (function($) { }); }; + /** + * Returns the guider by ID. + * + * Add check to create and grab guider from inits if it exists there. + */ guiders._guiderById = function(id) { if (typeof guiders._guiders[id] === "undefined") { - throw "Cannot find guider with id " + id; + if (typeof guiders._guiderInits[id] == "undefined") { + throw "Cannot find guider with id " + id; + } + var myGuider = guiders._guiderInits[id]; + // this can happen when resume() hits a snag somewhere + if (myGuider.attachTo && guiders.failStep && ($(myGuider.attachTo).length == 0)) { + throw "Guider attachment not found with id " + myGuider.attachTo; + } + guiders.createGuider(myGuider); + delete guiders._guiderInits[id]; //prevents recursion + // fall through ... } return guiders._guiders[id]; }; - guiders._showOverlay = function() { + guiders._showOverlay = function(overlayClass) { $("#guider_overlay").fadeIn("fast", function(){ if (this.style.removeAttribute) { this.style.removeAttribute("filter"); } + }).each( function() { + if (overlayClass) { + $(this).addClass(overlayClass); + } }); // This callback is needed to fix an IE opacity bug. // See also: @@ -282,7 +393,7 @@ var guiders = (function($) { }; guiders._hideOverlay = function() { - $("#guider_overlay").fadeOut("fast"); + $("#guider_overlay").fadeOut("fast").removeClass(); }; guiders._initializeOverlay = function() { @@ -332,6 +443,8 @@ var guiders = (function($) { }; var position = positionMap[myGuider.position]; myGuiderArrow.css(position[0], position[1] + "px"); + // TODO: experiment with pulsing + //myGuiderArrow.css(position[0], position[1] + "px").stop().pulse({backgroundPosition:["7px 0","0 0"],right:["-35px","-42px"]}, {times: 10, duration: 'slow'}); }; /** @@ -362,15 +475,30 @@ var guiders = (function($) { }; guiders.next = function() { - var currentGuider = guiders._guiders[guiders._currentGuiderID]; - if (typeof currentGuider === "undefined") { + //var currentGuider = guiders._guiders[guiders._currentGuiderID]; + try { + var currentGuider = guiders._guiderById(guiders._currentGuiderID); //has check to make sure guider is initialized + } catch (err) { + //console.log(err); return; } currentGuider.elem.data('locked', true); + //remove current auto-advance handler bound before advancing + if (currentGuider.autoAdvance) { + $(currentGuider.autoAdvance[0]).unbind(currentGuider.autoAdvance[1], currentGuider._advanceHandler); + } var nextGuiderId = currentGuider.next || null; if (nextGuiderId !== null && nextGuiderId !== "") { var myGuider = guiders._guiderById(nextGuiderId); + // If skip function is bound, check to see if we should advance the guider + if (myGuider.shouldSkip) { + if ( myGuider.shouldSkip() ) { + guiders._currentGuiderID = myGuider.id; + guiders.next(); + return; + } + } var omitHidingOverlay = myGuider.overlay ? true : false; guiders.hideAll(omitHidingOverlay, true); if (currentGuider && currentGuider.highlight) { @@ -407,6 +535,27 @@ var guiders = (function($) { } }; + /** + * This stores the guider but does no work on it. + * + * The main problem with createGuider() is that it needs _attach() to work. If + * you try to _attachTo something that doesn't exist yet, the guider will + * suffer a fatal javscript error and never initialize. + * + * A secondary problem is createGuider() code is expensive on the CPU/time. + * This prevents more than one guider from being created at a time (it defers + * creation to a user-is-idle time. + */ + guiders.initGuider = function(passedSettings) { + if (passedSettings === null || passedSettings === undefined) { + return; + } + if (!passedSettings.id) { + return; + } + this._guiderInits[passedSettings.id] = passedSettings; + }; + guiders.createGuider = function(passedSettings) { if (passedSettings === null || passedSettings === undefined) { passedSettings = {}; @@ -485,14 +634,65 @@ var guiders = (function($) { return guiders; }; + /** + * Like hideAll() but remembers to delete the cookie if set + */ + guiders.endTour = function(omitHidingOverlay) { + if (guiders.cookie) { + $.cookie(guiders.cookie, null); + } + guiders.hideAll(omitHidingOverlay); + }; + + /** + * Like show() but it will use a cookie if id is not specified and skips + * steps if necessary + */ + guiders.resume = function(id) { + // if cookie specified and no id passed in, resume from cookie + if (!id && guiders.cookie) { + id = $.cookie(guiders.cookie); + } + //if no id or cookie, don't resume (they can call show themselves) + if ( !id ) { + return false; + } + try { + var myGuider = guiders._guiderById(id); + } catch (err) { + if ( guiders.failStep ) { + guiders.show(guiders.failStep); + return true; + } else { + return false; + } + } + + //skip if should skip + if (myGuider.shouldSkip) { + if ( myGuider.shouldSkip() ) { + guiders._currentGuiderID = myGuider.id; + guiders.next(); + return true; + } + } + guiders.show(); + return true; + }; + guiders.show = function(id) { if (!id && guiders._lastCreatedGuiderID) { id = guiders._lastCreatedGuiderID; } - var myGuider = guiders._guiderById(id); + try { + var myGuider = guiders._guiderById(id); + } catch (err) { + //console.log(err); + return; + } if (myGuider.overlay) { - guiders._showOverlay(); + guiders._showOverlay(myGuider.overlay); // if guider is attached to an element, make sure it's visible if (myGuider.highlight) { guiders._highlightElement(myGuider.highlight); @@ -510,6 +710,25 @@ var guiders = (function($) { myGuider.onShow(myGuider); } guiders._attach(myGuider); + + //If necessary, save the guider id to a cookie + if (guiders.cookie) { + $.cookie(guiders.cookie, id); + } + //handle binding of auto-advance action + if (myGuider.autoAdvance) { + myGuider.bindAdvanceHandler(myGuider); + $(myGuider.autoAdvance[0]).bind(myGuider.autoAdvance[1], myGuider._advanceHandler); + } + // You can use an onShow function to take some action before the guider is shown. + if (myGuider.onShow) { + // if onShow returns something, assume this means you want to bypass the rest of onShow. + var show_return = myGuider.onShow(myGuider); + if (show_return) { + return show_return; + } + } + myGuider.elem.fadeIn("fast").data("locked", false); guiders._currentGuiderID = id; @@ -530,6 +749,20 @@ var guiders = (function($) { $(myGuider.elem).trigger("guiders.show"); + // Create (preload) next guider if it hasn't been created + var nextGuiderId = guiders.next || null; + var nextGuiderData; + if (nextGuiderId !== null && nextGuiderId !== "") { + if (nextGuiderData = guiders._guiderInits[nextGuiderId]) { + //don't attach if it doesn't exist in DOM + var testInDom = $(nextGuiderData.attachTo); + if ( testInDom.length > 0 ) { + guiders.createGuider(guiders.nextGuiderData); + delete nextGuiderData; + } + } + } + return guiders; }; diff --git a/wp-guiders.css b/wp-guiders.css new file mode 100755 index 0000000..4eedbab --- /dev/null +++ b/wp-guiders.css @@ -0,0 +1,232 @@ +/** + * WordPress Guided Tour, now with design inspiration from WP 3.3 pointers + */ + +.guider { + padding: 0 0 10px; + position: relative; + font-size: 13px; + background: #fff; + border-style: solid; + border-width: 1px; + border-color: #dfdfdf; + border-color: rgba(0,0,0,.125); + -webkit-border-radius: 3px; + border-radius: 3px; + -webkit-box-shadow: 0 2px 4px rgba(0,0,0,.19); + -moz-box-shadow: 0 2px 4px rgba(0,0,0,.19); + box-shadow: 0 2px 4px rgba(0,0,0,.19); + position: absolute; + outline: none; + z-index: 100000005 !important; + width: 500px; +} + +.guider_buttons { + margin: 0; + padding: 5px 15px; + overflow: auto; +} + +.guider_buttons a { + float: right; + display: inline-block; + text-decoration: none; + position: relative; + margin-left: 10px; +} + +.button-secondary { + line-height: 1.2em !important; +} + +.guider_buttons a.plain { + padding-left: 3px; + color: #21759b; + border: 0 !important; + background: 0 !important; + padding-right: 0 !important; + text-shadow: 0 !important; +} + +.guider_buttons a.plain:hover { + color: #d65227; +} + +.guider_buttons a.plain::before { + content: ' '; + width: 10px; + height: 100%; + position: absolute; + left: -10px; + background: url('../../../wp-includes/images/xit.gif') 0 15% no-repeat; +} + +.guider_buttons a.plain:hover::before { + background-position-x: -10px; +} + +.guider_content { + position: relative; + font-size: 13px; +} + +.guider_content h1 { + position: relative; + margin: 0 0 5px; + padding: 15px 18px 14px 60px; + line-height: 1.4em; + font-size: 14px; + color: #fff; + border-radius: 3px 3px 0 0; + text-shadow: 0 -1px 0 rgba(0,0,0,0.3); + background-color: #8cc1e9; + background-image: -webkit-linear-gradient(bottom,#72a7cf 0,#8cc1e9 100%); + background-image: -moz-linear-gradient(bottom,#72a7cf 0,#8cc1e9 100%); + background-image: -ms-linear-gradient(bottom,#72a7cf 0,#8cc1e9 100%); + background-image: -o-linear-gradient(bottom,#72a7cf 0,#8cc1e9 100%); + background-image: linear-gradient(bottom,#72a7cf 0,#8cc1e9 100%); +} +.guider_content h1::before { + position: absolute; + top: 0; + left: 15px; + content: ' '; + width: 36px; + height: 100%; + background: url('../../../wp-includes/images/icon-pointer-flag.png') 0 50% no-repeat; +} + +.guider_close { + float: right; + padding: 10px 0 0; +} + +.x_button { + background-image: url('x_close_button.jpg'); + cursor: pointer; + height: 13px; + width: 13px; +} + +.guider_content p { + clear: both; + color: #333; + padding: 0 15px; +} + +#guider_overlay { + background-color: #fff; + width: 100%; + height: 100%; + position: fixed; + top: 0px; + left: 0px; + opacity: 0.4; + -ms-filter: "progid:DXImageTransform.Microsoft.Alpha(Opacity=40)"; + filter: alpha(opacity=40); + z-index: 50; +} + +#guider_overlay[class=error] { + background-color: #000; +} + +.guider_arrow { + top: 50%; + margin-top: -15px; + width: 14px; + height: 30px; + position: absolute; + display: none; + z-index: 10; + z-index: 100000006 !important; + background: url('../../../wp-includes/images/arrow-pointer-blue.png') 0 0 no-repeat; +} + +.guider_arrow_left, .guider_arrow_right, .guider_arrow_up, .guider_arrow_down { + display: block; +} + +.guider_arrow_left { + left: 0; + background-position: 0 -15px; + left: -14px; + margin-top: 7px; +} + +.guider_arrow_up { + background-position: 0 0; + top: 1px; + width: 30px; + height: 14px; +} + +/* possibly an ugly hack to push the arrow to the right side on the exit tour dialog */ +#gt-hide .guider_arrow_up { + left: 355px !important; +} + +.guider_arrow_down { + background-position:0 -46px; + top: auto !important; + bottom: -30px !important; + width: 30px; +} + +.guider_arrow_right { + background-position:-16px -15px; + right: -14px; + margin-top: 7px; +} + + + + + + + +/* +old guider arrows +.guider_arrow { + width: 42px; + height: 42px; + position: absolute; + display: none; + background-repeat: no-repeat; + z-index: 100000006 !important; + + background-image: url(data:image/png;base64,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); + *background-image: url('guider_arrows.png'); +} + +.guider_arrow_right { + display: block; + background-position: 0px 0px; + right: -42px; +} +.guider_arrow_down { + display: block; + background-position: 0px -42px; + bottom: -42px; +} +.guider_arrow_up { + display: block; + background-position: 0px -126px; + top: -42px; +} +.guider_arrow_left { + display: block; + background-position: 0px -84px; + left: -42px; +} + +*/ + + + + + + + +