VotingAPI: Hooks for greater control

This information is intended for developers creating modules that use VotingAPI.

VotingAPI provides a number of hooks that can be used by modules to alter the normal voting or tallying process, or to receive notification of voting-related events.

Create/Read/Update/Delete hooks

hook_votingapi_load(&$vote)

AFTER an individual vote object is loaded, this hook is triggered. You'll probably never need this, but it can be used to alter the incoming vote object before the calling module receives it.

hook_votingapi_insert($vote)

AFTER a new vote has been inserted into the database, this hook is triggered.

hook_votingapi_update($vote, $new_value)

AFTER an existing vote object has been altered, this function is triggered. The $vote object contains the original value of the vote, while $new_value is, predictably, its new value.

hook_votingapi_delete($vote)

BEFORE a vote object is deleted, this hook is triggered.

Calculation hooks

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

Whenever a vote is cast, VotingAPI gathers all the votes for that piece of content and calculates aggregate results. It calculates several default results (average vote, total number of voters, etc.), then triggers this hook.

Modules that implement it can directly alter the $results array, inserting their own records or replacing others. $votes is an array of all the votes for the current piece of content, while $results is a series of nested arrays in the following format:
$results[$tag][$value_type][$aggregate_function] = $value

Other

hook_votingapi_format($vote, $field)

VotingAPI provides several helper functions to format vote and result data. Whenever they are called, this hook is triggered, giving modules a chance to format or theme any custom voting types they have provided. The full vote object is provided, in addition to the field to be formatted ('tag', 'value_type', 'value', or 'function'). All modules have a chance to respond, but only the first respondant's fomatted result will be used. If you need to place nicely with other voting modules, be sure to only return a value if you know the vote is one your module 'understands.'

hook_votingapi_action_sets()

When used in conjunction with Actions.module, VotingAPI allows modules to expose sets of criteria ('average vote is higher than 75,' 'node type is forum', etc) and actions to be executed if the criteria are met ('promote the node to the front page,' 'email the author,' etc). This hook allows modules to return a structured array containing one or more 'action' sets to be evaluated whenever vote results are tallied.