Voting API

I want to emphasize that this module is based almost completely on benshell's work with voting.module. I just pulled out the flash dependencies and cleaned up one of the queries for the module I needed it for.

Part of the reason I'm soliciting thoughts from other people who've implemented voting modules is because I'm not sure what functionality would be universally applicable. What makes sense to centralize, beyond simple saving/retrieving?

I suppose if the schema is standardized, at least, writing custom queries against it would be simpler.

I think you're definitely right in recognizing some of the issues. I've been spending a lot of time pondering this lately... and the reluctance to change the DB schema underneath your current users makes a lot of sense.

The reason I think a voting API of SOME sort is important is simple: many modules, and many areas of the Drupal system, involve mechanisms by which multiple users contribute a data point to arrive at some group decision. That may be 'How funny is this joke?' or 'Should this content be promoted to the front page?' or 'Do we trust this person's opinions?'

As Drupal's capabilities for building community sites grow, and more sites with LARGE communites are built on this foundation, I think it'll be more and more important. For community-oriented sites, I think that mechanisms for these systems can be as critical as image support or RSS feeds.

There are a couple of distinct questions, though, that keep coming up.

1. How is data for a variety of voting mechanisms stored consistently? Thumbs up/thumbs down systems, 1-10 systems, 0-100% systems, multicriteria rating*, and 'microcommentary**' systems, like slashdot moderation, are all different options.
2. If different modules can apply different voting metrics to pieces of content, will the 'community opinion' data become just as fragmented as with a collection of separate modules?
3. Different modules (and different users) will want to act on this information in different ways. One module might want to promote highly-rated comments into front-page nodes for further discussion. Another might want to expose voting totals to end users and allow them to hide messages under a certain threshold. Another might want to change a user's role, or assign them userpoints, if they accumulate enough 'karma' via other users' votes on their content.

One possible answer to this is to provide a very very bare-bones voting API, only a step removed from the one that's currently posted. There are already fields for the vote itself, user information, and content-type information. Adding one additional field -- 'vote_type' -- would allow modules to capture information like 'this vote is a karma point' or 'this vote pertains to the given node's technical quality.'

The API would support saving and retrieving individual votes and sets of votes, and expose a set of hooks to allow modules to act on votes whenever they're cast. Some might even store their own additional information -- my 'latestgreatest' module stores its own record for each aggregator item that's reached a promotion threshold, so that the voting user-widgets are hidden once an item gets promoted. Once it hits the promotion point, no more vote aggregation is necessary. I can envision complicated user-trust or karma calculations happening in that way -- the vote API being used to collect 'raw data' and the karma module being used to calculate the results.

Thoughts? Feedback?

--Jeff

* With multicriteria rating, a given story might be rated both on concept and execution.

** With microcommentary systems, 'votes' are more like tags a user applies to a piece of content, some with positive and some with negative connotations. 'Funny,' 'Flamebait,' 'Informative,' 'Disingenuous,' and so on. Drupal's comment moderation matrix was a bit like this in 4.6, but it's been stripped out in 4.7 to be replaced by a module. That module has yet to be written, thus my early work on voting API :-)

--
Jeff Eaton | Click Here To Find Out Why Drupal "Sucks"

The bad key is, in fact, a bug. Fixing it shortly.

I want to emphasize that the VotingAPI as it stands right now (the CVS version, not the 4.6 tagged version) is not at all functionally complete. To solve the problem of multicriteria voting, I had to drop down a level. Implementing the functionality of the 4.6 version will require another layer on top of the basic set/get vote calls.

I've been tinkering around with ideas on how to best do this, and haven't gotten a lot of feedback yet, so I decided to sart marching forward. If you want it to stay in place, I'd recommend sticking with the 4.6 tagged version until the next layer of functionality is complete.

The question of what vote results should be calculated by the API itself, and what results will need 'knowledge' from the modules that inserted them, is a difficult one... Especially if the API is to be flexible enough to store more than one kind of vote.

Because of the possibility that multiple modules could record votes for the same content with diffrent tags and different meanings ('popularity' and 'accuracy' for example), or the potential for the 'vote' value to be a foreign key for something like the Comment Moderation Matrix, it gets tricky.

Thus, a single flexible 'get' function that can filter by tag or by user, and a calculation hook.

I'd like to whip up a basic votingapi_totals.module over the next week that implements basic calculations like 'highest and lowest votes by tag,' 'median vote by tag,' and 'sum of all votes by tag' for a given $votes object. They wouldn't be accurate for some of the esoteric situations, but it could certainly be useful. Once that's in place your module would be able to look at the calculated vote without doing any of the work.

Do you have any thoughts? As a consumer of votingapi data, what do YOU want it to give you as a result?

--
Jeff Eaton | I heart Drupal.

Hey! Thanks for the response. I hope the basics of the API stay stable at this point, and the data scheme stays stable as well. i think there's still a lot of room for improvement in streamlining the approach to querying, etc.

First: I'll be uploading an example of VERY simple thumbs-up voting using latestgreatest.module later this evening.

Second: The get_resuts() function returns a list of objects because (at least in some instances) the results may contain cached totals for a variety of value types, and a variety of voting tags (like 'camerawork' or 'composition' or the ever-popular default 'vote').

As such, the code you pasted would certainly work in a single-voting-system scenerio. In a scenerio where you might share space with many different types of voting, you might want to add an additional check:

<?php
$results = votingapi_get_voting_results($content_type, $content_id);
foreach($results as $result) {
    if ($result->value_type == VOTINGAPI_VALUE_TYPE_PERCENT && $result->tag == 'vote') {
        if ($result->function == 'count') {
            $num_votes = $result->value;
        } elseif ($result->function == 'average') {
            $avg_vote = $result->value;
        }
    }
}
?>

What I'd like to do is add an optional set of parameters to the get_results() function, allowing module developers to quickly and easily filter by value_type, tag, and (optionally) function. That would allow the code to look more like this:

<?php
$results = votingapi_get_voting_results($content_type, $content_id, $value_type, $tag);
foreach($results as $result) {
    if ($result->function == 'count') {
        $num_votes = $result->value;
    } elseif ($result->function == 'average') {
        $avg_vote = $result->value;
    }
}
?>

Finally, regarding the integer, I have to check into that one. It SHOULD be saving and calculating averages as floats, but that's one bit I didn't have a chance to text extensively. If it's broken, and is truncating to ints, that's my fault. ;)

You are right, though, in that working with the 'percentage' value type assumes that you'll be feeding in values that are already percentages. For example, a 1-5 scale would be represented as 0, 25, 50, 75, 100.

I'll also be trying to put together a few snippet-style examples of how to best interact with the API in different situations. Fortunately, most of THIS stuff is frosting on top of the underlying system, and adding filtered helper functions doesn't break anything. From your perspective, what kinds of helper functions would be most useful? What would simplify your life as a module developer interacting with the API? Would it be MORE useful to have the results of a get_results() call be a nested array? Perhaps something like:

<?php
$results = votingapi_get_voting_results($content_type, $content_id, $value_type, $tag);
$num_votes = $result[$value_type][$tag]['count'];
$avg_vote = $result[$value_type][$tag]['average'];
}
?>

This would mirror the array that modules can iterate through with the calculate hook.

I don't want to make things hash, but it seems like settling these questions earlier rather than later can only be a good thing...

--
Jeff Eaton | I heart Drupal.