Drupal 8 comes with a new guided help API in the form of the Tour module.
Here at PreviousNext we were instrumental in getting this module in prior to feature freeze and are excited by the possibilities it presents to ease the learning curve for new Drupal site-builders.
In this post we discuss how the module came about, how we went about building support for the idea and the way the API works.
In part two we will go on to show some examples of how you can add tour module support to your modules and talk about some of the advanced features of the API.
What is Tour module?
Tour module provides a context-sensitive guided tour of the main parts of a given Drupal user interface. It is powered by the jQuery Joyride plugin and allows site builders and module-developers the ability to provide focussed help to target elements on the page. If all of that sounds a bit wordy, here's a screencast of it in action.
Getting Tour module in core - the process saga.
So how did this end up in core? Well we put a lot of work into it so we thought it would be great to share the story of how big changes like this are introduced to Drupal.
Back in the 2011, Nick Schuch and I were discussing the University of Minnesota Drupal usability testing trials that we'd both got up early in the morning to tune in to. We floated a few ideas including a slideshow during the installer hilighting the cool things you could build with Drupal, inspired by what some of the major Linux GUI installers were doing at the time. But it remained just that, two developers bandying about ideas in the office.
Fast forward to October 2012 and we happened to notice Cameron Eagans post an issue in the core queue to Write tour.module and add it to core. This struck a chord with us, and a few others too - and in the space of about four hours Devin Carlson had up a patch showing how it could be done. After an intial flurry of activity things went quiet for a while. Work got busy and we didn't get to look at it.
The road to work
In late December 2012 the Joyride plugin was brought up in some internal communications at PreviousNext and we remembered the issue about adding it to core. Nick and I both work remotely, based out of shared office in Central Queensland and we got to talking that in the new-year we'd try and set aside some time to pick up the issue again. We discussed how to re-architect it so it was backed with a solid API so other modules could extend it and hopefully increase its chances of being core-worthy. But then the Australian climate got in the way and Nick's route to the office became more of a waterway.
So late in January, Nick took off like a rocket and started re-working the tour code to use some of Drupal 8's new features like config entities, plugins and put the tour button in the toolbar using hook_toolbar() to dovetail with the work being done by the Spark team on the Edit module.
Inside a day, Nick had a decent working concept based on config entities, meaning modules would only need some yml files in their config folder to define UI tours.
But this was the end of January and feature freeze was in just over two weeks. Were we insane? So we spoke with Angela Byron in IRC to discuss our plans and our chances. Angela remarked that it sounded like Drupal 9 material. But undeterred, Nick boldy declared he'd do whatever it took to make it happen in time for Drupal 8.
Shortly after Nick posted his latest screencast the issue thread began to light up again.
Then we went to Drupalcon Sydney and started accosting people in hallways. We approached Angela Byron to show tour in action on Views UI. We started demoing to other Australian Drupal contributors to get their support. Then we hijacked Dries as he was about to get into the lift. We took him through the demo as the lift rose and when he got out on his floor - he asked us was there an issue with a patch before the feature completion phase, thanks to Devin and Cameron - there was. Dries had to take a call so asked if we could email him the issue number. To be honest at the time we weren't sure if he liked it or not. Later he revealed in the issue queue that he did but he played it very cool after that lift ride. To be honest, I don't blame him - we hadn't met Dries before and whilst what we were demoing might have looked nice, the back-end API could have been a load of rubbish.
For us, Feature Freeze came on a Tuesday in our timezone, so Monday morning our time we had a few nitpick cleanups but shortly after lunch on Monday we finally got to Reviewed and tested by the community with a list of follow up tasks to be completed post feature freeze.
What this story come saga highlights is how an idea moves to a fully-fledged feature in the Drupal community. Many sets of eyes review a patch, each experts in their own respective fields. The net product is far more robust than something any one individual could produce. It is this level of collaboration that makes Drupal what it is today.
So that's the tale of how tour.module got into core, keep an eye out for part 2 where we'll talk about how you use it for site-building and providing help for your modules.
Thanks for all the effort you put in to build this functionality in D8! I'd like to give people a bit more background on the origins of the whole idea. I suggested <a href="http://drupal.org/node/1164760#comment-4849504>the first seed of the idea</a>. Then <a href="http://drupal.org/user/581844">@franz</a> made the first mention of the words "video tutorial." Then do make sure to have a peek at comment #41 right below that says "It won't happen. Seriously."
I mentioned <a href="http://drupal.org/node/1164760#comment-5066584">the "official" idea of tour.module</a> many, many comments later. <a href="http://drupal.org/user/241634">@tim.plunkett</a> jumped into the conversation at comment #109. Finally at comment #170 <a href="http://drupal.org/user/404732">@cwegans</a> wrote the official feature request issue.
And, as they say, the rest was history.
This is great! Is there a Drupal 7 version of this module? I could use it right now!