Capstone Blog: The (De)Merits of Community Code

Posted on Sat, 12/05/2015 - 18:40

Back in Project Report #2, I first mentioned the idea of implementing a walk-through tour of an Open Eggheads site, “as one simple, yet effective, means of improving the user experience (UX) design of the site.” To get a sense of my original motivations for wanting to focus on creating such JavaScript-based tours, take a quick look at that post.

Long story, short: I ended up creating a whole series of walk-through tours, using the Bootstrap Tour JavaScript library (which I had mentioned in that previous blog post). This series of tours was then organized into a stand-alone Frequently Asked Questions (FAQ) page for an Open Eggheads site. For the current version of Open Eggheads, this FAQ page is meant to serve as the primary hub for user support. The current list of questions—each of which links to its own, unique, walk-through tour—aims to cover the majority of basic features that an Open Eggheads user would need to understand, in order to use their site effectively.


Screenshot of the FAQ page in its current form

In order to create these tours within the Drupal-based Open Eggheads platform, I decided to use the pre-existing Bootstrap Tour contributed module on Drupal.org, as a means of integrating the previously mentioned Bootstrap Tour JavaScript (JS) library into Open Eggheads. I chose to use this module, in lieu of manually installing the Bootstrap Tour JS library on my site. There are a few distinct advantages to doing so:

  1. It is MUCH easier to integrate the JS library into my site, without having to write countless, custom scripts just to call the library at the right time in Drupal’s bootstrapping process to create the necessary tours.
  2. The module comes with a pre-built, form-based UI for adding tours and adding steps within tours. This, again, makes the creation and integration of actual tours within the site extremely simple.

There is, however, one prevailing disadvantage to this contributed-module approach: Any contributed module is, by design, created for the widest possible range of use cases. It is meant to be used by the Drupal community-at-large, and so it is made to be applicable to as many generic use cases as possible. For normal usage, this is usually a benefit, rather than a problem. However, this approach limits the full capability of the Bootstrap Tour JS library itself.

As an example, I wanted to have my tours trigger certain events on the page, as the user clicked through certain tours. So, if a user reaches a certain step while learning how to use a form on the site, I might want my tour to trigger some sort of change in a form field, to better illustrate the concept being taught.

As any good JavaScript library does, the Bootstrap Tour library has its own well-documented API, which includes many methods that can be accessed for such use cases. So, if I want to trigger some sort of custom function when the user clicks “Next” on a particular step in the tour, the Bootstrap Tour API offers a pre-built method called “onNext”, to allow for such functions to be triggered.

Unfortunately, using the Bootstrap Tour contributed module doesn’t allow for easy access to this robust API. Because the basic call to the JS library were hard-coded into the Drupal module, I didn’t have easy access to methods like the “onNext” method mentioned above. Instead, I was forced to write my own countervailing JS snippets to make my tours more interactive.

These bits of custom JS on my part had to try and intercept (if not compete with) the pre-programmed JS offered by the Drupal module. For examples, I had to write some JS code to blindly listen for when a user clicked a specific “Next” button in a tour, to then trigger a change in the form they are viewing. Essentially, I was forced to write JavaScript that was listening for and reacting to other, unrelated JavaScript-based events. Such solutions, while functional, are less than ideal from the perspective of writing robust and easy-to-maintain code. It would have been much better (in terms of reliability and maintainability) if I could have used the Bootstrap Tour JS library’s built-in API, which would have been possible only if I had taken the trouble to manually integrate the library into my site.

In summary, using community-contributed modules to do some dirty work can often make things easier at the start. You are essentially trading in control for ease-of-use instead. However, as you start getting more sophisticated with what you’re trying to do, that initial bargain proves costly, since your hands are then tied for the most part when it comes to control. Consequently, you may be forced to struggle even more in the long term, due to those short-term compromises.

TL;DR: Be mindful of using pre-built solutions. What’s easy at first may prove to be even more difficult later on.