function hook_file_action in Ubercart 5

Same name and namespace in other branches

1. 6.2 docs/hooks.php \hook_file_action()

Perform actions on file products.

The uc_file module comes with a file manager (found at Administer » Store administration » Products » View file downloads) that provides some basic functionality: deletion of multiple files and directories, and upload of single files (those looking to upload multiple files should just directly upload them to their file download directory then visit the file manager which automatically updates new files found in its directory). Developers that need to create more advanced actions with this file manager can do so by using this hook.

Parameters

$op: The operation being taken by the hook, possible ops defined below.

• 'info': Called before the uc_file module builds its list of possible file actions. This op is used to define new actions that will be placed in the file action select box.
• 'insert': Called after uc_file discovers a new file in the file download directory.
• 'form': When any defined file action is selected and submitted to the form this function is called to render the next form. Because this is called whenever a module-defined file action is selected, the variable $args['action'] can be used to define a new form or append to an existing form.
• 'upload': After a file has been uploaded, via the file manager's built in file upload function, and moved to the file download directory this op can perform any remaining operations it needs to perform on the file before its placed into the uc_files table.
• 'upload_validate': This op is called to validate the uploaded file that was uploaded via the file manager's built in file upload function. At this point, the file has been uploaded to PHP's temporary directory. Files passing this upload validate function will be moved into the file downloads directory.
• 'validate': This op is called to validate the file action form.
• 'submit': This op is called to submit the file action form.

$args: A keyed array of values that varies depending on the op being performed, possible values defined below.

• 'info': None
• 'insert':
  • 'file_object': The file object of the newly discovered file
• 'form':
  • 'action': The file action being performed as defined by the key in the array sent by hook_file_action($op = 'info')
  • 'file_ids' - The file ids (as defined in the uc_files table) of the selected files to perform the action on
• 'upload':
  • 'file_object': The file object of the file moved into file downloads directory
  • 'form_id': The form_id variable of the form_submit function
  • 'form_values': The form_values variable of the form_submit function
• 'upload_validate':
  • 'file_object': The file object of the file that has been uploaded into PHP's temporary upload directory
  • 'form_id': The form_id variable of the form_validate function
  • 'form_values': The form_values variable of the form_validate function
• 'validate':
  • 'form_id': The form_id variable of the form_validate function
  • 'form_values': The form_values variable of the form_validate function
• 'submit':
  • 'form_id': The form_id variable of the form_submit function
  • 'form_values': The form_values variable of the form_submit function

Return value

The return value of hook depends on the op being performed, possible return values defined below.

• 'info': The associative array of possible actions to perform. The keys are unique strings that defines the actions to perform. The values are the text to be displayed in the file action select box.
• 'insert': None
• 'form': This op should return an array of drupal form elements as defined by the drupal form API.
• 'upload': None
• 'upload_validate': None
• 'validate': None
• 'submit': None

4 invocations of hook_file_action()

uc_file_files_form in uc_file/uc_file.module

Form builder for file products admin

uc_file_files_form_submit in uc_file/uc_file.module

uc_file_files_form_validate in uc_file/uc_file.module

_file_table_action in uc_file/uc_file.module

Perform a specified action on the uc_files table

File

docs/hooks.php, line 448

These are the hooks that are invoked by the Übercart core.

Code

function hook_file_action($op, $args) {
  switch ($op) {
    case 'info':
      return array(
        'uc_image_watermark_add_mark' => 'Add Watermark',
      );
    case 'insert':

      //automatically adds watermarks to any new files that are uploaded to the file download directory
      _add_watermark($args['file_object']->filepath);
      break;
    case 'form':
      if ($args['action'] == 'uc_image_watermark_add_mark') {
        $form['watermark_text'] = array(
          '#type' => 'textfield',
          '#title' => t('Watermark Text'),
        );
        $form['submit_watermark'] = array(
          '#type' => 'submit',
          '#value' => t('Add Watermark'),
        );
      }
      return $form;
    case 'upload':
      _add_watermark($args['file_object']->filepath);
      break;
    case 'upload_validate':

      //Given a file path, function checks if file is valid JPEG
      if (!_check_image($args['file_object']->filepath)) {
        form_set_error('upload', t('Uploaded file is not a valid JPEG'));
      }
      break;
    case 'validate':
      if ($args['form_values']['action'] == 'uc_image_watermark_add_mark') {
        if (empty($args['form_values']['watermark_text'])) {
          form_set_error('watermar_text', t('Must fill in text'));
        }
      }
      break;
    case 'submit':
      if ($args['form_values']['action'] == 'uc_image_watermark_add_mark') {
        foreach ($args['form_values']['file_ids'] as $file_id) {
          $filename = db_result(db_query("SELECT filename FROM {uc_files} WHERE fid = %d", $file_id));

          //Function adds watermark to image
          _add_watermark($filename);
        }
      }
      break;
  }
}