Guiders to work across page loads (and other changes) #77

wants to merge 14 commits into


None yet
2 participants

tychay commented Nov 30, 2012

This is some stuff that I wrote a year ago that WordPress used for Guided Tours on The main change was some extra functionality to allow the tour to work across multiple differing pages which necessitated some changes like

  • a cookie to allow guiders to be continued even if a UX element were clicked
  • a way to auto-advance the guider when an event occurs instead of the guider being clicked
  • a way for a tour to be loaded without error, even if the UX element a guide can be attached to doesn't exist yet/in that page
    … etc.

These do not break/change existing functionality in Guiders.js (as of August 2012)

That went live on WordPress back in 2010, but I was also planning on making this available as a plugin for installations which I never finished.

Wikipedia plans on using doing a Guided Tour as part of Onboarding experimentation and in the process, Guiders might get modified a lot--plus it would make sense to have a way to upstream those changes.

I updated Guiders a couple months ago to track your changes in the last year and a half, so the js files, at least, should merge cleanly.

Note that there is some stuff related to the plugin I never finished (things like wp-guiders.css and some notes in the README) if you merge the pull, feel free to delete them. If I ever redo guiders for WordPress, I'll just do it via Git submodule :-)

Take care,


tychay added some commits Jan 6, 2012

Upgraded from 1.2.0 to 1.1.5
Fork from github and push back to github

Changes to Guided Tour for
- cookie: guiders property allows you to name a cookie that gets
updated every time show() is called. Requires jQuery Cookies plugin
- 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
- resume(): start up tour from current place in cookie (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
 - 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 =;
- 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: 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
with a class="error")
Tested and merged with
Syntax errors in in merge fixed
Fixed small class name errors on secondary buttons.
Added css file for guiders to match WordPress 3.3 pointers
Updated readme file with new functionality
Functionality added for the WordPress version of guiders.js
Small typos in GitHub's markdown
Apparently they do not support multimarkdown syntax.
More correct and complete documentation
- added undocumented handlers from original guiders.js code
- alphabetically sorted names
- moved defaults around so that it is in line with documentation and
coding conventions
- renamed advanceHandler to _advanceHandler to prevent accidental
default button class override
wordpress uses a different classname for all buttons
Merge remote-tracking branch 'upstream/master'
Merge tour stuff into 1.2.8
- defaultButtonClass is now _buttonClass to be more consistent with others
- merge is untested
Bug in merge
error in the _buttonClass switch
- encode the x box
- documentation fix
- removed obsolute guiders-1.2.0.js

Hi Terry,

I updated guiders.js to 1.2.9 with some changes motivated by your patch. For example:

  • a way for a tour to be loaded without error, even if the UX element a guide can be attached to doesn't exist yet/in that page … etc.

I addressed this in the new version. The guiders are still all added to the DOM upon initialization, which as you rightly point out could slow down the page, but the fix I added is more forgiving and user friendly than the "initGuider" method.

  • a cookie to allow guiders to be continued even if a UX element were clicked

Agreed, this is something that has been asked for before. It adds a dependency on $.cookie which is why I didn't add it. Also, different companies like to maintain state in different ways. For example, at Optimizely, a user is shown the guided tour once upon sign in and then never again, with that state info kept in server-side in the database.

I see that you guys are planning to use guided tours... looks cool.

tychay commented Dec 11, 2012

Thanks for taking a look over. I'll merge the patches back into our branch and clean up stuff so that we can track the changes to guiders somewhere between Wikimedia Foundation gerrit instance using the way we're supposed to be doing it in gerrit.

I'll consider moving the cookie support into the files that are outside of guiders.js.

BTW, the WMF maintains a pretty strict policy with regard to coding conventions due to our main engineer is a jQuery core developer, so there's probably a big "assorted cruft cleanup" patch that I'll do with another pull request.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment