File Upload

Functions
	hook_file_upload_check ($action, $details, &$message)

Detailed Description

Tripal provides a convenient HTML5 Javascript uploader. It is automatically embedded into the TripalImporter class. This application programing interface (API) provides support for working with uploaded files.

If you want to use the TripalUploader JavaScript in your own form the following must be performed:

1) Add a Drupal form to your code that contains the following:

• A Drupal-style table with 4 or 8 columns. See the initialize function in this class for a description of the columns.
• A button for submitting a file for upload.

$headers = array(
   array('data' => 'Sequence File'),
   array('data' => 'Size', 'width' => '10%'),
   array('data' => 'Upload Progress', 'width' => '20%'),
   array('data' => 'Action', 'width' => '10%')
 );
 $rows = array();
 $table_vars = array(
   'header'      => $headers,
   'rows'        => $rows,
   'attributes'  => array('id' => 'sequence-file-upload-table'),
   'sticky'      => TRUE,
   'colgroups'   => array(),
   'empty'       => t('There are currently no files added.'),
 );
 $form['upload']['sequence_file'] = array(
   '#markup' => theme('table', $table_vars)
 );
 $form['upload']['sequence_fid'] = array(
   '#type' => 'hidden',
   '#value' => 0,
   '#attributes' => array('id' => 'sequence-fid')
 );
 $form['upload']['sequence_file_submit'] = array(
   '#type'     => 'submit',
   '#value'    => 'Upload Sequence File',
   '#name' => 'sequence_file_submit',
   // We don't want this button to submit as the file upload
   // is handled by the JavaScript code.
   '#attributes' => array('onclick' => 'return (false);')
 );

2) Edit the theme/js/[module_name].js and in the "Drupal.behaviors.[module]" section add a JQuery show function to the form that converts the table created in the Drupal form to a TripalUploader table. The 'table_id' must be the same as the 'id' attribute set for the table in the Drupal code above. The 'submit_id' must be the id of the upload button added in the Drupal code above. The 'category' for the files. This is the category that will be saved in Tripal for the file. See the addUploadTable function for additional options. Include a 'cardinality' setting to indicate the number of allowed files per upload, and set the 'target_id' to the name of the field that will contain the file ID (fid) after uploading.

// The TripalUploader object used for uploading of files using the
// HTML5 File API. Large files are uploaded as chunks and a progress
// bar is provided.
var uploader = new TripalUploader();
 
$('#tripal-sequences-panel-form').show(function() {
  uploader.addUploadTable('sequence_file', {
    'table_id' : '#sequence-file-upload-table',
    'submit_id': '#edit-sequence-file-submit',
    'category' : ['sequence_file'],
    'cardinality' : 1,
    'target_id' : 'sequence-fid',
  });
});

3) Files are uploaded automatically to Tripal. Files are saved in the Tripal user's directory. You can retrieve information about the file by querying for the file category for the current project.

$seq_files = TripalFeature::getFilesByTypes($user->uid,
                array('sequence_file'), $project_id);

4) If the 'target_id' was used in array for step #2 above, then the file ID can be retrieved in the hook_validate() and hook_submit() functions via the $form_state['input'] array (not the $form_state['values'] array.

Function Documentation

hook_file_upload_check()

hook_file_upload_check	(		$action,
			$details,
		&	$message
	)

Allows a module to interact with the Tripal file uploader during upload.

This function is called prior to an 'action' occurring and allows the module that is responsible for the file upload to halt an upload if needed.

Parameters

$action	The current action that is being performed during the upload process. The actions are: 'save', 'check' and 'merge'.
$details	An associative array containing details about the upload process. Valid keys include: filename: The name of the file. file_size: The total size of the file. chunk_size: The size of the chunk. fid: The file ID of the file.
$message	An error message to report to the user if the function returns FALSE.

Returns

TRUE if the upload should continue. FALSE if a problem occurs and the upload should be terminated.