$Id: API.txt,v 1.4 2006/06/09 00:15:01 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 four 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_get_voting_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) Workflow
Every time results are calculated for a piece of content, VotingAPI can launch actions (like promoting a node to the front page, hiding a comment that's been flagged as spam, or emailing an administrator) if specified criteria are met.

4) Display
VotingAPI integrates with Views.module, allowing you to slice and dice your site's content based on user consensus. It also provides convenience functions to format vote data for display to users.


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.
hostname     -- The IP address of the host the vote was cast from.

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.


How it works (high-level overview)
==================================
  An example: SimpleVote
    Load the vote results
    Display the vote results
    Cast a vote
      (invisible steps: recalculation, and votingapi $ops)
    And so on, ad infitum


Using the API (The Easy Way)
============================
  High-level functions
    votingapi_set_vote()
    votingapi_unset_vote()
    votingapi_get_voting_results()


Using the API (With Full Control)
=================================
  Core functions (for full control)
    votingapi_add_vote()
    votingapi_change_vote()
    votingapi_delete_vote()
    votingapi_delete_votes()
    votingapi_recalculate_results()
    votingapi_get_user_votes()
    votingapi_get_content_votes()


VotingAPI hooks (Bending the API to your will)
================================================
  hook_votingapi_load($vote)
  hook_votingapi_insert($vote)
  hook_votingapi_update($vote, $new_value)
  hook_votingapi_delete($vote)

  hook_votingapi_format($vote, $field)

  hook_votingapi_calculate(&$results, $votes, $content_type, $content_id)
  hook_votingapi_results($results, $votes, $content_type, $content_id)


Actions Integration
===================
  Providing default actions
  Exposing custom action handlers

  hook_votingapi_action_sets()