header photo

via positiva

Voting API: The Next Generation

After a pleasant weekend of movie-watching, relaxing, and sporadic coding, there's a new version of VotingAPI checked into the Drupal CVS. It's probably as good a time as any to step back and examine the reason for the project.

  1. A framework, not a widgetExisting voting solutions implemented good UI widgets, but provided few options for sites that needed a different voting workflow. Creating a new system required starting from square one again. VotingAPI implements the back end -- saving and retrieving votes, calculating results in a variety of ways, and so on -- so that other modules can handle the site-specific stuff.
  2. Make easy things easyA contributed voting module only needs to use three functions: votingapi_set_vote(), votingapi_get_user_votes(), and votingapi_get_voting_results(). Modules that implement complex voting systems and workflow can utilize optional parameters and helper functions to tap into more functionality, but simple voting scenerios are simple to code.
  3. Vote on anythingVoting.module, node_voting.module, and others were good solutions but they applied only to nodes. VotingAPI is content-agnostic, and can be used to rate nodes, comments, users, or fish. With comment moderation stripped out of the Drupal Core for version 4.7, there's a definite need for a clean system that can deal with comments as well.
  4. Multi-criteria votingThis one's a show-stopper for sites that wanted to use voting to capture data on multiple aspects of a given thing. (Gathering community ratings for a game's graphics, audio, and plot, for example.)
  5. Vote in different waysPercentage voting, thumbs-up/thumbs-down voting, and custom voting styles are all supported. VotingAPI is smart enough to recognize the differences between the voting styles and calculate the correct results.
  6. Standardize data storageExisting voting systems all used custom data models. Voting data is valuable to lots of different modules; using a standard API to store and retrieve the data means other modules can be consumers of voting data without knowing what system produced the data.
  7. Expensive inserts, cheap selectsVotingAPI automatically caches aggregate voting results (total number of votes, average vote, etc) for fast retrieval. Whenever a new vote is cast, aggregate data is recalculated and re-cached. That means easier, less expensive joins for views and filters.
  8. Hooks for other custom calculationsLesser-used aggregate functions, like median votes, karma-adjusted votes, and so on can be implemented via hook_votingapi(). With it, modules can insert their own calculation logic during cache-time.

With last night's checkins, VotingAPI.module finally supports all of these features. There's still work to do, and I can think of ways to improve both the caching and simplify retrieval of filtered voting results. As it stands, though, it's fully functional and ready for other module developers to tinker with. Both BuddaBoy and merlinofchaos from #drupal have been instrumental in testing and brainstorming; hopefully the results will make life easier for them, too.

Huzzah!

Any Install Documentation?

Expecting users to know as much as you know is a bad teaching paradigm. In the download packages, there is not a single word how to install this API. Would be kind of courtesy to us, the ignorants, to provide such instructions.

Thank you

Copy the module to /modules, and enable it.

Under Drupal 4.7, VotingAPI handles its own installation as soon as you enable it on your site's admin/modules page.

Keep in mind that VotingAPI does NOT directly provide any voting 'widgets' or commands on your site. It's an API that other modules, like Vote Up Down, MediumVote, and UserReview, use to store and manipulate their voting data. Check out some of THOSE modules on Drupal.org for details. If you're not a developer, you don't really have any reason to work directly with THIS module.

It's 2009, and votingapi

It's 2009, and votingapi still has no code examples in the "documentation". Lose, lose.

Except, of course...

Except, of course, for the code examples contained in the 'API.txt' file that comes with the download, and the copious PHPDoc explaining every function in the API. Clearly not perfect, but my rule of thumb is, "If you don't know how to read PHPDoc, you shouldn't be using an API module."

VotingAPI rocks! It is one

VotingAPI rocks! It is one of the best Drupal modules available. Especially now that anonymous voting is possible when combining it with the 2.x branch of http://drupal.org/project/vote_up_down .

Post new comment

The content of this field is kept private and will not be shown publicly.
  • Allowed HTML tags: <a> <em> <strong> <cite> <code> <ul> <ol> <li> <dl> <dt> <dd> <blockquote> <img> <i> <b> <strike> <h3> <h4>
  • Lines and paragraphs break automatically.
  • You may use [inline:xx] tags to display uploaded files or images inline.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Twitter-style @usersnames are linked to their Twitter account pages.
  • Twitter-style #hashtags are linked to search.twitter.com.

More information about formatting options

Miniblog

  • Totally got the third item in that list from @blakehall btw. He's the clever one! 1 hour ago
  • There are two hard problems in CompSci: optimal cache invalidation, naming things, and off-by-one errors. 1 hour ago
  • OH: "Well, the Title title can just be the title, but reign_title can't be the reign title, or the title title." 4 hours ago
  • Know Drupal? Dig wrestling? Looks like the WWE is hiring... http://j.mp/bSu4pB 2 days ago
  • I want to be the Malcolm Gladwell of Drupal APIs. My breakout book will be named 'Clear Cache.' 4 days ago

SXSW Interactive 2011!