function votingapi_set_votes in Voting API 7.2

Same name and namespace in other branches

1. 6.2 votingapi.module \votingapi_set_votes()
2. 7.3 votingapi.module \votingapi_set_votes()

Cast a vote on a particular piece of content.

This function does most of the heavy lifting needed by third-party modules based on VotingAPI. Handles clearing out old votes for a given piece of content, saving the incoming votes, and re-tallying the results given the new data.

Modules that need more explicit control can call votingapi_add_votes() and manage the deletion/recalculation tasks manually.

Parameters

array $votes: An array of votes, each with the following structure: $vote['entity_type'] (Optional, defaults to 'node') $vote['entity_id'] (Required) $vote['value_type'] (Optional, defaults to 'percent') $vote['value'] (Required) $vote['tag'] (Optional, defaults to 'vote') $vote['uid'] (Optional, defaults to current user) $vote['vote_source'] (Optional, defaults to current IP) $vote['timestamp'] (Optional, defaults to REQUEST_TIME)

array $criteria: A keyed array used to determine what votes will be deleted when the current vote is cast. If no value is specified, all votes for the current content by the current user will be reset. If an empty array is passed in, no votes will be reset and all incoming votes will be saved IN ADDITION to existing ones. $criteria['vote_id'] (If this is set, all other keys are skipped) $criteria['entity_type'] $criteria['entity_id'] $criteria['value_type'] $criteria['tag'] $criteria['uid'] $criteria['vote_source'] $criteria['timestamp'] (If this is set, records with timestamps GREATER THAN the set value will be selected.)

Return value

array An array of vote result records affected by the vote. The values are contained in a nested array keyed thusly: $value = $results[$entity_type][$entity_id][$tag][$value_type][$function]

See also

votingapi_add_votes()

votingapi_recalculate_results()

1 call to votingapi_set_votes()

_votingapi_cast_votes in ./votingapi.devel.inc

Utility function to generate votes on a node by a set of users.

File

./votingapi.module, line 179

A generalized voting API for Drupal.

Code

function votingapi_set_votes(&$votes, $criteria = NULL) {
  $touched = array();
  if (!empty($votes['entity_id'])) {
    $votes = array(
      $votes,
    );
  }

  // Allow other modules to modify or unset/remove votes.
  // module_invoke_all does not allow passing variables by reference
  // http://api.drupal.org/api/drupal/includes%21module.inc/function/module_invoke_all/7#comment-35778
  drupal_alter(array(
    'votingapi_preset_votes',
  ), $votes);

  // Handle clearing out old votes if they exist.
  if (!isset($criteria)) {

    // If the calling function didn't explicitly set criteria for vote deletion,
    // build up the delete queries here.
    foreach ($votes as $vote) {
      $identifier_info = votingapi_current_user_identifier();

      // Make sure we're dealing with an array to avoid errors.
      if (is_array($vote) && is_array($identifier_info)) {
        $tmp = $vote + $identifier_info;
      }
      if (isset($tmp['value'])) {
        unset($tmp['value']);
      }
      votingapi_delete_votes(votingapi_select_votes($tmp));
    }
  }
  elseif (is_array($criteria)) {

    // The calling function passed in an explicit set of delete filters.
    if (!empty($criteria['entity_id'])) {
      $criteria = array(
        $criteria,
      );
    }
    foreach ($criteria as $c) {
      votingapi_delete_votes(votingapi_select_votes($c));
    }
  }
  foreach ($votes as $key => $vote) {
    _votingapi_prep_vote($vote);
    $votes[$key] = $vote;

    // Is this needed? Check to see how PHP4 handles refs.
  }

  // Cast the actual votes, inserting them into the table.
  votingapi_add_votes($votes);
  foreach ($votes as $vote) {
    $touched[$vote['entity_type']][$vote['entity_id']] = TRUE;
  }
  if (variable_get('votingapi_calculation_schedule', 'immediate') != 'cron') {
    foreach ($touched as $type => $ids) {
      foreach ($ids as $id => $bool) {
        $touched[$type][$id] = votingapi_recalculate_results($type, $id);
      }
    }
  }
  return $touched;
}