Skip to content
GitLab
Menu
Projects
Groups
Snippets
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Sign in
Toggle navigation
Menu
Open sidebar
project
drupal
Commits
d91203fe
Commit
d91203fe
authored
Dec 05, 2011
by
catch
Browse files
Issue
#1347890
by sven.lauer: Clean up API docs for file module.
parent
f28b98cb
Changes
6
Hide whitespace changes
Inline
Side-by-side
core/modules/file/file.admin.css
View file @
d91203fe
/**
* @file
* Admin styles for file module.
* Admin styles
heet
for file module.
*/
/**
...
...
core/modules/file/file.api.php
View file @
d91203fe
...
...
@@ -55,8 +55,8 @@ function hook_file_download_access($field, $entity_type, $entity) {
* @return
* An array of grants, keyed by module name, each with a Boolean grant value.
* Return an empty array to assert FALSE. You may choose to return your own
* module's value in addition to other grants or to overwrite the values set
by
* other modules.
* module's value in addition to other grants or to overwrite the values set
*
by
other modules.
*/
function
hook_file_download_access_alter
(
&
$grants
,
$field
,
$entity_type
,
$entity
)
{
// For our example module, we always enforce the rules set by node module.
...
...
core/modules/file/file.field.inc
View file @
d91203fe
...
...
@@ -120,9 +120,13 @@ function file_field_instance_settings_form($field, $instance) {
}
/**
*
Element validate callback for
the maximum upload size field.
*
Render API callback: Validates
the maximum uplo
d
ad size field.
*
* Ensure a size that can be parsed by parse_size() has been entered.
* Ensures that a size has been entered and that it can be parsed by
* parse_size().
*
* This function is assigned as an #element_validate callback in
* file_field_instance_settings_form().
*/
function
_file_generic_settings_max_filesize
(
$element
,
&
$form_state
)
{
if
(
!
empty
(
$element
[
'#value'
])
&&
!
is_numeric
(
parse_size
(
$element
[
'#value'
])))
{
...
...
@@ -131,7 +135,10 @@ function _file_generic_settings_max_filesize($element, &$form_state) {
}
/**
* Element validate callback for the allowed file extensions field.
* Render API callback: Validates the allowed file extensions field.
*
* This function is assigned as an #element_validate callback in
* file_field_instance_settings_form().
*
* This doubles as a convenience clean-up function and a validation routine.
* Commas are allowed by the end-user, but ultimately the value will be stored
...
...
@@ -152,10 +159,14 @@ function _file_generic_settings_extensions($element, &$form_state) {
}
/**
* Element validate callback for the file destination field.
* Render API callback: Validates the file destination field.
*
* Removes slashes from the beginning and end of the destination value and
* ensures that the file directory path is not included at the beginning of the
* value.
*
*
Remove slashes from the beginning and end of the destination value and ensure
*
that the file directory path is not included at the beginning of the value
.
*
This function is assigned as an #element_validate callback in
*
file_field_instance_settings_form()
.
*/
function
_file_generic_settings_file_directory_validate
(
$element
,
&
$form_state
)
{
// Strip slashes from the beginning and end of $widget['file_directory'].
...
...
@@ -312,7 +323,7 @@ function file_field_delete_revision($entity_type, $entity, $field, $instance, $l
}
/**
* Decrements
a fil
e usage count and attempts to delete it.
* Decrements
th
e usage count
for a file
and attempts to delete it.
*
* This function only has an effect if the file being deleted is used only by
* File module.
...
...
@@ -358,12 +369,13 @@ function file_field_is_empty($item, $field) {
}
/**
* Determine whether a file should be displayed when outputting field content.
* Determine
s
whether a file should be displayed when outputting field content.
*
* @param $item
* A field item array.
* @param $field
* A field array.
*
* @return
* Boolean TRUE if the file will be displayed, FALSE if the file is hidden.
*/
...
...
@@ -516,10 +528,11 @@ function file_field_widget_form(&$form, &$form_state, $field, $instance, $langco
}
/**
*
G
et the upload validators for a file field.
*
R
et
rieves
the upload validators for a file field.
*
* @param $field
* A field array.
*
* @return
* An array suitable for passing to file_save_upload() or the file field
* element's '#upload_validators' property.
...
...
@@ -545,7 +558,7 @@ function file_field_widget_upload_validators($field, $instance) {
}
/**
* Determine the URI for a file field instance.
* Determine
s
the URI for a file field instance.
*
* @param $field
* A field array.
...
...
@@ -553,6 +566,7 @@ function file_field_widget_upload_validators($field, $instance) {
* A field instance array.
* @param $data
* An array of token objects to pass to token_replace().
*
* @return
* A file directory URI with tokens replaced.
*
...
...
@@ -568,7 +582,9 @@ function file_field_widget_uri($field, $instance, $data = array()) {
}
/**
* The #value_callback for the file_generic field element.
* Render API callback: Retrieves the value for the file_generic field element.
*
* This function is assigned as a #value callback in file_field_widget_form().
*/
function
file_field_widget_value
(
$element
,
$input
=
FALSE
,
$form_state
)
{
if
(
$input
)
{
...
...
@@ -594,9 +610,11 @@ function file_field_widget_value($element, $input = FALSE, $form_state) {
}
/**
*
An element #process callback for the
file_generic field
type
.
*
Render API callback: Processes a
file_generic field
element
.
*
* Expands the file_generic type to include the description and display fields.
*
* This function is assigned as a #process callback in file_field_widget_form().
*/
function
file_field_widget_process
(
$element
,
&
$form_state
,
$form
)
{
$item
=
$element
[
'#value'
];
...
...
@@ -665,10 +683,12 @@ function file_field_widget_process($element, &$form_state, $form) {
}
/**
*
An element #process callback for
a group of file_generic fields.
*
Render API callback: Processes
a group of file_generic field
element
s.
*
* Adds the weight field to each row so it can be ordered and adds a new Ajax
* wrapper around the entire group so it can be replaced all at once.
*
* This function is assigned as a #process callback in file_field_widget_form().
*/
function
file_field_widget_process_multiple
(
$element
,
&
$form_state
,
$form
)
{
$element_children
=
element_children
(
$element
,
TRUE
);
...
...
@@ -704,10 +724,13 @@ function file_field_widget_process_multiple($element, &$form_state, $form) {
}
/**
* Helper function for file_field_widget_process_multiple().
* Retrieves the file description from a field field element.
*
* This helper function is used by file_field_widget_process_multiple().
*
* @param $element
* The element being processed.
*
* @return
* A description of the file suitable for use in the administrative interface.
*/
...
...
@@ -725,7 +748,7 @@ function _file_field_get_description_from_element($element) {
}
/**
*
Submit
handler for upload
and
remove button
s
of file_
generic fields
.
*
Form submission
handler for upload
/
remove button of file_
field_widget_form()
.
*
* This runs in addition to and after file_managed_file_submit().
*
...
...
core/modules/file/file.module
View file @
d91203fe
...
...
@@ -56,7 +56,7 @@ function file_menu() {
/**
* Implements hook_element_info().
*
* The managed file element may be used
independently
anywhere in Drupal.
* The managed file element may be used anywhere in Drupal.
*/
function
file_element_info
()
{
$file_path
=
drupal_get_path
(
'module'
,
'file'
);
...
...
@@ -223,12 +223,16 @@ function file_file_download($uri, $field_type = 'file') {
}
/**
* Menu callback; Shared Ajax callback for file uploads and deletions.
* Ajax callback: Processes file uploads and deletions.
*
* Path: file/ajax
*
* This rebuilds the form element for a particular field item. As long as the
* form processing is properly encapsulated in the widget element the form
* should rebuild correctly using FAPI without the need for additional callbacks
* or processing.
*
* @see file_menu()
*/
function
file_ajax_upload
()
{
$form_parents
=
func_get_args
();
...
...
@@ -286,7 +290,9 @@ function file_ajax_upload() {
}
/**
* Menu callback for upload progress.
* Ajax callback: Retrieves upload progress.
*
* Path: file/progress
*
* @param $key
* The unique key for this upload process.
...
...
@@ -317,7 +323,7 @@ function file_ajax_progress($key) {
}
/**
* Determine the preferred upload progress implementation.
* Determine
s
the preferred upload progress implementation.
*
* @return
* A string indicating which upload progress system is available. Either "apc"
...
...
@@ -348,10 +354,12 @@ function file_file_delete($file) {
}
/**
*
Process function to e
xpand the managed_file element type.
*
Render API callback: E
xpand
s
the managed_file element type.
*
* Expands the file type to include Upload and Remove buttons, as well as
* support for a default value.
*
* This function is assigned as a #process callback in file_element_info().
*/
function
file_managed_file_process
(
$element
,
&
$form_state
,
$form
)
{
$fid
=
isset
(
$element
[
'#value'
][
'fid'
])
?
$element
[
'#value'
][
'fid'
]
:
0
;
...
...
@@ -471,7 +479,9 @@ function file_managed_file_process($element, &$form_state, $form) {
}
/**
* The #value_callback for a managed_file type element.
* Render API callback: Determines the value for a managed_file type element.
*
* This function is assigned as a #value_callback in file_element_info().
*/
function
file_managed_file_value
(
&
$element
,
$input
=
FALSE
,
$form_state
=
NULL
)
{
$fid
=
0
;
...
...
@@ -537,7 +547,10 @@ function file_managed_file_value(&$element, $input = FALSE, $form_state = NULL)
}
/**
* An #element_validate callback for the managed_file element.
* Render API callback: Validates the managed_file element.
*
* This function is assigned as a #element_validate callback in
* file_element_info().
*/
function
file_managed_file_validate
(
&
$element
,
&
$form_state
)
{
// If referencing an existing file, only allow if there are existing
...
...
@@ -570,7 +583,9 @@ function file_managed_file_validate(&$element, &$form_state) {
}
/**
* Submit handler for upload and remove buttons of managed_file elements.
* Form submission handler for upload / remove buttons of managed_file elements.
*
* @see file_managed_file_process()
*/
function
file_managed_file_submit
(
$form
,
&
$form_state
)
{
// Determine whether it was the upload or the remove button that was clicked,
...
...
@@ -611,10 +626,11 @@ function file_managed_file_submit($form, &$form_state) {
}
/**
*
Given a managed_file element, save
any files that have been uploaded into
i
t.
*
Saves
any files that have been uploaded into
a managed_file elemen
t.
*
* @param $element
* The FAPI element whose values are being saved.
*
* @return
* The file object representing the file that was saved, or FALSE if no file
* was saved.
...
...
@@ -671,7 +687,7 @@ function theme_file_managed_file($variables) {
}
/**
*
#pre_r
ender callback
to h
ide display of the upload or remove controls.
*
R
ender
API
callback
: H
ide
s
display of the upload or remove controls.
*
* Upload controls are hidden when a file is already uploaded. Remove controls
* are hidden when there is no file attached. Controls are hidden here instead
...
...
@@ -686,6 +702,8 @@ function theme_file_managed_file($variables) {
* assume that the buttons can't be "clicked" just because they are not
* displayed.
*
* This function is assigned as a #pre_render callback in file_element_info().
*
* @see file_managed_file_process()
* @see form_builder()
*/
...
...
@@ -761,13 +779,14 @@ function theme_file_icon($variables) {
}
/**
*
Given a file object, c
reate a URL to
a matching icon
.
*
C
reate
s
a URL to
the icon for a file object
.
*
* @param $file
* A file object.
* @param $icon_directory
* (optional) A path to a directory of icons to be used for files. Defaults to
* the value of the "file_icon_directory" variable.
*
* @return
* A URL string to the icon, or FALSE if an appropriate icon cannot be found.
*/
...
...
@@ -779,13 +798,14 @@ function file_icon_url($file, $icon_directory = NULL) {
}
/**
*
Given a file object, c
reate a path to
a matching icon
.
*
C
reate
s
a path to
the icon for a file object
.
*
* @param $file
* A file object.
* @param $icon_directory
* (optional) A path to a directory of icons to be used for files. Defaults to
* the value of the "file_icon_directory" variable.
*
* @return
* A string to the icon as a local path, or FALSE if an appropriate icon could
* not be found.
...
...
@@ -831,10 +851,11 @@ function file_icon_path($file, $icon_directory = NULL) {
}
/**
* Determine the generic icon MIME package based on a file's MIME type.
* Determine
s
the generic icon MIME package based on a file's MIME type.
*
* @param $file
* A file object.
*
* @return
* The generic icon MIME package expected for this file.
*/
...
...
@@ -962,7 +983,7 @@ function file_icon_map($file) {
*/
/**
*
G
ets a list of references to a file.
*
R
et
rieve
s a list of references to a file.
*
* @param $file
* A file object.
...
...
core/modules/file/tests/file.test
View file @
d91203fe
...
...
@@ -6,7 +6,7 @@
*/
/**
*
This class p
rovides methods specifically for testing File's field handling.
*
P
rovides methods specifically for testing File
module
's field handling.
*/
class
FileFieldTestCase
extends
DrupalWebTestCase
{
protected
$admin_user
;
...
...
@@ -27,7 +27,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
*
G
et a sample file of the specified type.
*
R
et
rieves
a sample file of the specified type.
*/
function
getTestFile
(
$type_name
,
$size
=
NULL
)
{
// Get a file to upload.
...
...
@@ -40,14 +40,14 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
*
G
et the fid of the last inserted file.
*
R
et
rieves
the fid of the last inserted file.
*/
function
getLastFileId
()
{
return
(
int
)
db_query
(
'SELECT MAX(fid) FROM {file_managed}'
)
->
fetchField
();
}
/**
* Create a new file field.
* Create
s
a new file field.
*
* @param $name
* The name of the new field (all lowercase), exclude the "field_" prefix.
...
...
@@ -74,7 +74,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
* Attach a file field to an entity.
* Attach
es
a file field to an entity.
*
* @param $name
* The name of the new field (all lowercase), exclude the "field_" prefix.
...
...
@@ -108,7 +108,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
* Update an existing file field with new settings.
* Update
s
an existing file field with new settings.
*/
function
updateFileField
(
$name
,
$type_name
,
$instance_settings
=
array
(),
$widget_settings
=
array
())
{
$instance
=
field_info_instance
(
'node'
,
$name
,
$type_name
);
...
...
@@ -119,7 +119,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
* Upload a file to a node.
* Upload
s
a file to a node.
*/
function
uploadNodeFile
(
$file
,
$field_name
,
$nid_or_type
,
$new_revision
=
TRUE
,
$extras
=
array
())
{
$langcode
=
LANGUAGE_NONE
;
...
...
@@ -150,7 +150,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
* Remove a file from a node.
* Remove
s
a file from a node.
*
* Note that if replacing a file, it must first be removed then added again.
*/
...
...
@@ -164,7 +164,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
* Replace a file within a node.
* Replace
s
a file within a node.
*/
function
replaceNodeFile
(
$file
,
$field_name
,
$nid
,
$new_revision
=
TRUE
)
{
$edit
=
array
(
...
...
@@ -177,7 +177,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
* Assert that a file exists physically on disk.
* Assert
s
that a file exists physically on disk.
*/
function
assertFileExists
(
$file
,
$message
=
NULL
)
{
$message
=
isset
(
$message
)
?
$message
:
t
(
'File %file exists on the disk.'
,
array
(
'%file'
=>
$file
->
uri
));
...
...
@@ -185,7 +185,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
* Assert that a file exists in the database.
* Assert
s
that a file exists in the database.
*/
function
assertFileEntryExists
(
$file
,
$message
=
NULL
)
{
entity_get_controller
(
'file'
)
->
resetCache
();
...
...
@@ -195,7 +195,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
* Assert that a file does not exist on disk.
* Assert
s
that a file does not exist on disk.
*/
function
assertFileNotExists
(
$file
,
$message
=
NULL
)
{
$message
=
isset
(
$message
)
?
$message
:
t
(
'File %file exists on the disk.'
,
array
(
'%file'
=>
$file
->
uri
));
...
...
@@ -203,7 +203,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
* Assert that a file does not exist in the database.
* Assert
s
that a file does not exist in the database.
*/
function
assertFileEntryNotExists
(
$file
,
$message
)
{
entity_get_controller
(
'file'
)
->
resetCache
();
...
...
@@ -212,7 +212,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
* Assert that a file's status is set to permanent in the database.
* Assert
s
that a file's status is set to permanent in the database.
*/
function
assertFileIsPermanent
(
$file
,
$message
=
NULL
)
{
$message
=
isset
(
$message
)
?
$message
:
t
(
'File %file is permanent.'
,
array
(
'%file'
=>
$file
->
uri
));
...
...
@@ -221,7 +221,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
}
/**
* Test
class for testing
the 'managed_file' element type
on its own, not as part of a file field
.
* Test
s
the 'managed_file' element type.
*
* @todo Create a FileTestCase base class and move FileFieldTestCase methods
* that aren't related to fields into it.
...
...
@@ -311,7 +311,7 @@ class FileManagedFileElementTestCase extends FileFieldTestCase {
}
/**
* Test
class to test
file field widget
, single and multi-valued, with and without Ajax, with public and private files
.
* Test
s
file field widget.
*/
class
FileFieldWidgetTestCase
extends
FileFieldTestCase
{
public
static
function
getInfo
()
{
...
...
@@ -323,7 +323,7 @@ class FileFieldWidgetTestCase extends FileFieldTestCase {
}
/**
* Tests upload and remove buttons
, with and without Ajax,
for a single-valued File field.
* Tests upload and remove buttons for a single-valued File field.
*/
function
testSingleValuedWidget
()
{
// Use 'page' instead of 'article', so that the 'article' image field does
...
...
@@ -380,7 +380,7 @@ class FileFieldWidgetTestCase extends FileFieldTestCase {
}
/**
* Tests upload and remove buttons
, with and without Ajax,
for multiple multi-valued File field.
* Tests upload and remove buttons for multiple multi-valued File field
s
.
*/
function
testMultiValuedWidget
()
{
// Use 'page' instead of 'article', so that the 'article' image field does
...
...
@@ -616,7 +616,7 @@ class FileFieldWidgetTestCase extends FileFieldTestCase {
}
/**
* Test
class to test
file handling with node revisions.
* Test
s
file handling with node revisions.
*/
class
FileFieldRevisionTestCase
extends
FileFieldTestCase
{
public
static
function
getInfo
()
{
...
...
@@ -628,7 +628,7 @@ class FileFieldRevisionTestCase extends FileFieldTestCase {
}
/**
* Test creating multiple revisions of a node and managing
the
attached files.
* Test
s
creating multiple revisions of a node and managing attached files.
*
* Expected behaviors:
* - Adding a new revision will make another entry in the field table, but
...
...
@@ -731,7 +731,7 @@ class FileFieldRevisionTestCase extends FileFieldTestCase {
}
/**
* Test
class to check
that formatters are working properly.
* Test
s
that formatters are working properly.
*/
class
FileFieldDisplayTestCase
extends
FileFieldTestCase
{
public
static
function
getInfo
()
{
...
...
@@ -743,7 +743,7 @@ class FileFieldDisplayTestCase extends FileFieldTestCase {
}
/**
* Test normal formatter display on node display.
* Test
s
normal formatter display on node display.
*/
function
testNodeDisplay
()
{
$field_name
=
strtolower
(
$this
->
randomName
());
...
...
@@ -782,7 +782,7 @@ class FileFieldDisplayTestCase extends FileFieldTestCase {
}
/**
* Test
class to check for
various validations.
* Test
s
various validations.
*/
class
FileFieldValidateTestCase
extends
FileFieldTestCase
{
protected
$field
;
...
...
@@ -797,7 +797,7 @@ class FileFieldValidateTestCase extends FileFieldTestCase {
}
/**
* Test required property on file fields.
* Test
s the
required property on file fields.
*/
function
testRequired
()
{
$type_name
=
'article'
;
...
...
@@ -845,7 +845,7 @@ class FileFieldValidateTestCase extends FileFieldTestCase {
}
/**
* Test the max file size validator.
* Test
s
the max file size validator.
*/
function
testFileMaxSize
()
{
$type_name
=
'article'
;
...
...
@@ -897,7 +897,7 @@ class FileFieldValidateTestCase extends FileFieldTestCase {
}
/**
* Test
the
file extension
, do additional checks if mimedetect is installed
.
* Test
s
file extension
checking
.
*/
function
testFileExtension
()
{
$type_name
=
'article'
;
...
...
@@ -943,7 +943,7 @@ class FileFieldValidateTestCase extends FileFieldTestCase {
}
/**
* Test
class to check
that files are uploaded to proper locations.
* Test
s
that files are uploaded to proper locations.
*/
class
FileFieldPathTestCase
extends
FileFieldTestCase
{
public
static
function
getInfo
()
{
...
...
@@ -955,7 +955,7 @@ class FileFieldPathTestCase extends FileFieldTestCase {
}
/**
* Test normal formatter display on node display.
* Test
s the
normal formatter display on node display.
*/
function
testUploadPath
()
{
$field_name
=
strtolower
(
$this
->
randomName
());
...
...
@@ -1000,7 +1000,7 @@ class FileFieldPathTestCase extends FileFieldTestCase {
}
/**
* A
loose assertion to check
that a file is uploaded to the right location.
* A
sserts
that a file is uploaded to the right location.
*
* @param $expected_path
* The location where the file is expected to be uploaded. Duplicate file
...
...
@@ -1023,7 +1023,7 @@ class FileFieldPathTestCase extends FileFieldTestCase {
}
/**
* Test file token replacement in strings.
* Test
s the
file token replacement in strings.
*/
class
FileTokenReplaceTestCase
extends
FileFieldTestCase
{
public
static
function
getInfo
()
{
...
...
@@ -1095,7 +1095,7 @@ class FileTokenReplaceTestCase extends FileFieldTestCase {
}
/**
* Test
class to test
file access on private nodes.
* Test
s
file access on private nodes.
*/
class
FilePrivateTestCase
extends
FileFieldTestCase
{
public
static
function
getInfo
()
{
...
...
@@ -1113,7 +1113,7 @@ class FilePrivateTestCase extends FileFieldTestCase {
}
/**
*
Uploads a file to a private node, then tests that access is allowed and denied when appro
priate.
*
Tests file access for file uploaded to a
pri
v
ate
node
.
*/
function
testPrivateFile
()
{
// Use 'page' instead of 'article', so that the 'article' image field does
...
...
core/modules/file/tests/file_module_test.module
View file @
d91203fe
...
...
@@ -22,7 +22,13 @@ function file_module_test_menu() {
}
/**
* Form builder for testing a 'managed_file' element.
* Form constructor for testing a 'managed_file' element.
*
* Path: file/test
*
* @see file_module_test_menu()
* @see file_module_test_form_submit()
* @ingroup forms
*/
function
file_module_test_form
(
$form
,
&
$form_state
,
$tree
=
TRUE
,
$extended
=
FALSE
,
$default_fid
=
NULL
)
{
$form
[
'#tree'
]
=
(
bool
)
$tree
;
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment