Tour Module Part 1: The Journey of Adding a Drupal Feature

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. 

As we were heading to Drupalcon Sydney a few days early, Nick and I hatched plans to work on this during transit and have it in a solid state to demo to folks during the conference. We put some extra work in to get the config entity and plugin stuff a bit cleaner, wrote the required test coverage and got a more substantial example together, for Views UI, arguably one of Drupal's most complex interfaces. At the same time we started work behind the scenes to gather support for the feature and get it as solid as possible. Nick reached out to Jesse Beach on IRC for help with overlay integration. We tagged the issue as Javascript to get a review from Théodore Biadala. Cameron Eagans pointed out that we needed to consider translation. We met with Thomas Svenson via Google Hangout for some input on the User Experience side of things. We reached out to Mike Gifford via the Skype accessibility to group to get a review from a usability point of view. 

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. 

And that is when the issue queue really lit up. Shortly after our lift ride we received a reply to our email from Dries to let us know he'd ask some folks to review it. And review they did. We had php reviews from Alex Bronstein, javascript reviews from Florian Margaine and a review of both from Wim Leers. Then we had a review from Tim Plunkett pointing out that our architecture had the config entities and plugins opposite to every other core interaction between the two. We had a plugin to wrap a config entity, whilst elsewhere in core ie in Views and Displays or Formats and Filters, the config entity wraps the plugins. At this time we also brought fellow PreviousNext accessibility expert Christian Biggins in to help. It would have looked weird for passers-by to see the three of us huddled around a laptop at the tables on the footpath outside the Drupalcon Sydney venue sharing a set of headphones to make sure the tour worked for visually impaired users!

We got a lot done during Drupalcon Sydney but after getting back there was still a lot to be done. Nick and I spent a lot of time and were given a lot of assistance from Tim Plunkett trying to get our heads around how the PluginBags (which allowed the config entity to track its plugins) worked. Nick finally got it working whilst Wim Leers completely rewrote the JavaScript to make use of Backbone.js. We were now at the weekend before feature freeze and cutting if very fine. Nick put a lot of late nights in that weekend to get it completely re-architected and I pitched in here and there a couple of times across the weekend to keep it moving. 

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.