UpAPI (as in Upload API)

Provides a form element and other tools to make custom file uploads as easy as possible. These modules are of particular interest to module developers who need to add an upload field to a customized form. If you're not a developer, install this module only if another module requires it.

Good News Developers

No more beating your head against file.inc!

This package includes two modules. One introduces a form element for file uploads. These look similar to fields presented the upload and filefield modules, but are not limited to just node forms. The second module provides a higher level API. It will save file information to the database upon form submit, so your module has to do relatively little work.

As an example, here's how a module could add an upload to the Story node form:

function example_form_alter($form_id, &$form) {
  if ($form_id == 'story_node_form') { // add files to story nodes.
    $node = $form['#node'];

    // a file associated with this node
    $form['single_file'] = 
      array('#type' => 'upfield',
            '#multiple' => FALSE,
            '#title' => t('File upload example'),
            '#description' => t('Please share your favorite file with us!'),
            '#label' => 'example_single', // An identifier for UpAPI.
            '#callback' => 'upapi_callback', // Let UpAPI save the data.
            // This next bit tells UpAPI to associate this file with this node.
            '#callback_data' => array('obj_type' => UPAPI_TYPE_NODE_ID,
                                      'obj_id' => $form['nid']['#value'],
                                      // Here we control where file is stored.
                                      'destination' => '%file_directory/upapi_example/%filename',
            ),
      );
  }
}

Perhaps that looks complicated, but believe me its better than building it all yourself. Learn more by studying upapi_example.module.

Wishlist

I welcome patches towards any of these goals:

• Javascripty goodness like progress bar, etc.
• Validation. Insuring the presence of required files, limiting by extension or mime type.
• Usability improvements like prompting for, say, at least three files (or whatever number).
• Security issues. I don't know that there are any, but please let me know if you find them.
• Support for databases other than MySQL. (Sorry I don't have others installed)
• Anywhere you see TODO in the code. :)

Parting Thoughts

There are many visions in the Drupal community as to what a file API should be. This is mine, and I think its flexible enough to satisfy most upload needs.

I welcome testing, feedback, etc. I had an itch. I scratched. This module is the result. Now I'm sharing. This is a module for developers. If you've read this far, you probably are one. So I leave you with one last thought: bug reports get much more love if a patch is included.