$Id: API.txt,v 1.6.4.2 2008-06-06 00:00:30 eaton Exp $

What's this, now?
=================
VotingAPI provides a flexible, easy-to-use framework for rating, voting, moderation, and consensus-gathering modules in Drupal. It allows module developers to focus on their ideas (say, providing a 'rate this thread' widget at the bottom of each forum post) without worrying about the grunt work of storing votes, preventing ballot-stuffing, calculating the results, and so on.

VotingAPI handles three key things for module developers:

1) CRUD
Create/Retrieve/Update/Delete operations for voting data. The simplest modules only need to call two functions -- votingapi_set_vote() and votingapi_select_results() -- to use the API. Others can use finer-grain functions for complete control.

2) Calculation
Every time a user casts a vote, VotingAPI calculates the results and caches them for you. You can use the default calculations (like average, total, etc) or implement your own custom tallying functions.

3) Display
VotingAPI integrates with Views.module, allowing you to slice and dice your site's content based on user consensus. While some custom modules may need to implement thier own Views integration to provide customized integration, the vast majority can use the built-in system without any additional work.


How Data Is Stored
==================
VotingAPI manages a raw 'pool' of vote data -- it doesn't keep track of any content directly. Instead, it lets modules store each vote with a 'content type' and 'content id', so that the same APIs can be used to rate nodes, comments, users, aggregator items, or even other votes (in a Slashdot-esque meta-moderation system). It can also be used by modules that need to store and calculate custom data like polling results -- using a custom content_type ensures that other modules won't trample on your module's voting data.

For each discrete vote, the API stores the following information:

content_type -- This *usually* corresponds to a type of Drupal content, like 'node' or 'comment' or 'user'.
content_id   -- The key ID of the content being rated.
value        -- This is the actual value of the vote that was cast by the user.
value_type   -- This determines how vote results are totaled. VotingAPI supports three value types by default: 'percent' votes are averaged, 'points' votes are summed up, and 'option' votes get a count of votes cast for each specific option.  Modules can use other value_types, but must implement their own calculation functions to generate vote results -- more on that later.
tag          -- Modules can use different tags to store votes on specific aspects of a piece of content, like 'accuracy' and 'timeliness' of a news story. If you don't need to vote on multiple criteria, you should use the default value of 'vote'. If you use multiple tags, it is STRONGLY recommended that you provide an average or 'overall' value filed under the default 'vote' tag. This gives other modules that display voting data a single value to key on for sorting, etc.
uid          -- The user ID of the person who voted.
timestamp    -- The time the vote was cast.
vote_source  -- A unique identifier used to distinguish votes cast by anonymous users. By default, this is the IP address of the remote machine.

Whenever a vote is cast, VotingAPI gathers up all the votes for the content_type/content_id combination, and creates a collection of cached 'result' records. Each voting result recorded stores the following information:

content_type -- Just what you'd expect from the individual vote objects.
content_id   -- Ditto.
value_type   -- Ditto.
tag          -- Ditto.
function     -- The aggregate function that's been calculated -- for example, 'average', 'sum', and so on.
value        -- The value of the aggregate function.
timestamp    -- The time the results were calculated.


Upgrading from VotingAPI 1.x
============================
Version 2.0 of VotingAPI offers several notable changes. Modules MUST be updated to work with VotingAPI 2.0, but changes for most modules should be minimal. Among other things, version 2.0 offers automatic support for anonymous votes -- something that required custom vote handling in version 1.x.

1) Functions accept objects and arrays of objects instead of long parameter lists
VotingAPI 1.x used relatively complex parameter lists in its most commonly used functions. In version 2.x, VotingAPI vote-casting functions accept a single vote object or array of vote objects, while vote and result retrieval functions accept a keyed array describing the filter criteria to be used. 

2) hook_votingapi_update() Removed
This function allowed modules to intervene whenever a user changed their vote. The processing overhead that it imposed on most operations, however, was severe. No modules in contrib implemented the hook, and it has been eliminated. hook_votingapi_insert() and hook_votingapi_delete() are still available.

3) Retrieval functions consolidated
In VotingAPI 1.x, votes for a content object were retrieved using a dizzying array of functions, including the ugly buy often-used internal function, _votingapi_get_raw_votes(). In version 2.x, the following functions are provided:

* votingapi_select_votes();
* votingapi_select_results();
* votingapi_select_single_vote_value()
* votingapi_select_single_result_value();

4) Custom result calculations must do their own SQL
In version 1.x, VotingAPI loaded all votes for a given content object in order to calculate the average vote using PHP. Modules calculating their own results (median, etc.) were handed the stack of vote objects and given an opportunity to do more using hook_votingapi_calculate(). This was fine for simple cases, but consumed monstrous amounts of RAM whenever a single piece of content accumulated large numbers of votes.

In version 2.x, VotingAPI modules may implement hook_votingapi_results_alter() instead. They receive the same information about the content object, and the stack of results to modify, but are responsible for using their own SQL to generate their results. Fortunately, most modules implementing custom results required complex calculations more efficiently done in SQL anyways.


An example custom calculation
=============================
The following function adds a standard_deviation result to the calculated result data.
Note that in previous versions of VotingAPI, this function received in-memory copies of
each and every cast vote to avoid the need for custom SQL. This turned out to be very,
very, very inefficient -- the slowdown of possibly running multiple aggregate queries is
far outweighed by the memory savings of each module handling its own queries. After all,
MySQL calculates standard deviation far faster than you can in PHP.

function mymodule_votingapi_results_alter(&$results, $content_type, $content_id) {
  // We're using a MySQLism (STDDEV isn't ANSI SQL), but it's OK because this is
  // an example. And no one would ever base real code on sample code. Ever. Never.
  $sql  = "SELECT v.tag, STDDEV(v.value) as standard_deviation ";
  $sql .= "FROM {votingapi_vote} v ";
  $sql .= "WHERE v.content_type = '%s' AND v.content_id = %d AND v.value_type = 'percent' ";
  $sql .= "GROUP BY v.tag";

  $results = db_query($sql, $content_type, $content_id);

  // VotingAPI wants the data in the following format:
  // $cache[$tag][$value_type][$math_function] = $value;
  while ($result = db_fetch_array($results)) {
    $cache[$result['tag']]['percent']['standard_deviation'] = $result['standard_deviation'];
  }
}