root / drupal7 / sites / all / modules / votingapi / votingapi.api.php @ fcc9430f
1 |
<?php
|
---|---|
2 |
|
3 |
/**
|
4 |
* @file
|
5 |
* Provides hook documentation for the VotingAPI module.
|
6 |
*/
|
7 |
|
8 |
|
9 |
/**
|
10 |
* Adds to or changes the calculated vote results for a piece of content.
|
11 |
*
|
12 |
* VotingAPI calculates a number of common aggregate functions automatically,
|
13 |
* including the average vote and total number of votes cast. Results are
|
14 |
* grouped by 'tag', 'value_type', and then 'function' in the following format:
|
15 |
*
|
16 |
* $results[$tag][$value_type][$aggregate_function] = $value;
|
17 |
*
|
18 |
* If no custom tag is being used for votes, the catch-all "vote" tag should be
|
19 |
* used. In cases where custom tags are used to vote on different aspects of a
|
20 |
* piece of content, a catch-all "vote" value should still be calculated for
|
21 |
* use
|
22 |
* on summary screens, etc.
|
23 |
*
|
24 |
* @param $vote_results
|
25 |
* An alterable array of aggregate vote results.
|
26 |
* @param $content_type
|
27 |
* A string identifying the type of content being rated. Node, comment,
|
28 |
* aggregator item, etc.
|
29 |
* @param $content_id
|
30 |
* The key ID of the content being rated.
|
31 |
*
|
32 |
* @see votingapi_recalculate_results()
|
33 |
*/
|
34 |
function hook_votingapi_results_alter(&$vote_results, $content_type, $content_id) { |
35 |
// We're using a MySQLism (STDDEV isn't ANSI SQL), but it's OK because this is
|
36 |
// an example. And no one would ever base real code on sample code. Ever. Never.
|
37 |
|
38 |
$sql = "SELECT v.tag, STDDEV(v.value) as standard_deviation "; |
39 |
$sql .= "FROM {votingapi_vote} v "; |
40 |
$sql .= "WHERE v.content_type = '%s' AND v.content_id = %d AND v.value_type = 'percent' "; |
41 |
$sql .= "GROUP BY v.tag"; |
42 |
|
43 |
$aggregates = db_query($sql, $content_type, $content_id); |
44 |
|
45 |
// VotingAPI wants the data in the following format:
|
46 |
// $vote_results[$tag][$value_type][$aggregate_function] = $value;
|
47 |
|
48 |
while ($aggregate = db_fetch_array($aggregates)) { |
49 |
$vote_results[$result['tag']]['percent']['standard_deviation'] = $result['standard_deviation']; |
50 |
} |
51 |
} |
52 |
|
53 |
|
54 |
/**
|
55 |
* Adds to or alters metadata describing Voting tags, value_types, and
|
56 |
* functions.
|
57 |
*
|
58 |
* If your module uses custom tags or value_types, or calculates custom
|
59 |
* aggregate functions, please implement this hook so other modules can
|
60 |
* properly interperet and display your data.
|
61 |
*
|
62 |
* Three major bins of data are stored: tags, value_types, and aggregate result
|
63 |
* functions. Each entry in these bins is keyed by the value stored in the
|
64 |
* actual VotingAPI tables, and contains an array with (minimally) 'name' and
|
65 |
* 'description' keys. Modules can add extra keys to their entries if desired.
|
66 |
*
|
67 |
* @param $data
|
68 |
* An alterable array of aggregate vote results.
|
69 |
*
|
70 |
* @see votingapi_metadata()
|
71 |
*/
|
72 |
function hook_votingapi_metadata_alter(&$data) { |
73 |
// Document several custom tags for rating restaurants and meals.
|
74 |
$data['tags']['bread'] = array( |
75 |
'name' => t('Bread'), |
76 |
'description' => t('The quality of the food at a restaurant.'), |
77 |
'module' => 'mymodule', |
78 |
// This is optional; we can add it for our own purposes.
|
79 |
); |
80 |
$data['tags']['circuses'] = array( |
81 |
'name' => t('Circuses'), |
82 |
'description' => t('The quality of the presentation and atmosphere at a restaurant.'), |
83 |
'module' => 'mymodule', |
84 |
); |
85 |
|
86 |
// Document two custom aggregate function.
|
87 |
$data['functions']['standard_deviation'] = array( |
88 |
'name' => t('Standard deviation'), |
89 |
'description' => t('The standard deviation of all votes cast on a given piece of content. Use this to find controversial content.'), |
90 |
'module' => 'mymodule', |
91 |
); |
92 |
$data['functions']['median'] = array( |
93 |
'name' => t('Median vote'), |
94 |
'description' => t('The median vote value cast on a given piece of content. More accurate than a pure average when there are a few outlying votes.'), |
95 |
'module' => 'mymodule', |
96 |
); |
97 |
} |
98 |
|
99 |
/**
|
100 |
* Returns callback functions and descriptions to format a VotingAPI Views
|
101 |
* field.
|
102 |
*
|
103 |
* Loads all votes for a given piece of content, then calculates and caches the
|
104 |
* aggregate vote results. This is only intended for modules that have assumed
|
105 |
* responsibility for the full voting cycle: the votingapi_set_vote() function
|
106 |
* recalculates automatically.
|
107 |
*
|
108 |
* @param object $field
|
109 |
* A Views field object. This can be used to expose formatters only for tags,
|
110 |
* vote values, aggregate functions, etc.
|
111 |
*
|
112 |
* @return array
|
113 |
* An array of key-value pairs, in which each key is a callback function and
|
114 |
* each value is a human-readable description of the formatter.
|
115 |
*
|
116 |
* @see votingapi_set_votes()
|
117 |
*/
|
118 |
function hook_votingapi_views_formatters($field) { |
119 |
if ($field->field == 'value') { |
120 |
return array('mymodule_funky_formatter' => t('MyModule value formatter')); |
121 |
} |
122 |
if ($field->field == 'tag') { |
123 |
return array('mymodule_funky_tags' => t('MyModule tag formatter')); |
124 |
} |
125 |
} |
126 |
|
127 |
/**
|
128 |
* Save a vote in the database.
|
129 |
*
|
130 |
* @param $vote
|
131 |
* See votingapi_add_votes() for the structure of this array, with the
|
132 |
* defaults loaded from votingapi_prep_vote().
|
133 |
*/
|
134 |
function hook_votingapi_storage_add_vote(&$vote) { |
135 |
_mongodb_votingapi_prepare_vote($criteria);
|
136 |
mongodb_collection('votingapi_vote')->insert($vote); |
137 |
} |
138 |
|
139 |
/**
|
140 |
* Delete votes from the database.
|
141 |
*
|
142 |
* @param $votes
|
143 |
* An array of votes to delete. Minimally, each vote must have the 'vote_id'
|
144 |
* key set.
|
145 |
* @param $vids
|
146 |
* A list of the 'vote_id' values from $voes.
|
147 |
*/
|
148 |
function hook_votingapi_storage_delete_votes($votes, $vids) { |
149 |
mongodb_collection('votingapi_vote')->delete(array('vote_id' => array('$in' => array_map('intval', $vids)))); |
150 |
} |
151 |
|
152 |
/**
|
153 |
* Select invidual votes from the database
|
154 |
*
|
155 |
* @param array $criteria
|
156 |
* A keyed array used to build the select query. Keys can contain
|
157 |
* a single value or an array of values to be matched.
|
158 |
* $criteria['vote_id'] (If this is set, all other keys are skipped)
|
159 |
* $criteria['entity_id']
|
160 |
* $criteria['entity_type']
|
161 |
* $criteria['value_type']
|
162 |
* $criteria['tag']
|
163 |
* $criteria['uid']
|
164 |
* $criteria['vote_source']
|
165 |
* $criteria['timestamp'] If this is set, records with timestamps
|
166 |
* GREATER THAN the set value will be selected. Defaults to
|
167 |
* REQUEST_TIME - variable_get('votingapi_anonymous_window', 3600); if
|
168 |
* the anonymous window is above zero.
|
169 |
* @param int $limit
|
170 |
* An integer specifying the maximum number of votes to return. 0 means
|
171 |
* unlimited and is the default.
|
172 |
*
|
173 |
* @return array
|
174 |
* An array of votes matching the criteria.
|
175 |
*/
|
176 |
function hook_votingapi_storage_select_votes($criteria, $limit) { |
177 |
_mongodb_votingapi_prepare_vote($criteria);
|
178 |
$find = array(); |
179 |
foreach ($criteria as $key => $value) { |
180 |
$find[$key] = is_array($value) ? array('$in' => $value) : $value; |
181 |
} |
182 |
$cursor = mongodb_collection('votingapi_vote')->find($find); |
183 |
if (!empty($limit)) { |
184 |
$cursor->limit($limit); |
185 |
} |
186 |
$votes = array(); |
187 |
foreach ($cursor as $vote) { |
188 |
$votes[] = $vote; |
189 |
} |
190 |
return $votes; |
191 |
} |
192 |
|
193 |
/**
|
194 |
* Allows to act on votes before being inserted.
|
195 |
*
|
196 |
* @param $votes
|
197 |
* An array of votes, each with the following structure:
|
198 |
* $vote['entity_type'] (Optional, defaults to 'node')
|
199 |
* $vote['entity_id'] (Required)
|
200 |
* $vote['value_type'] (Optional, defaults to 'percent')
|
201 |
* $vote['value'] (Required)
|
202 |
* $vote['tag'] (Optional, defaults to 'vote')
|
203 |
* $vote['uid'] (Optional, defaults to current user)
|
204 |
* $vote['vote_source'] (Optional, defaults to current IP)
|
205 |
* $vote['timestamp'] (Optional, defaults to REQUEST_TIME)
|
206 |
*/
|
207 |
function hook_votingapi_preset_votes(&$votes) { |
208 |
foreach ($votes as $vote) { |
209 |
if ($vote['tag'] == 'recommend') { |
210 |
// Do something if the 'recommend' vote is being inserted.
|
211 |
} |
212 |
} |
213 |
} |
214 |
|
215 |
/**
|
216 |
* TODO
|
217 |
*
|
218 |
*/
|
219 |
function hook_votingapi_storage_standard_results($entity_id, $entity) { |
220 |
// TODO
|
221 |
} |