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.


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 'acuracy' and 'timeliness' of a news story. If you don't need to vote on multiple criteria, you can use the default value of 'vote'.
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 recored stores the vollowing 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.


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()


The VotingAPI hook (Bending the API to your will)
================================================
  insert
  update
  delete
  load
  calculate
  post calculate
  format (tag, value, result)


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