Skip navigation
Help

hook_uc_file_action

7 uc_file.api.php hook_uc_file_action($op, $args)

Performs 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_uc_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.

Related topics

5 invocations of hook_uc_file_action()

File

ubercart/uc_file/uc_file.api.php, line 121
Hooks provided by the File Downloads module.

Code

function hook_uc_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']->uri);
      break;
    case 'form':
      if ($args['action'] == 'uc_image_watermark_add_mark') {
        $form['watermark_text'] = array(
          '#type' => 'textfield', 
          '#title' => t('Watermark text'),
        );
        $form['actions'] = array('#type' => 'actions');
        $form['actions']['submit_watermark'] = array(
          '#type' => 'submit', 
          '#value' => t('Add watermark'),
        );
      }
      return $form;
    case 'upload':
      _add_watermark($args['file_object']->uri);
      break;
    case 'upload_validate':
      // Given a file path, function checks if file is valid JPEG.
      if (!_check_image($args['file_object']->uri)) {
        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_query("SELECT filename FROM {uc_files} WHERE fid = :fid", array(':fid' => $file_id))->fetchField();
          // Function adds watermark to image.
          _add_watermark($filename);
        }
      }
      break;
  }
}