Commit 87d3e491 authored by quicksketch's avatar quicksketch

Code style cleanup, mostly comments and PHPdoc.

parent dc273ff9
<?php
// $Id$
/**
* @file
* Common functionality for file handling CCK field modules.
*/
/**
* Load a file object from the database.
* Load a file from the database.
*
* @param $fid
* A numeric file id or string containing the file path.
*
* @param $reset
* Whether to reset the internal file_load cache.
* @return
* A file array.
*/
function field_file_load($fid, $reset = NULL) {
// Reset internal cache.
......@@ -44,23 +46,23 @@ function field_file_load($fid, $reset = NULL) {
$function($file);
}
// Cache the fully loaded file for later reusability.
// Cache the fully loaded file for later use.
$files = _field_file_cache($file);
}
// Cast to array for field. hook_file() expects objects as well as
// core file functions.
// Cast to an array for the field storage.
// Contrary to fields, hook_file() and core file functions expect objects.
return (array)$files[$fid];
}
/**
* Save a file upload to a new location. The source file is validated as a
* proper upload and handled as such. By implementing hook_file($op = 'insert'),
* modules are able to act on the file upload and to add their own properties
* to the file.
* Save a file upload to a new location.
* The source file is validated as a proper upload and handled as such. By
* implementing hook_file($op = 'insert'), modules are able to act on the file
* upload and to add their own properties to the file.
*
* The file will be added to the files table as a temporary file. Temporary files
* are periodically cleaned. To make the file permanent file call
* The file will be added to the files table as a temporary file. Temporary
* files are periodically cleaned. To make the file permanent file call
* file_set_status() to change its status.
*
* @param $source
......@@ -110,7 +112,6 @@ function field_file_save_upload($source, $validators = array(), $dest = FALSE) {
* not provided or is not writable, the temporary directory will be used.
* @return
* An array containing the file information, or 0 in the event of an error.
*
*/
function field_file_save_file($filepath, $validators = array(), $dest = FALSE) {
global $user;
......
......@@ -319,8 +319,10 @@ function filefield_widget(&$form, &$form_state, $field, $items, $delta = 0) {
/**
* Get the upload validators for a file field.
*
* @param $field CCK Field
* @return array suitable for passing to file_save_upload() or the filefield
* @param $field
* A CCK field array.
* @return
* An array suitable for passing to file_save_upload() or the file field
* element's '#upload_validators' property.
*/
function filefield_widget_upload_validators($field) {
......@@ -340,12 +342,14 @@ function filefield_widget_upload_validators($field) {
return $validators;
}
/**
* Implementation of CCK's hook_content_is_empty().
*
* The result of this determines whether content.module will save
* the value of the field.
* The result of this determines whether content.module will save the value of
* the field. Note that content module has some interesting behaviors for empty
* values. It will always save at least one record for every node revision,
* even if the values are all NULL. If it is a multi-value field with an
* explicit limit, CCK will save that number of empty entries.
*/
function filefield_content_is_empty($item, $field) {
return empty($item['fid']) || (int)$item['fid'] == 0;
......@@ -405,6 +409,7 @@ function filefield_icon_url($file) {
/**
* Access callback for the JavaScript upload and deletion AHAH callbacks.
*
* The content_permissions module provides nice fine-grained permissions for
* us to check, so we can make sure that the user may actually edit the file.
*/
......@@ -428,10 +433,12 @@ function filefield_view_access($field_name) {
}
/**
* Shared AHAH callback for uploads and deletions... It 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.
* Menu callback; Shared AHAH callback for uploads and deletions.
*
* 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.
*/
function filefield_js($type_name, $field_name, $delta) {
$field = content_fields($field_name, $type_name);
......@@ -535,18 +542,18 @@ function filefield_file_delete($file) {
// foreach field... remove items referencing $file.
}
/**
* Check that the filename ends with an allowed extension. This check is
* enforced for the user #1.
* An #upload_validators callback. Check the file matches an allowed extension.
*
* If the mimedetect module is available, this will also validate that the
* content of the file matches the extension. User #1 is included in this check.
*
* @param $file
* A Drupal file object.
* @param $extensions
* A string with a space separated
* A string with a space separated list of allowed extensions.
* @return
* An array. If the file extension is not allowed, it will contain an error message.
* An array of any errors cause by this file if it failed validation.
*/
function filefield_validate_extensions($file, $extensions) {
global $user;
......@@ -573,9 +580,9 @@ function filefield_validate_extensions($file, $extensions) {
return $errors;
}
// These three functions return messages for file_validate_size, and file_validate_extensions.
// They're a neat hack that gets the job done. Even though it's evil to put a
// function into a namespace not owned by your module...
/**
* Help text automatically appended to fields that have extension validation.
*/
function filefield_validate_extensions_help($extensions) {
if (!empty($extensions)) {
return t('Allowed Extensions: %ext', array('%ext' => $extensions));
......@@ -585,6 +592,19 @@ function filefield_validate_extensions_help($extensions) {
}
}
/**
* An #upload_validators callback. Check the file size does not exceed a limit.
*
* @param $file
* A Drupal file object.
* @param $file_limit
* An integer value limiting the maximum file size in bytes.
* @param $file_limit
* An integer value limiting the maximum size in bytes a user can upload on
* the entire site.
* @return
* An array of any errors cause by this file if it failed validation.
*/
function filefield_validate_size($file, $file_limit = 0, $user_limit = 0) {
global $user;
......@@ -604,10 +624,27 @@ function filefield_validate_size($file, $file_limit = 0, $user_limit = 0) {
return $errors;
}
/**
* Automatic help text appended to fields that have file size validation.
*/
function filefield_validate_size_help($size) {
return t('Maximum Filesize: %size', array('%size' => format_size(parse_size($size))));
}
/**
* An #upload_validators callback. Check an image resolution.
*
* @param $file
* A Drupal file object.
* @param $max_size
* A string in the format WIDTHxHEIGHT. If the image is larger than this size
* the image will be scaled to fit within these dimensions.
* @param $min_size
* A string in the format WIDTHxHEIGHT. If the image is smaller than this size
* a validation error will be returned.
* @return
* An array of any errors cause by this file if it failed validation.
*/
function filefield_validate_image_resolution(&$file, $maximum_dimensions = 0, $minimum_dimensions = 0) {
$errors = array();
......@@ -644,6 +681,9 @@ function filefield_validate_image_resolution(&$file, $maximum_dimensions = 0, $m
return $errors;
}
/**
* Automatic help text appended to fields that have image resolution validation.
*/
function filefield_validate_image_resolution_help($max_size = '0', $min_size = '0') {
if (!empty($max_size)) {
if (!empty($min_size)) {
......@@ -668,6 +708,22 @@ function filefield_validate_image_resolution_help($max_size = '0', $min_size = '
}
}
/**
* An #upload_validators callback. Check that a file is an image.
*
* This check should allow any image that PHP can identify, including png, jpg,
* gif, tif, bmp, psd, swc, iff, jpc, jp2, jpx, jb2, xbm, and wbmp.
*
* This check should be combined with filefield_validate_extensions() to ensure
* only web-based images are allowed, however it provides a better check than
* extension checking alone if the mimedetect module is not available.
*
* @param $file
* A Drupal file object.
* @return
* An array of any errors cause by this file if it failed validation.
*/
function filefield_validate_is_image(&$file) {
$errors = array();
$info = image_get_info($file->filepath);
......@@ -677,9 +733,13 @@ function filefield_validate_is_image(&$file) {
return $errors;
}
/**
* This validation function adds the field to the file object, for later
* use in field aware modules implementing hook_file.
/**
* An #upload_validators callback. Add the field to the file object.
*
* This validation function adds the field to the file object for later
* use in field aware modules implementing hook_file. It's not truly a
* validation at all, rather a convient way to add properties to the uploaded
* file.
*/
function filefield_validate_associate_field(&$file, $field) {
$file->field = $field;
......
<?php
// $Id$
/**
* @file
* FileField: Defines a CCK file field type.
* Theme functions used for normal file output.
*
* Uses content.module to store the fid and field specific metadata,
* and Drupal's {files} table to store the actual file data.
*
* This file contains common theme functions.
*/
/**
......
<?php
// $Id$
/**
* @file
* Token hook implementations. Included if token.module is installed.
*/
/**
* Implementation of hook_token_list().
*
......
......@@ -3,9 +3,12 @@
/**
* @file
* FileField field hooks and callbacks.
* FileField CCK field hooks and callbacks.
*/
/**
* Implementation of CCK's hook_field_settings($op = 'form').
*/
function filefield_field_settings_form($field) {
drupal_add_js(drupal_get_path('module', 'filefield') .'/filefield.js');
......@@ -35,13 +38,16 @@ function filefield_field_settings_form($field) {
return $form;
}
function filefield_field_settings_validate($field) {
}
/**
* Implementation of CCK's hook_field_settings($op = 'save').
*/
function filefield_field_settings_save($field) {
return array('list_field', 'list_default', 'description_field');
}
/**
* Implementation of CCK's hook_field_settings($op = 'database_columns').
*/
function filefield_field_settings_database_columns($field) {
return array(
'fid' => array('type' => 'int', 'not null' => FALSE),
......@@ -50,6 +56,9 @@ function filefield_field_settings_database_columns($field) {
);
}
/**
* Implementation of CCK's hook_field_settings($op = 'views_data').
*/
function filefield_field_settings_views_data($field) {
$data = content_views_field_views_data($field);
$db_info = content_database_info($field);
......@@ -74,10 +83,8 @@ function filefield_field_settings_views_data($field) {
return $data;
}
/**
* Implementation of CCK's hook_field().
* Implementation of CCK's hook_field($op = 'load').
*/
function filefield_field_load($node, $field, &$items, $teaser, $page) {
if (empty($items)) {
......@@ -103,10 +110,16 @@ function filefield_field_load($node, $field, &$items, $teaser, $page) {
return array($field['field_name'] => $items);
}
/**
* Implementation of CCK's hook_field($op = 'insert').
*/
function filefield_field_insert($node, $field, &$items, $teaser, $page) {
return filefield_field_update($node, $field, $items, $teaser, $page);
}
/**
* Implementation of CCK's hook_field($op = 'update').
*/
function filefield_field_update($node, $field, &$items, $teaser, $page) {
// Accumulator to gather current fid to compare with the original node
......@@ -123,8 +136,7 @@ function filefield_field_update($node, $field, &$items, $teaser, $page) {
}
}
// if this is a new node... there are no
// old items to worry about.
// If this is a new node there are no old items to worry about.
if ($node->is_new) {
return;
}
......@@ -143,6 +155,9 @@ function filefield_field_update($node, $field, &$items, $teaser, $page) {
}
}
/**
* Implementation of CCK's hook_field($op = 'delete_revision').
*/
function filefield_field_delete_revision($node, $field, &$items, $teaser, $page) {
foreach ($items as $delta => $item) {
// For hook_file_references, remember that this is being deleted.
......@@ -153,7 +168,9 @@ function filefield_field_delete_revision($node, $field, &$items, $teaser, $page)
}
}
/**
* Implementation of CCK's hook_field($op = 'delete').
*/
function filefield_field_delete($node, $field, &$items, $teaser, $page) {
foreach ($items as $delta => $item) {
// For hook_file_references(), remember that this is being deleted.
......@@ -165,6 +182,9 @@ function filefield_field_delete($node, $field, &$items, $teaser, $page) {
}
}
/**
* Implementation of CCK's hook_field($op = 'sanitize').
*/
function filefield_field_sanitize($node, $field, &$items, $teaser, $page) {
foreach ($items as $delta => $item) {
// Cleanup $items during node preview.
......@@ -204,5 +224,3 @@ function filefield_field_sanitize($node, $field, &$items, $teaser, $page) {
}
}
}
......@@ -67,7 +67,8 @@ function theme_filefield_formatter_url_plain($element) {
}
/**
* Theme function for any file that is managed by filefield.
* Theme function for any file that is managed by FileField.
*
* It doesn't really format stuff by itself but rather redirects to other
* formatters that are telling us they want to handle the concerned file.
*
......@@ -76,11 +77,7 @@ function theme_filefield_formatter_url_plain($element) {
* in any case, please use theme('filefield') instead.
*/
function theme_filefield_item($file, $field) {
if (!filefield_view_access($field['field_name'])) {
return '<!-- you do not have access to view this file -->';
}
if (filefield_file_listed($file, $field)) {
if (filefield_view_access($field['field_name']) && filefield_file_listed($file, $field)) {
return theme('filefield_file', $file);
}
return '';
......
......@@ -12,13 +12,8 @@
*/
/**
* @file
*
* FileField Widget Settings Hooks.
* @todo: move description property to filefield_widget widget callbacks
* (filefield_widget_widget_{$op}).
* Implementation of CCK's hook_widget_settings($op == 'form').
*/
function filefield_widget_settings_form($widget) {
$form = array();
$form['file_extensions'] = array(
......@@ -29,6 +24,7 @@ function filefield_widget_settings_form($widget) {
'#description' => t('Extensions a user can upload to this field. Separate extensions with a space and do not include the leading dot. Leaving this blank will allow users to upload a file with any extension.'),
'#weight' => 1,
);
$form['path_settings'] = array(
'#type' => 'fieldset',
'#title' => t('Path settings'),
......@@ -36,7 +32,6 @@ function filefield_widget_settings_form($widget) {
'#collapsed' => TRUE,
'#weight' => 6,
);
$form['path_settings']['file_path'] = array(
'#type' => 'textfield',
'#title' => t('File path'),
......@@ -54,8 +49,6 @@ function filefield_widget_settings_form($widget) {
'#collapsible' => TRUE,
'#collapsed' => TRUE,
);
// upload validator. @todo: consider replacing with global
// && node validate.
$form['max_filesize']['max_filesize_per_file'] = array(
'#type' => 'textfield',
'#title' => t('Maximum upload size per file'),
......@@ -65,8 +58,6 @@ function filefield_widget_settings_form($widget) {
'#description' => t('Specify the size limit that applies to each file separately. Enter a value like "512" (bytes), "80K" (kilobytes) or "50M" (megabytes) in order to restrict the allowed file size. If you leave this this empty the file sizes will be limited only by PHP\'s maximum post and file upload sizes (current limit <strong>%limit</strong>).', array('%limit' => format_size(file_upload_max_size()))),
'#element_validate' => array('_filefield_widget_settings_max_filesize_per_file_validate'),
);
// node validate.
$form['max_filesize']['max_filesize_per_node'] = array(
'#type' => 'textfield',
'#title' => t('Maximum upload size per node'),
......@@ -76,9 +67,13 @@ function filefield_widget_settings_form($widget) {
'#description' => t('Specify the total size limit for all files in field on a given node. Enter a value like "512" (bytes), "80K" (kilobytes) or "50M" (megabytes) in order to restrict the total size of a node. Leave this empty if there should be no size restriction.'),
'#element_validate' => array('_filefield_widget_settings_max_filesize_per_node_validate'),
);
return $form;
}
/**
* Implementation of CCK's hook_widget_settings($op == 'save').
*/
function filefield_widget_settings_save($widget) {
return array(
'file_extensions', 'file_path', 'max_filesize_per_file',
......@@ -95,8 +90,8 @@ function _filefield_widget_settings_max_filesize_per_file_validate($element, &$f
if (empty($form_state['values']['max_filesize_per_file'])) {
return; // Empty means no size restrictions, so don't throw an error.
}
else if (!is_numeric(parse_size($form_state['values']['max_filesize_per_file']))) {
form_error($element, t('The "Maximum file size for each file" option must contain a valid value. You can either leave the text field empty or enter a string like "512" (bytes), "80K" (kilobytes) or "50M" (megabytes).'));
elseif (!is_numeric(parse_size($form_state['values']['max_filesize_per_file']))) {
form_error($element, t('The "@field" option must contain a valid value. You can either leave the text field empty or enter a string like "512" (bytes), "80K" (kilobytes) or "50M" (megabytes).', array('@field' => t('Maximum upload size per file'))));
}
}
......@@ -104,16 +99,18 @@ function _filefield_widget_settings_max_filesize_per_node_validate($element, &$f
if (empty($form_state['values']['max_filesize_per_node'])) {
return; // Empty means no size restrictions, so don't throw an error.
}
else if (!is_numeric(parse_size($form_state['values']['max_filesize_per_node']))) {
form_error($element, t('The "Maximum file size per node" option must contain a valid value. You can either leave the text field empty or enter a string like "512" (bytes), "80K" (kilobytes) or "50M" (megabytes).'));
elseif (!is_numeric(parse_size($form_state['values']['max_filesize_per_node']))) {
form_error($element, t('The "@field" option must contain a valid value. You can either leave the text field empty or enter a string like "512" (bytes), "80K" (kilobytes) or "50M" (megabytes).', array('@field' => t('Maximum upload size per node'))));
}
}
/**
* Determine the widget's files directory
*
* @param $field CCK field
* @return files directory path.
* @param $field
* A CCK field array.
* @return
* The files directory path, with any tokens replaced.
*/
function filefield_widget_file_path($field_instance) {
$dest = $field_instance['widget']['file_path'];
......@@ -125,6 +122,15 @@ function filefield_widget_file_path($field_instance) {
return file_directory_path() .'/'. $dest;
}
/**
* Given a FAPI element, save any files that may have been uploaded into it.
*
* This function should only be called during validate, submit, or
* value_callback functions.
*
* @param $element
* The FAPI element whose values are being saved.
*/
function filefield_save_upload($element) {
$upload_name = $element['#field_name'] .'_'. $element['#delta'];
$field_instance = content_fields($element['#field_name'], $element['#type_name']);
......@@ -149,7 +155,7 @@ function filefield_save_upload($element) {
}
/**
* FileField widget element callbacks.
* The #value_callback for the filefield_widget type element.
*/
function filefield_widget_value($element, $edit = FALSE) {
if (!$edit) {
......@@ -179,6 +185,12 @@ function filefield_widget_value($element, $edit = FALSE) {
return $item;
}
/**
* An element #process callback for the filefield_widget field type.
*
* Expands the filefield_widget type to include the upload field, upload and
* remove buttons, and the description field.
*/
function filefield_widget_process($element, $edit, &$form_state, $form) {
// The widget is being presented, so apply the JavaScript.
drupal_add_js(drupal_get_path('module', 'filefield') .'/filefield.js');
......@@ -310,6 +322,9 @@ function filefield_widget_process($element, $edit, &$form_state, $form) {
return $element;
}
/**
* An #element_validate callback for the filefield_widget field.
*/
function filefield_widget_validate($element, &$form_state) {
// Currently all handled by filefield_widget_upload_validators().
}
......@@ -384,9 +399,12 @@ function theme_filefield_widget_file($element) {
}
/**
* #require validation for filetype fields.
* Additional #validate handler for the node form.
*
* This function checks the #required properties on file fields and calculates
* node upload totals for all file fields. The #required property is not
* properly supported on file fields by Drupal core, so we do this manually.
*/
function filefield_node_form_validate($form, &$form_state) {
$type = content_types($form['type']['#value']);
foreach ($type['fields'] as $field_name => $field) {
......@@ -418,10 +436,15 @@ function filefield_node_form_validate($form, &$form_state) {
}
}
/**
* Additional #submit handler for the node form.
*/
function filefield_node_form_submit($form, &$form_state) {
// we ignore all but the save button here.
if ($form_state['values']['op'] != t('Save')) {
// Only add additional submit handling on save.
if ($form_state['values']['op'] == t('Save')) {
// TODO: Immediately delete temporary files that were uploaded but never
// saved. This isn't critical to do, since any file not saved with the node
// will by cleaned up by system_cron() after 6 hours.
return;
}
// @todo: try to delete removed files.
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment