Project

General

Profile

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

root / drupal7 / sites / all / modules / file_entity / file_entity.api.php @ 7b2d1845

1
<?php
2

    
3
/**
4
 * @file
5
 * Hooks provided by the File Entity module.
6
 */
7

    
8
/**
9
 * Declare that your module provides default file types.
10
 *
11
 * Your module may already implement this hook for other CTools plugin types.
12
 * If so, copy the body of this function into the existing hook.
13
 */
14
function hook_ctools_plugin_api($owner, $api) {
15
  if ($owner == 'file_entity' && $api == 'file_type') {
16
    return array('version' => 1);
17
  }
18
}
19

    
20
/**
21
 * Define default file types.
22
 *
23
 * File types are implemented as CTools exportables, so modules can alter the
24
 * defaults via hook_file_default_types_alter(), and the administrator can
25
 * save overridden and custom types to the {file_type} database table.
26
 *
27
 * @return array
28
 *   An array whose keys are file type names and whose values are objects
29
 *   representing the file type, with the following key/value pairs:
30
 *   - api_version: The version of this data.
31
 *   - type: The file type name.
32
 *   - label: The human-readable name of the file type.
33
 *   - description: The description of this file type.
34
 *   - mimetypes: An array of mimetypes that this file type will map to.
35
 */
36
function hook_file_default_types() {
37
  return array(
38
    'image' => (object) array(
39
      'api_version' => 1,
40
      'type' => 'image',
41
      'label' => t('Image'),
42
      'description' => t("An <em>Image</em> is a two-dimensional picture that has a similar appearance to some subject, usually a physical object or a person."),
43
      'mimetypes' => array(
44
        'image/*',
45
      ),
46
    ),
47
  );
48
}
49

    
50
/**
51
 * Alter default file types.
52
 *
53
 * @see hook_file_default_types()
54
 */
55
function hook_file_default_types_alter(&$types) {
56
  $types['image']->mimetypes[] = 'image/svg+xml';
57
}
58

    
59
/**
60
 * Define file formatters.
61
 *
62
 * @return array
63
 *   An array whose keys are file formatter names and whose values are arrays
64
 *   describing the formatter.
65
 *
66
 * @todo Document key/value pairs that comprise a formatter.
67
 *
68
 * @see hook_file_formatter_info_alter()
69
 */
70
function hook_file_formatter_info() {
71
  // @todo Add example.
72
}
73

    
74
/**
75
 * Perform alterations on file formatters.
76
 *
77
 * @param array $info
78
 *   Array of information on file formatters exposed by
79
 *   hook_file_formatter_info() implementations.
80
 */
81
function hook_file_formatter_info_alter(array &$info) {
82
  // @todo Add example.
83
}
84

    
85
/**
86
 * @todo Add documentation.
87
 *
88
 * Note: This is not really a hook. The function name is manually specified via
89
 * 'view callback' in hook_file_formatter_info(), with this recommended callback
90
 * name pattern.
91
 */
92
function hook_file_formatter_FORMATTER_view($file, $display, $langcode) {
93
}
94

    
95
/**
96
 * @todo Add documentation.
97
 *
98
 * Note: This is not really a hook. The function name is manually specified via
99
 * 'settings callback' in hook_file_formatter_info(), with this recommended
100
 * callback name pattern.
101
 */
102
function hook_file_formatter_FORMATTER_settings($form, &$form_state, $settings) {
103
}
104

    
105
/**
106
 * @todo Add documentation.
107
 */
108
function hook_file_displays_alter($displays, $file, $view_mode) {
109
}
110

    
111
/**
112
 * @todo Add documentation.
113
 */
114
function hook_file_view($file, $view_mode, $langcode) {
115
}
116

    
117
/**
118
 * @todo Add documentation.
119
 */
120
function hook_file_view_alter($build, $type) {
121
}
122

    
123
/**
124
 * Add mass file operations.
125
 *
126
 * This hook enables modules to inject custom operations into the mass
127
 * operations dropdown found at admin/content/file, by associating a callback
128
 * function with the operation, which is called when the form is submitted. The
129
 * callback function receives one initial argument, which is an array of the
130
 * checked files.
131
 *
132
 * @return array
133
 *   An array of operations. Each operation is an associative array that may
134
 *   contain the following key-value pairs:
135
 *   - 'label': Required. The label for the operation, displayed in the dropdown
136
 *     menu.
137
 *   - 'callback': Required. The function to call for the operation.
138
 *   - 'callback arguments': Optional. An array of additional arguments to pass
139
 *     to the callback function.
140
 */
141
function hook_file_operations() {
142
  $operations = array(
143
    'delete' => array(
144
      'label' => t('Delete selected files'),
145
      'callback' => NULL,
146
    ),
147
  );
148
  return $operations;
149
}
150

    
151
/**
152
 * Control access to a file.
153
 *
154
 * Modules may implement this hook if they want to have a say in whether or not
155
 * a given user has access to perform a given operation on a file.
156
 *
157
 * The administrative account (user ID #1) always passes any access check,
158
 * so this hook is not called in that case. Users with the "bypass file access"
159
 * permission may always view and edit files through the administrative
160
 * interface.
161
 *
162
 * Note that not all modules will want to influence access on all
163
 * file types. If your module does not want to actively grant or
164
 * block access, return FILE_ENTITY_ACCESS_IGNORE or simply return nothing.
165
 * Blindly returning FALSE will break other file access modules.
166
 *
167
 * @param string $op
168
 *   The operation to be performed. Possible values:
169
 *   - "create"
170
 *   - "delete"
171
 *   - "update"
172
 *   - "view"
173
 *   - "download".
174
 * @param object $file
175
 *   The file on which the operation is to be performed, or, if it does
176
 *   not yet exist, the type of file to be created.
177
 * @param object $account
178
 *   A user object representing the user for whom the operation is to be
179
 *   performed.
180
 *
181
 * @return string|null
182
 *   FILE_ENTITY_ACCESS_ALLOW if the operation is to be allowed;
183
 *   FILE_ENTITY_ACCESS_DENY if the operation is to be denied;
184
 *   FILE_ENTITY_ACCESS_IGNORE to not affect this operation at all.
185
 *
186
 * @ingroup file_entity_access
187
 */
188
function hook_file_entity_access($op, $file, $account) {
189
  $type = is_string($file) ? $file : $file->type;
190

    
191
  if ($op !== 'create' && (REQUEST_TIME - $file->timestamp) < 3600) {
192
    // If the file was uploaded in the last hour, deny access to it.
193
    return FILE_ENTITY_ACCESS_DENY;
194
  }
195

    
196
  // Returning nothing from this function would have the same effect.
197
  return FILE_ENTITY_ACCESS_IGNORE;
198
}
199

    
200
/**
201
 * Control access to listings of files.
202
 *
203
 * @param object $query
204
 *   A query object describing the composite parts of a SQL query related to
205
 *   listing files.
206
 *
207
 * @see hook_query_TAG_alter()
208
 * @ingroup file_entity_access
209
 */
210
function hook_query_file_entity_access_alter(QueryAlterableInterface $query) {
211
  // Only show files that have been uploaded more than an hour ago.
212
  $query->condition('timestamp', REQUEST_TIME - 3600, '<=');
213
}
214

    
215
/**
216
 * Act on a file being displayed as a search result.
217
 *
218
 * This hook is invoked from file_entity_search_execute(), after file_load()
219
 * and file_view() have been called.
220
 *
221
 * @param object $file
222
 *   The file being displayed in a search result.
223
 *
224
 * @return array
225
 *   Extra information to be displayed with search result. This information
226
 *   should be presented as an associative array. It will be concatenated
227
 *   with the file information (filename) in the default search result theming.
228
 *
229
 * @see template_preprocess_search_result()
230
 * @see search-result.tpl.php
231
 *
232
 * @ingroup file_entity_api_hooks
233
 */
234
function hook_file_entity_search_result($file) {
235
  $file_usage_count = db_query('SELECT count FROM {file_usage} WHERE fid = :fid', array('fid' => $file->fid))->fetchField();
236
  return array(
237
    'file_usage_count' => format_plural($file_usage_count, '1 use', '@count uses'),
238
  );
239
}
240

    
241
/**
242
 * Act on a file being indexed for searching.
243
 *
244
 * This hook is invoked during search indexing, after file_load(), and after
245
 * the result of file_view() is added as $file->rendered to the file object.
246
 *
247
 * @param object $file
248
 *   The file being indexed.
249
 *
250
 * @return string
251
 *   Additional file information to be indexed.
252
 *
253
 * @ingroup file_entity_api_hooks
254
 */
255
function hook_file_update_index($file) {
256
  $text = '';
257
  $uses = db_query('SELECT module, count FROM {file_usage} WHERE fid = :fid', array(':fid' => $file->fid));
258
  foreach ($uses as $use) {
259
    $text .= '<h2>' . check_plain($use->module) . '</h2>' . check_plain($use->count);
260
  }
261
  return $text;
262
}
263

    
264
/**
265
 * Provide additional methods of scoring for core search results for files.
266
 *
267
 * A file's search score is used to rank it among other files matched by the
268
 * search, with the highest-ranked files appearing first in the search listing.
269
 *
270
 * For example, a module allowing users to vote on files could expose an
271
 * option to allow search results' rankings to be influenced by the average
272
 * voting score of a file.
273
 *
274
 * All scoring mechanisms are provided as options to site administrators, and
275
 * may be tweaked based on individual sites or disabled altogether if they do
276
 * not make sense. Individual scoring mechanisms, if enabled, are assigned a
277
 * weight from 1 to 10. The weight represents the factor of magnification of
278
 * the ranking mechanism, with higher-weighted ranking mechanisms having more
279
 * influence. In order for the weight system to work, each scoring mechanism
280
 * must return a value between 0 and 1 for every file. That value is then
281
 * multiplied by the administrator-assigned weight for the ranking mechanism,
282
 * and then the weighted scores from all ranking mechanisms are added, which
283
 * brings about the same result as a weighted average.
284
 *
285
 * @return array
286
 *   An associative array of ranking data. The keys should be strings,
287
 *   corresponding to the internal name of the ranking mechanism, such as
288
 *   'recent', or 'usage'. The values should be arrays themselves, with the
289
 *   following keys available:
290
 *   - "title": the human readable name of the ranking mechanism. Required.
291
 *   - "join": part of a query string to join to any additional necessary
292
 *     table. This is not necessary if the table required is already joined to
293
 *     by the base query, such as for the {file_managed} table. Other tables
294
 *     should use the full table name as an alias to avoid naming collisions.
295
 *     Optional.
296
 *   - "score": part of a query string to calculate the score for the ranking
297
 *     mechanism based on values in the database. This does not need to be
298
 *     wrapped in parentheses, as it will be done automatically; it also does
299
 *     not need to take the weighted system into account, as it will be done
300
 *     automatically. It does, however, need to calculate a decimal between
301
 *     0 and 1; be careful not to cast the entire score to an integer by
302
 *     inadvertently introducing a variable argument. Required.
303
 *   - "arguments": if any arguments are required for the score, they can be
304
 *     specified in an array here.
305
 *
306
 * @ingroup file_entity_api_hooks
307
 */
308
function hook_file_ranking() {
309
  // If voting is disabled, we can avoid returning the array, no hard feelings.
310
  if (variable_get('vote_file_enabled', TRUE)) {
311
    return array(
312
      'vote_average' => array(
313
        'title' => t('Average vote'),
314
        // Note that we use i.sid, the search index's search item id, rather
315
        // than fm.fid.
316
        'join' => 'LEFT JOIN {vote_file_data} vote_file_data ON vote_file_data.fid = i.sid',
317
        // The highest possible score should be 1,
318
        // and the lowest possible score, always 0, should be 0.
319
        'score' => 'vote_file_data.average / CAST(%f AS DECIMAL)',
320
        // Pass in the highest possible voting score as a decimal argument.
321
        'arguments' => array(variable_get('vote_score_max', 5)),
322
      ),
323
    );
324
  }
325
}
326

    
327
/**
328
 * Alter file download headers.
329
 *
330
 * @param array $headers
331
 *   Array of download headers.
332
 * @param object $file
333
 *   File object.
334
 */
335
function hook_file_download_headers_alter(array &$headers, $file) {
336
  // Instead of being powered by PHP, tell the world this resource was powered
337
  // by your custom module!
338
  $headers['X-Powered-By'] = 'My Module';
339
}
340

    
341
/**
342
 * React to a file being downloaded.
343
 */
344
function hook_file_transfer($uri, array $headers) {
345
  // Redirect a download for an S3 file to the actual location.
346
  if (file_uri_scheme($uri) == 's3') {
347
    $url = file_create_url($uri);
348
    drupal_goto($url);
349
  }
350
}
351

    
352
/**
353
 * Decides which file type (bundle) should be assigned to a file entity.
354
 *
355
 * @param object $file
356
 *   File object.
357
 *
358
 * @return array
359
 *   Array of file type machine names that can be assigned to a given file type.
360
 *   If there are more proposed file types the one, that was returned the first,
361
 *   wil be chosen. This can be, however, changed in alter hook.
362
 *
363
 * @see hook_file_type_alter()
364
 */
365
function hook_file_type($file) {
366
  // Assign all files uploaded by anonymous users to a special file type.
367
  if (user_is_anonymous()) {
368
    return array('untrusted_files');
369
  }
370
}
371

    
372
/**
373
 * Alters list of file types that can be assigned to a file.
374
 *
375
 * @param array $types
376
 *   List of proposed types.
377
 * @param object $file
378
 *   File object.
379
 */
380
function hook_file_type_alter(array &$types, $file) {
381
  // Choose a specific, non-first, file type.
382
  $types = array($types[4]);
383
}
384

    
385
/**
386
 * Provides metadata information.
387
 *
388
 * @todo Add documentation.
389
 *
390
 * @return array
391
 *   An array of metadata information.
392
 */
393
function hook_file_metadata_info() {
394

    
395
}
396

    
397
/**
398
 * Alters metadata information.
399
 *
400
 * @todo Add documentation.
401
 *
402
 * @return array
403
 *   an array of metadata information.
404
 */
405
function hook_file_metadata_info_alter() {
406

    
407
}
408

    
409
/**
410
 * Alters skip fields status.
411
 *
412
 * Use this to choose to skip or complete step 4 of the file upload process.
413
 *
414
 * @param bool &$skip_fields
415
 *   Set to TRUE to skip the form for editing extra file entity fields.
416
 * @param array $form_state
417
 *   State array of the current upload form.
418
 */
419
function hook_file_entity_file_upload_skip_fields_alter(&$skip_fields, $form_state) {
420
  if ($form_state['file']->type == 'video') {
421
    $skip_fields = TRUE;
422
  }
423
}