root / drupal7 / sites / all / modules / votingapi / votingapi.api.php @ fcc9430f
1 | 85ad3d82 | Assos Assos | <?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 | fcc9430f | Assos Assos | * 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 | 85ad3d82 | Assos Assos | *
|
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 | fcc9430f | Assos Assos | * piece of content, a catch-all "vote" value should still be calculated for
|
21 | * use
|
||
22 | 85ad3d82 | Assos Assos | * 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 | fcc9430f | Assos Assos | $sql = "SELECT v.tag, STDDEV(v.value) as standard_deviation "; |
39 | 85ad3d82 | Assos Assos | $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 | fcc9430f | Assos Assos | * Adds to or alters metadata describing Voting tags, value_types, and
|
56 | * functions.
|
||
57 | 85ad3d82 | Assos Assos | *
|
58 | fcc9430f | Assos Assos | * 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 | 85ad3d82 | Assos Assos | *
|
62 | * Three major bins of data are stored: tags, value_types, and aggregate result
|
||
63 | fcc9430f | Assos Assos | * 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 | 85ad3d82 | Assos Assos | * '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 | fcc9430f | Assos Assos | 'module' => 'mymodule', |
78 | // This is optional; we can add it for our own purposes.
|
||
79 | 85ad3d82 | Assos Assos | ); |
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 | fcc9430f | Assos Assos | * Returns callback functions and descriptions to format a VotingAPI Views
|
101 | * field.
|
||
102 | 85ad3d82 | Assos Assos | *
|
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 | fcc9430f | Assos Assos | * @param object $field
|
109 | 85ad3d82 | Assos Assos | * A Views field object. This can be used to expose formatters only for tags,
|
110 | * vote values, aggregate functions, etc.
|
||
111 | fcc9430f | Assos Assos | *
|
112 | * @return array
|
||
113 | 85ad3d82 | Assos Assos | * 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 | fcc9430f | Assos Assos | * @param array $criteria
|
156 | 85ad3d82 | Assos Assos | * 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 | fcc9430f | Assos Assos | * @param int $limit
|
170 | 85ad3d82 | Assos Assos | * An integer specifying the maximum number of votes to return. 0 means
|
171 | * unlimited and is the default.
|
||
172 | fcc9430f | Assos Assos | *
|
173 | * @return array
|
||
174 | 85ad3d82 | Assos Assos | * 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 | 7942932f | Assos Assos | /**
|
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 | 85ad3d82 | Assos Assos | /**
|
216 | * TODO
|
||
217 | *
|
||
218 | */
|
||
219 | function hook_votingapi_storage_standard_results($entity_id, $entity) { |
||
220 | // TODO
|
||
221 | } |