root / drupal7 / sites / all / modules / file_entity / file_entity.api.php @ 9a28ac3f
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 |
} |