Last updated June 26, 2014. Created on June 13, 2006.
Edited by batigolix, corbacho, dww, eaton. Log in to edit this page.

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

Notice that the documentation published here does not correspond the current version of the votingapi module 6.x and 7.x. Check the file votingapi.api.php which is included with the module

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

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.
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.
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

hook_votingapi_results($results, $votes, $content_type, $content_id)
After all the results have been calculated and saved, this hook is triggered for modules that wish to respond to vote results, but not alter them. $results is a flat array of all the cached vote result objects that were saved, while $votes is an array of the individual vote objects.


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.'
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.

Looking for support? Visit the forums, or join #drupal-support in IRC.


Bevan’s picture

Are the Calculation hooks called "Whenever a vote is cast" even when "Tally results at cron-time" is set on admin/settings/votingapi? I would expect the Calculation hooks are only called at cron time if "Tally results at cron-time" is set. Can someone please confirm or deny so I can update documentation. Thanks! :)

tommytom’s picture

can somebody update the info here, pls

organicwire’s picture

The documentation published here does not correspond the current version of the votingapi module (6.x-2.3). Check the file votingapi.api.php which is included in the module's tarball. You can also browse the module's api documentation at

abhid90210’s picture

AFIK hook_update has been removed now.

qasimzee’s picture

What is the alternative of hook_votingapi_insert in drupal 7 ?

Qasim Zeeshan