root / drupal7 / sites / all / modules / flag / flag.api.php @ 4cfd8be6
1 |
<?php
|
---|---|
2 |
|
3 |
/**
|
4 |
* @file
|
5 |
* Hooks provided by the Flag module.
|
6 |
*/
|
7 |
|
8 |
/**
|
9 |
* @addtogroup hooks
|
10 |
* @{
|
11 |
*/
|
12 |
|
13 |
/**
|
14 |
* Define one or more flag types.
|
15 |
*
|
16 |
* This hook may be placed in a $module.flag.inc file.
|
17 |
*
|
18 |
* @return
|
19 |
* An array whose keys are flag type names and whose values are properties of
|
20 |
* the flag type.
|
21 |
* When a flag type is for an entity, the flag type name must match the entity
|
22 |
* type.
|
23 |
* Properties for flag types are as follows:
|
24 |
* - 'title': The main label of the flag type.
|
25 |
* - 'description': A longer description shown in the UI when creating a new
|
26 |
* flag.
|
27 |
* - 'handler': The name of the class implementing this flag type.
|
28 |
* - 'module': (optional) The name of the module that should be registered as a
|
29 |
* dependency for this flag type.
|
30 |
*
|
31 |
* @see flag_fetch_definition()
|
32 |
*/
|
33 |
function hook_flag_type_info() { |
34 |
return array( |
35 |
'node' => array( |
36 |
'title' => t('Nodes'), |
37 |
'description' => t("Nodes are a Drupal site's primary content."), |
38 |
'handler' => 'flag_node', |
39 |
'module' => 'node', |
40 |
), |
41 |
); |
42 |
} |
43 |
|
44 |
/**
|
45 |
* Alter flag type definitions provided by other modules.
|
46 |
*
|
47 |
* This hook may be placed in a $module.flag.inc file.
|
48 |
*
|
49 |
* @param $definitions
|
50 |
* An array of flag definitions returned by hook_flag_type_info().
|
51 |
*/
|
52 |
function hook_flag_type_info_alter(&$definitions) { |
53 |
|
54 |
} |
55 |
|
56 |
/**
|
57 |
* Define default flags.
|
58 |
*/
|
59 |
function hook_flag_default_flags() { |
60 |
$flags = array(); |
61 |
$flags['bookmarks'] = array( |
62 |
'entity_type' => 'node', |
63 |
'title' => 'Bookmarks', |
64 |
'global' => FALSE, |
65 |
'types' => array( |
66 |
0 => 'article', |
67 |
1 => 'blog', |
68 |
), |
69 |
'flag_short' => 'Bookmark this', |
70 |
'flag_long' => 'Add this post to your bookmarks', |
71 |
'flag_message' => 'This post has been added to your bookmarks', |
72 |
'unflag_short' => 'Unbookmark this', |
73 |
'unflag_long' => 'Remove this post from your bookmarks', |
74 |
'unflag_message' => 'This post has been removed from your bookmarks', |
75 |
'unflag_denied_text' => '', |
76 |
'link_type' => 'toggle', |
77 |
'weight' => 0, |
78 |
'show_in_links' => array( |
79 |
'full' => TRUE, |
80 |
'token' => FALSE, |
81 |
), |
82 |
'show_as_field' => FALSE, |
83 |
'show_on_form' => FALSE, |
84 |
'access_author' => '', |
85 |
'show_contextual_link' => TRUE, |
86 |
'show_on_profile' => FALSE, |
87 |
'access_uid' => '', |
88 |
'api_version' => 3, |
89 |
); |
90 |
return $flags; |
91 |
} |
92 |
|
93 |
/**
|
94 |
* Alter the definition of default flags.
|
95 |
*
|
96 |
* @param array &$flags
|
97 |
* An array keyed by flag machine name containing flag definitions.
|
98 |
*/
|
99 |
function hook_flag_default_flags_alter(&$flags) { |
100 |
if (!empty($flags['bookmark'])) { |
101 |
$flags['bookmark']['title'] = 'Bananana Bookmark'; |
102 |
} |
103 |
} |
104 |
|
105 |
/**
|
106 |
* Allow modules to alter a flag when it is initially loaded.
|
107 |
*
|
108 |
* @see flag_get_flags()
|
109 |
*/
|
110 |
function hook_flag_alter(&$flag) { |
111 |
|
112 |
} |
113 |
|
114 |
/**
|
115 |
* Alter a flag's default options.
|
116 |
*
|
117 |
* Modules that wish to extend flags and provide additional options must declare
|
118 |
* them here so that their additions to the flag admin form are saved into the
|
119 |
* flag object.
|
120 |
*
|
121 |
* @param $options
|
122 |
* The array of default options for the flag type, with the options for the
|
123 |
* flag's link type merged in.
|
124 |
* @param $flag
|
125 |
* The flag object.
|
126 |
*
|
127 |
* @see flag_flag::options()
|
128 |
*/
|
129 |
function hook_flag_options_alter(&$options, $flag) { |
130 |
|
131 |
} |
132 |
|
133 |
/**
|
134 |
* Act on an object being flagged.
|
135 |
*
|
136 |
* @param $flag
|
137 |
* The flag object.
|
138 |
* @param $entity_id
|
139 |
* The id of the entity the flag is on.
|
140 |
* @param $account
|
141 |
* The user account performing the action.
|
142 |
* @param $flagging_id
|
143 |
* The flagging entity.
|
144 |
*/
|
145 |
function hook_flag_flag($flag, $entity_id, $account, $flagging) { |
146 |
|
147 |
} |
148 |
|
149 |
/**
|
150 |
* Act on an object being unflagged.
|
151 |
*
|
152 |
* This is invoked after the flag count has been decreased, but before the
|
153 |
* flagging entity has been deleted.
|
154 |
*
|
155 |
* @param $flag
|
156 |
* The flag object.
|
157 |
* @param $entity_id
|
158 |
* The id of the entity the flag is on.
|
159 |
* @param $account
|
160 |
* The user account performing the action.
|
161 |
* @param $flagging
|
162 |
* The flagging entity.
|
163 |
*/
|
164 |
function hook_flag_unflag($flag, $entity_id, $account, $flagging) { |
165 |
|
166 |
} |
167 |
|
168 |
/**
|
169 |
* Perform custom validation on a flag before flagging/unflagging.
|
170 |
*
|
171 |
* @param $action
|
172 |
* The action about to be carried out. Either 'flag' or 'unflag'.
|
173 |
* @param $flag
|
174 |
* The flag object.
|
175 |
* @param $entity_id
|
176 |
* The id of the entity the user is trying to flag or unflag.
|
177 |
* @param $account
|
178 |
* The user account performing the action.
|
179 |
* @param $flagging
|
180 |
* The flagging entity.
|
181 |
*
|
182 |
* @return
|
183 |
* Optional array: textual error with the error-name as the key.
|
184 |
* If the error name is 'access-denied' and javascript is disabled,
|
185 |
* drupal_access_denied will be called and a 403 will be returned.
|
186 |
* If validation is successful, do not return a value.
|
187 |
*/
|
188 |
function hook_flag_validate($action, $flag, $entity_id, $account, $skip_permission_check, $flagging) { |
189 |
// We're only operating on the "test" flag, and users may always unflag.
|
190 |
if ($flag->name == 'test' && $action == 'flag') { |
191 |
// Get all flags set by the current user.
|
192 |
$flags = flag_get_user_flags('node', NULL, $account->uid, $sid = NULL, $reset = FALSE); |
193 |
// Check if this user has any flags of this type set.
|
194 |
if (isset($flags['test'])) { |
195 |
$count = count($flags[$flag->name]); |
196 |
if ($count >= 2) { |
197 |
// Users may flag only 2 nodes with this flag.
|
198 |
return (array('access-denied' => t('You may only flag 2 nodes with the test flag.'))); |
199 |
} |
200 |
} |
201 |
} |
202 |
} |
203 |
|
204 |
/**
|
205 |
* Allow modules to allow or deny access to flagging for a single entity.
|
206 |
*
|
207 |
* Called when displaying a single entity view or edit page. For flag access
|
208 |
* checks from within Views, implement hook_flag_access_multiple().
|
209 |
*
|
210 |
* @param $flag
|
211 |
* The flag object.
|
212 |
* @param $entity_id
|
213 |
* The id of the entity in question.
|
214 |
* @param $action
|
215 |
* The action to test. Either 'flag' or 'unflag'.
|
216 |
* @param $account
|
217 |
* The user on whose behalf to test the flagging action.
|
218 |
*
|
219 |
* @return
|
220 |
* One of the following values:
|
221 |
* - TRUE: User has access to the flag.
|
222 |
* - FALSE: User does not have access to the flag.
|
223 |
* - NULL: This module does not perform checks on this flag/action.
|
224 |
*
|
225 |
* NOTE: Any module that returns FALSE will prevent the user from
|
226 |
* being able to use the flag.
|
227 |
*
|
228 |
* @see hook_flag_access_multiple()
|
229 |
* @see flag_flag:access()
|
230 |
*/
|
231 |
function hook_flag_access($flag, $entity_id, $action, $account) { |
232 |
|
233 |
} |
234 |
|
235 |
/**
|
236 |
* Allow modules to allow or deny access to flagging for multiple entities.
|
237 |
*
|
238 |
* Called when preparing a View or list of multiple flaggable entities.
|
239 |
* For flag access checks for individual entities, see hook_flag_access().
|
240 |
*
|
241 |
* @param $flag
|
242 |
* The flag object.
|
243 |
* @param $entity_ids
|
244 |
* An array of object ids to check access.
|
245 |
* @param $account
|
246 |
* The user on whose behalf to test the flagging action.
|
247 |
*
|
248 |
* @return
|
249 |
* An array whose keys are the object IDs and values are booleans indicating
|
250 |
* access.
|
251 |
*
|
252 |
* @see hook_flag_access()
|
253 |
* @see flag_flag:access_multiple()
|
254 |
*/
|
255 |
function hook_flag_access_multiple($flag, $entity_ids, $account) { |
256 |
|
257 |
} |
258 |
|
259 |
/**
|
260 |
* Define one or more flag link types.
|
261 |
*
|
262 |
* Link types defined here must be returned by this module's hook_flag_link().
|
263 |
*
|
264 |
* This hook may be placed in a $module.flag.inc file.
|
265 |
*
|
266 |
* @return
|
267 |
* An array of one or more types, keyed by the machine name of the type, and
|
268 |
* where each value is a link type definition as an array with the following
|
269 |
* properties:
|
270 |
* - 'title': The human-readable name of the type.
|
271 |
* - 'description': The description of the link type.
|
272 |
* - 'options': An array of extra options for the link type.
|
273 |
* - 'uses standard js': Boolean, indicates whether the link requires Flag
|
274 |
* module's own JS file for links.
|
275 |
* - 'uses standard css': Boolean, indicates whether the link requires Flag
|
276 |
* module's own CSS file for links.
|
277 |
* - 'provides form': (optional) Boolean indicating that this link type shows
|
278 |
* the user a flagging entity form. This property is used in the UI, eg to
|
279 |
* warn the admin user of link types that are not compatible with other
|
280 |
* flag options. Defaults to FALSE.
|
281 |
*
|
282 |
* @see flag_get_link_types()
|
283 |
* @see hook_flag_link_type_info_alter()
|
284 |
*/
|
285 |
function hook_flag_link_type_info() { |
286 |
|
287 |
} |
288 |
|
289 |
/**
|
290 |
* Alter other modules' definitions of flag link types.
|
291 |
*
|
292 |
* This hook may be placed in a $module.flag.inc file.
|
293 |
*
|
294 |
* @param $link_types
|
295 |
* An array of the link types defined by all modules.
|
296 |
*
|
297 |
* @see flag_get_link_types()
|
298 |
* @see hook_flag_link_type_info()
|
299 |
*/
|
300 |
function hook_flag_link_type_info_alter(&$link_types) { |
301 |
|
302 |
} |
303 |
|
304 |
/**
|
305 |
* Return the link for the link types this module defines.
|
306 |
*
|
307 |
* The type of link to be produced is given by $flag->link_type.
|
308 |
*
|
309 |
* When Flag uses a link type provided by this module, it will call this
|
310 |
* implementation of hook_flag_link(). This should return a single link's
|
311 |
* attributes, using the same structure as hook_link(). Note that "title" is
|
312 |
* provided by the Flag configuration if not specified here.
|
313 |
*
|
314 |
* @param $flag
|
315 |
* The full flag object for the flag link being generated.
|
316 |
* @param $action
|
317 |
* The action this link should perform. Either 'flag' or 'unflag'.
|
318 |
* @param $entity_id
|
319 |
* The ID of the node, comment, user, or other object being flagged. The type
|
320 |
* of the object can be deduced from the flag type.
|
321 |
*
|
322 |
* @return
|
323 |
* An array defining properties of the link.
|
324 |
*
|
325 |
* @see hook_flag_link_type_info()
|
326 |
* @see template_preprocess_flag()
|
327 |
*/
|
328 |
function hook_flag_link() { |
329 |
|
330 |
} |
331 |
|
332 |
/**
|
333 |
* Act on flag deletion.
|
334 |
*
|
335 |
* This is invoked after all the flag database tables have had their relevant
|
336 |
* entries deleted.
|
337 |
*
|
338 |
* @param $flag
|
339 |
* The flag object that has been deleted.
|
340 |
*/
|
341 |
function hook_flag_delete($flag) { |
342 |
|
343 |
} |
344 |
|
345 |
/**
|
346 |
* Act when a flag is reset.
|
347 |
*
|
348 |
* @param $flag
|
349 |
* The flag object.
|
350 |
* @param $entity_id
|
351 |
* The entity ID on which all flaggings are to be removed. May be NULL, in
|
352 |
* which case all of this flag's entities are to be unflagged.
|
353 |
* @param $rows
|
354 |
* Database rows from the {flagging} table.
|
355 |
*
|
356 |
* @see flag_reset_flag()
|
357 |
*/
|
358 |
function hook_flag_reset($flag, $entity_id, $rows) { |
359 |
|
360 |
} |
361 |
|
362 |
/**
|
363 |
* Alter the javascript structure that describes the flag operation.
|
364 |
*
|
365 |
* @param $info
|
366 |
* The info array before it is returned from flag_build_javascript_info().
|
367 |
* @param $flag
|
368 |
* The full flag object.
|
369 |
*
|
370 |
* @see flag_build_javascript_info()
|
371 |
*/
|
372 |
function hook_flag_javascript_info_alter(&$info, $flag) { |
373 |
if ($flag->name === 'test') { |
374 |
$info['newLink'] = $flag->theme($flag->is_flagged($info['contentId']) ? 'unflag' : 'flag', $info['contentId'], array( |
375 |
'after_flagging' => TRUE, |
376 |
'errors' => $flag->get_errors(), |
377 |
// Additional options to pass to theme's preprocess function/template.
|
378 |
'icon' => TRUE, |
379 |
'hide_text' => TRUE, |
380 |
)); |
381 |
} |
382 |
} |
383 |
|
384 |
/**
|
385 |
* Alter a flag object that is being prepared for exporting.
|
386 |
*
|
387 |
* @param $flag
|
388 |
* The flag object.
|
389 |
*
|
390 |
* @see flag_export_flags()
|
391 |
*/
|
392 |
function hook_flag_export_alter($flag) { |
393 |
|
394 |
} |