Developer Guide

Development with rules

Events

Convert File provides 3 events (React on event)

• File conversion has been requested.
• File conversion has succeeded.
• File conversion has failed.

All 3 events provide two variables, a file object and the field instance configuration that the file is associated with. In cases that no such association exists, a simulated field instance configuration will be provided.

Development with hooks and rules

A hook is provided for third party modules to declare themselves as a provider for file conversions: hook_convertfile_info().

The example info hook below registers a callback function that will handle gzip conversions.

/**
 * Implements hook_convertfile_info().
 *
 * Register our provider and formats with convertfile module.
 */
function cf_convertfile_convertfile_info() {
  return array(
    'cf_convertfile' => array(
      'name' => 'Convert File',
      'types' => array (
        'gz' => '.gz (application/x-gzip)',
      ),
    ),
  );
}

Now fields that use the file field widget Convert File will have an option to select the provider as Convert File and a format of .gz (application/x-gzip)

When a file is uploaded into this field a custom #upload_validators callback will be executed. This callback will invoke the rule event File conversion has been requested.

Each provider will declare its own rules actions, generally one for each format provided, and provide default rules that listen for the file conversion event.

/**
 * Implements hook_rules_action_info().
 *
 * Register the convertfile gzip action with rules.
 */
function cf_convertfile_rules_action_info() {
  return array(
    'cf_convertfile_gzip' => array(
      'label' => t('Convert file to .gz (application/x-gzip) using Convert File'),
      'parameter' => array(
        'file' => array(
          'type' => 'file',
          'label' => t('File to convert'),
        ),
        'instance' => array(
          'type' => 'struct',
          'label' => t('Field instance data'),
        ),
      ),
      'group' => t('Convert File'),
      'base' => 'cf_convertfile_action_gzip',
    ),
  );
}

/**
 * Rules action to gzip a file.
 *
 * @param stdClass $file
 *   File object that is being readied to be moved from temporary server
 *   upload bin.
 * @param array $instance
 *   Field instance that this file was submitted to.
 *
 * @return
 *   Sets new property of $file->convertfile['error'] to TRUE on if an
 *   error was encountered, otherwise properties absense means success.
 *
 * @see cf_convertfile_rules_action_info()
 */
function cf_convertfile_action_gzip($file, $instance) {
  $success = FALSE;
  $settings = $instance['widget']['settings'];
  $dir = pathinfo($file->uri, PATHINFO_DIRNAME);
  $base = pathinfo($file->filename, PATHINFO_FILENAME);
  $ext = pathinfo($file->filename, PATHINFO_EXTENSION);

  if (($contents = file_get_contents($file->uri)) !== FALSE) {
    if ($fp = gzopen($file->uri, 'w9')) {
      if (gzwrite($fp, $contents)) {
        $ext_new = 'gz';
        $file->filename = $base . '.' . $ext . '.' . $ext_new;
        $file->filesize = filesize($file->uri);
        $file->filemime = file_get_mimetype($file->filename);
        $file->destination = $file->destination . '.' . $ext_new;
        $success = TRUE;
      }
      gzclose($fp);
    }
  }

  if (!$success) {
    $file->convertfile['error'] = TRUE;
  }
}

Listen for the convert file request event and execute our gzip action if appropriate conditions are met:

/**
 * Implements hook_default_rules_configuration().
 */
function cf_convertfile_default_rules_configuration() {
  $configs = array();

  // Automkatically gzip all text files uploaded to 'convert_file' widgets.
  $rule = '{ "cf_convertfile_gzip" : {
    "LABEL" : "CF Convert File convert to GZ",
    "PLUGIN" : "reaction rule",
    "TAGS" : [ "gzip", "convertfile", "gz" ],
    "REQUIRES" : [ "convertfile", "cf_convertfile", "rules" ],
    "ON" : [ "convertfile_request" ],
    "IF" : [
      { "convertfile_condition_provider" : {
          "instance" : [ "instance" ],
          "provider" : { "value" : { "cf_convertfile" : "cf_convertfile" } }
        }
      },
      { "convertfile_condition_format" : {
          "instance" : [ "instance" ],
          "format" : { "value" : { "gz" : "gz" } }
        }
      }
    ],
    "DO" : [
      { "cf_convertfile_gzip" : { "file" : [ "file" ], "instance" : [ "instance" ] } },
      { "drupal_message" : { "message" : "Your file has been compressed to reduce disk usage." } }
    ]
  }
}';

  $configs['cf_convertfile_gzip'] = rules_import($rule);

  return $configs;
}

Development with custom Form API element type

Convert file can be initiated while using the Form API by specifying the custom element type convertfile_file

$form['test_conversion'] = array(
  '#type' => 'convertfile_file',
  '#title' => 'Test file conversion',
  '#convertfile_provider' => 'cf_googledrive',
  '#convertfile_format' => 'pdf',
  '#description' => 'Test out the Form API element type convertfile_file by ' . 
    'specifying the googledrive provider and pdf format',
);