Project

General

Profile

Paste
Download (10.6 KB) Statistics
| Branch: | Revision:

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
}