YouTourney/Drupal Case Study

*Note: this content is here to supplement the post on Drupal.org (at http://drupal.org/node/790858) until the images can be posted to that site.

Overview

YouTourney is an interactive, Drupal-based web application that makes running video competitions easy. YouTourney helps answer the question “Which video is the best?” through popular vote in head-to-head video matchups. Tournaments, Entry nominations, and Votes are all user-submitted. Much of the main functionality of YouTourney is based on such modules as Embedded Media Field (Video embedding and display), Voting API (Vote tallying), and CCK (Content type customization).

The Project

This project was predicated on a simple idea: make video contests easy, automated, and fun. To accomplish this, the “Tournament” has been broken down into 3 main user interactions for which the site is responsible.

1. Create Tournaments

Running a Tournament in the real world is generally a very involved activity. A real world Tournament Coordinator’s responsibilities can include anything from manually receiving entries, to seeding and organizing matchups, to collecting and tallying votes. These tasks are tedious and repetitive; the goal for YouTourney was to automate as much of this as possible. Moreover, the system is meant to be as extensible as possible to allow all sorts of different Tournament styles and functionality.

With YouTourney, all a Tournamant Coordinator needs to do is set some initial parameters (Entry Deadline, Round Length, Tournament Style, and Tournament Rules, etc), and accept or reject Entries. From there, YouTourney automates everything from seeding the Entries, to tallying votes, to determining the winner, and even handling ties and other corner cases gracefully.

2. Receive Entry Nominations

The Video Sharing market is already pretty well saturated. Creating another venue for uploading and streaming video content is certainly not the goal with YouTourney. Keeping this in mind, the site was designed such that no video content is actually uploaded to YouTourney – instead, embeddable content can be imported from sites all over the web (currently YouTube is supported, but future expansion to include Vimeo and a variety of other sites is in the works).

Entering a video into a Tournament is as easy as copying and pasting the video’s URL. This way, users with existing content don’t need to upload their video all over again – and users that want to nominate a video that is not their own don’t need to “steal” the content in order to submit it. Currently, YouTourney makes heavy use of the YouTube API.

3. Tally User Votes

The outcome of every matchup, and ultimately of the Tournament, is decided by user votes. This is similar to the American Idol popular voting model. Voting should be as easy as clicking the button next to the video of your choice, and anyone should be able to vote, while maintaining vote integrity.

Tournament Flow

Tournaments move through 3 stages: (1) Entry Period; (2) Voting Period, during which multiple rounds of matchups may occur; (3) Completion.

The following outlines the Tournament process from the perspectives of the Tournament Coordinator (creator), a normal user, and the YouTourney System.

As you can see, the User’s and Coordinator’s responsibilities are minimized, and YouTourney does all the heavy lifting. This takes the burden off of the user, all but removing the barrier to entry for creating and hosting a video Tournament. Hopefully, this will inspire more users to create all different types of Tournaments, given the ease with which they can be created.

The events are triggered via cron hooks at timed intervals (see below).

For reference, the following shows how a general Knockout Tournament progresses:

Each round, the Entry pool is reduced by (about) half, until only two videos remain. They are then voted on in the Championship Matchup to determine the winner.

Drupal Implementation

Content Types

As with any Drupal site, the basic building block of YouTourney is the Node. To model Tournaments, YouTourney uses 3 special Content types, constructed via the Content Construction Kit (CCK). The main node types are:

Entry – The Entry Node type contains a video entry and a reference to the Tournament to which it belongs (via the Node Reference module). The Node maintains basic information about the Entry as well as the Entry’s state – for example, whether the Entry is currently Active, Eliminated, Awaiting Approval, on Bye, etc. Here the Embedded Media Field Module works its magic to easily convert a video’s URL into an embedded video on the Entry page. Users fill out the simple Entry Node creation form to submit a video to a Tournament.

Matchup – The Matchup Node contains references to two Entries (via the Node Reference module), and maintains state for the Matchup – for example, whether the Matchup is active or complete, when voting for the Matchup ends, what round the Matchup belongs to, etc. The Matchup also contains a reference to the Tournament to which it belongs. Matchups are generated programmatically each round by the system, via a custom module.

Tournament – The Tournament Node contains the Tournament settings (Name, Welcome Video, Tournament Description, Type, Entry Style, Deadline, etc), as well as some Tournament state (e.g. Accepting Entries, Voting Period, Completed). The Content Permissions module was used to display only relevant fields to normal users.

Theming

The custom theme developed for YouTourney is based on the Zen theme. Extensive theming was used to produce the desired look and feel of the site. Each of the Content Types above, for example, was given its own template (e.g. node-tournament.tpl.php). Most of the content display was entirely rewritten this way, and much of the structure was made the responsibility of the Tournament Logic Wrapper classes (see Tournament Logic below). Styling, of course, is entirely done through CSS.

Custom theme functions were written to wrap, for example, the Embeddable Media Field video widgets, in order to increase the flexibility of display options such as size throughout the content display areas.

User Interaction

Voting

The most basic action on YouTourney is voting. Every vote is recorded with reference to the Entry Node as well as the Matchup Node. This allows votes to be distinguished between Entries as well as between rounds. To do this, YouTourney makes use of the excellent Voting API. Every vote is cast against the Entry (node) for which it is intended, and tagged with the Matchup Node ID. The Voting API comes with some great out-of-the-box functionality such as anonymous voting capability as well.

A custom module named “Versus” was used to enable head-to-head voting, and restrict voting to only one Entry per matchup. Versus themes its own ajaxified widgets which are displayed on the Matchup page.

The voting statistics are displayed via the Google Charts Javascript API.

The Matchup page – the meat and potatoes of YouTourney:

Views

The Views module was used throughout the site, from the front page slider, to the Matchup and Entry listings on the Tournament page, to the search results page (using the Faceted Search Module).

Following

A “Follow” function, similar to Facebook’s “Like”, Twitter’s “Follow”, or other similar social links, allows users to keep track of Tournaments or Entries in which they are interested. Notifications pertaining to the activity of these Tournaments and Entries then show up in the user’s Activity Feed, and certain notifications are delivered via email. The “Follow” mechanism was implemented using the highly versatile Flag module.

Taxonomy
Taxonomic categorization on the site is accomplished via the Content Taxonomy module, providing Tournament moderators the ability to categorize their Tournaments into a predetermined vocabulary, and Entry submitters to tag their submissions freely.

Community Watch
Once in a while, an inappropriate video makes its way through the filters and into a Tournament. In this case, users can flag it as inappropriate. Naturally, the Flag module was used to implement this functionality (a simple custom function was used to send an alert rather than using preexisting solutions like the Abuse module in order to keep the enabled modules count as low as possible).

Help & Tips – The site makes use of the jQuery plugin qTip to offer helpful messages as users fill out forms and interact with the site.

Tournament Logic

Classes

The logic for the Tournaments is contained in three main classes and their subclasses – Entry, Matchup, and Tournament. For example, the Tournament class is responsible for counting up votes and declaring Matchup winners, seeding Entries into Matchups, generating brackets and final rankings, etc. These three classes wrap their respective $node objects and provide extra functionality and logic.

Events

Obviously, there needs to be some type of mechanism for performing actions at particular Tournament events (Tournament Start, Round End, Tournament End, etc). As these events are dictated by predetermined times (Entry Deadline, Round Length), the custom Tournament logic module uses the cron hook to search for Tournaments with expired states, and calls an update() function for those Tournaments. The Tournaments inspect their own state and perform the required updates.

Social Media Connections

YouTourney also allows users to make social media connections to other sites. One use of this feature is to allow social interactions and one-click sign-ins through sites like Facebook and Twitter.

More interestingly, YouTourney also allows users to link their YouTourney accounts to their YouTube accounts. By authenticating and then associating YouTube user names with YouTourney users, video nominations on YouTourney can be linked to their owners on YouTourney, as well as on YouTube.

That is, say Bob has an account on YouTourney, BobTourney, and an account on YouTube, BobTube. If Bob, or any other user, submits a video on YouTourney, there’s no way to determine BobTube’s identity on YouTourney, or even if BobTube uses YouTourney. If Bob links his two accounts, then when a video from BobTube is submitted to YouTourney, the system will find that BobTourney is the YouTourney account linked to the video. This allows Bob to receive “credit” for the video on YouTourney, as well as receive notifications when his videos are nominated by other users. This UserConnect functionality utilizes OAuth as much as possible.

Other Important Contributed Modules

Several other important modules went into making YouTourney run smoothly. Thanks so much to all the hard work these people put in to these great modules. Some of the highlights are:

CCK – The Content Construction Kit was used to craft all the content types on the site, most importantly those modeling Tournaments, Matchups, and Entries.

Embedded Media Field – EmField provided most of the functionality needed to embed videos straight from URLs, and saved a ton of time.

Flag – Flag is an excellent and extremely versatile module, especially if you’re creative. I’ve used this in a variety of ways in every Drupal project I’ve worked on. For YouTourney, Flag enabled user “Following” of Tournament and Entries, abuse reporting, and “agreeing” for the custom Get Satisfaction-like Feedback module. Flag also provides a solid API for interacting with the module.

CCK Node Reference – Creates a user-friendly interface for linking nodes (unidirectional). This made it easy to create a Matchup, which is essentially a wrapper for two Entry Nodes with a reference to a Tournament (3 references total).

Views – Views is another invaluable tool in every developer’s toolkit. Views was used for everything from the front page feature box, to the Entry and Matchup listings on the Tournament pages, to the search results (using Faceted Search).

Voting API – The Voting API module was used as the basis for the custom Versus module, which allowed head-to-head voting and tallying of votes within a given Matchup.

Content Profile – The Content Profile module made it easy to create User Profiles with a custom CCK Content Type.

Date – the Date module allowed both an out-of-the-box calendar widget as well as time zone handling for displaying accurate Tournament end dates around the world.

Devel – the Devel module is an indispensable tool for any developer.

LoginToboggan – LoginToboggan takes care of about 85% of the Login form customizations on YouTourney, and a custom module took care of the rest (Terms of Service, Captcha, etc). Most importantly, LoginToboggan allows the user to set a password at the time of registration, and sets up a mechanism for pre-authorizing users.

CAPTCHA/reCAPTCHA – Easy to set up and add to forms, the CAPTCHA and reCAPTCHA modules are an important part of any publicly accessible site to keep bots out.

Custom GetFeedback Module

YouTourney uses a custom Feedback module implemented in the vein of the popular GetSatisfaction system, but contained entirely within the site. Users submit feedback, and can vote on popular feedback items, allowing developers to focus on the most requested features, or the most common problems, etc.

The GetFeedback module uses the jQuery qTip plugin, CCK, Views, and Flag, to reproduce the essential elements of systems like GetSatisfaction. As these modules (and jQuery library) were all already in use on the site, there was no little overhead incurred to create this module.

qTip – A “Feedback” button is positioned on the left edge of the page. Upon clicking, a form pops up in a qTip dialog allowing users to submit feedback.

CCK – Using CCK, a “Feedback” content type was created, and this node creation form is shown in the popup. The type of feedback (question, idea, problem, other) is a radio button selection element.

Flag – The Flag module is used to allow users to “Agree” with a particular piece of Feedback, promoting it up the chain so it can get more attention. It also allows issues to be marked as “resolved”.

Views – The Views module is used to show “Popular” Feedback of the same type within the dialog.

I have not come across similar functionality in any other module that I’ve come across (apart from the GetSatisfaction module). Refactoring this code a bit may make for a solid module contribution if there is community interest.

Optimization & Scalability

Drupal requires some tweaks order to successfully scale for a large, high-traffic site (where many of us aspire to be one day). In an attempt to start down this road as early as possible and to set the site up for success should it ever achieve such traffic, YouTourney has been tweaked for performance wherever possible. While this is outside the scope of this case study, I would like to highly recommend the following resource: Squeezing the last drop from Drupal: Performance and Scalability. I found this to be an invaluable guide to optimizing the site!

Methods used include conversion of cache tables to InnoDB, installation of APC PHP accelerator, MySQL and Apache tuning.

YouTourney is running Drupal 6 and is currently hosted with Cloud Server hosting from Rackspace. It runs on an Ubuntu 9.10 (Karmic Koala) LAMP stack.

Conclusion

Having spent an inordinate of time researching and experimenting with content management systems, I can highly recommend Drupal for a site of this magnitude. Drupal provides an excellent platform for development, and with so much flexibility enables almost limitless customization. The wonderful array of community-contributed modules are both robust and well maintained. They save huge amounts of time even with highly-customized sites.

Thank you so much to the Drupal community for the excellent work done here! I hope this case study provides at least a small amount of give back.

You can check out the site at http://youtourney.com. There is more information available at http://blog.youtourney.com as well.

Thanks for reading – I hope people find this useful. Feedback is most welcome!