$Id: API.txt,v 1.6 2007-07-17 05:54:17 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.


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_select_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_insert($vote)
  hook_votingapi_update($vote, $new_value)
  hook_votingapi_delete($vote)

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

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

2) Retrieval functions consolidated

3) Lesser-used hooks eliminated