Dropbox: External File-Upload Forms

DateAuthor
2008-05-20J Frey

A department here at UD created a web form for their students to fill-out when they needed a poster printed on a large-format printer. This form featured a bunch of text fields as well as a file field for uploading the poster as a PowerPoint file. The form would be POSTed to a simple form-to-email agent that's been available at UD for ages.

Unfortunately, this meant that the staff person responsible for this service was routinely receiving gigantic attachments that were severely depleting his/her mail quota. The department asked if there would be any way that the form data could be redirected to Dropbox versus an email account. While the file itself would not be an issue for Dropbox, the question at hand was what to do with the additional form data on the page.

Whilst walking for a cup of coffee I debated how easily I could create just such an extension to the Dropbox service. The code is object-oriented and tends to foster excellent reuse value. The posted form data is coming from an unauthenticated client, which we already allow so long as the recipient(s) are @udel.edu email addresses. As long as an external web page honors some simple guidelines with respect to constructing the form – using correct field names for items that Dropbox is expecting – it should be relatively easy to setup.

Two hours later, the Dropbox Referral Service was online and ready for use by the UD community. DRS allows you to point a web form containing file upload controls to Dropbox, rather than to the usual email-based delivery. The uploaded files are augmented by one more file (XML, text, or HTML content) containing the additional form data from the page. The usual notification mechanisms in Dropbox allow the recipient of the form to be notified by email with pickup information and the sender to be emailed when the dropoff is picked-up.

Constructing a DRS-Compliant Form

In order to use this service you need to modify your web form to send the form data to the Dropbox system. You also need to modify the names you are using for the form fields and add a few DRS-specific fields to the page.

It is imperative that you adhere to the field naming conventions presented on this page! Failure to preserve the spelling and case as shown on this page will result in your form's not working properly.

HTML Form Element

Set the form to use the HTTP POST method, and the form must be encoded as multipart form data. The action URL for DRS is https://pandora.nss.udel.edu/referral.php.

DRS-Oriented Hidden Fields

Several "hidden" form fields are necessary in order to use DRS. Some of them hook into the Dropbox dropoff mechanism, while others control how any additional form fields are handled.

Field NameDescription
ActionThe value of this hidden form field must be "dropoff"
affPrefixName prefix for any additional form fields you'd like to be captured by the form processor
affFormatThe file format that should be used for any additional form field data captured by the form processor. Valid values are text, html, and xml. The default is text.
affSuccessURLIf the form processor successfully creates a dropoff, the client's browser will be redirected to this page.
affFailureURLIf the form processor cannot create a dropoff, the client's browser will be redirected to this page.
recipient_#The value of these fields should always be 1. The # should be replaced by increasing integer values starting from 1.
recipName_#Textual description of a recipient of the form data; can be blank. The # should be replaced by increasing integer values starting from 1.
recipEmail_#Email address of a recipient of the form data – must be a @udel.edu email address! The # should be replaced by increasing integer values starting from 1.

Multiple recipients are specified by adding multiple recipient_#+recipName_#+recipEmail_# hidden field triplets, replacing the "#" with an integer starting at one (1) and increasing with each subsequent triplet.

Lacking a defined value for affSuccessURL or affFailureURL, a page in the style of the Dropbox system is displayed with the appropriate status message. If a affFailureURL was supplied, then an explanatory message is attached to the end of the URL a'la

http://turin.nss.udel.edu/failure.php?message=No+files+were+uploaded.

Thus, if your failure page is script-based it could echo a more complete explanation of the failure to the user by means of the message CGI variable.

DRS-Oriented Visible Fields

There are two required fields (and four optional fields) that may be either hidden or visible to end user.

Field NameField TypeOptional?Description
senderNametextNoTextual description of the person posting the form. First and last name, for example.
senderOrganizationtextYesTextual description of the organizational affiliation of the person posting the form.
senderEmailtextNoThe email address of the end user who is posting the form.
confirmDeliverycheckboxYesShould an email be sent to senderEmail when the file(s) are picked-up?
desc_#textYesTextual description of file_#. The # should be replaced by increasing integer values starting from 1.
file_#fileNoThe form must include at least one file_# field, which represents the file being posted with this form. The # should be replaced by increasing integer values starting from 1.

Akin to the inclusion of multiple recipients for the form data, multiple files are allowed on the form by adding desc_#+file_# pairs, replacing the "#" with an integer starting at one (1) and increasing with each subsequent pair.

Additional Fields

You can augment the form to contain your own form data by properly naming any input fields that you add to the page. DRS requires that you uniquely prefix all of your own form fields in order to identify them to the form processor. Recall that this prefix is communicated to the form processor by means of the affPrefix hidden form field.

For example, I could add a popup menu and text area for description of the project being submitted:

  <input type="hidden" name="affPrefix" value="cisc"/>
  <input type="hidden" name="affFormat" value="xml"/>
  Select the project type:
  <select name="ciscProjectType">
    <option>Networking</option>
    <option>Web Interface</option>
    <option>System Utility</option>
  </select>
  <br/>
  Briefly describe this project:<br/>
  <textarea name="ciscProjectDescription">
  </textarea>

When the form is submitted, the selected popup menu value and text area content will be written to a file named AdditionalFormData.### that will appear among the files sent with the form (the ### will be replaced with the file extension appropriate for the selected affFormat). Given that the form above requested XML, the file would be named AdditionalFormData.xml and would contain something like this:

<?xml version="1.0" ?>
<form-data>
  <ProjectType>Networking</ProjectType>
  <ProjectDescription>The core network needs to be modified to allow everyone to do cool multicast broadcasts of their dorm room webcam throughout the day.</ProjectDescription>
</form-data>

Had text format been chosen, the file would be named AdditionalFormData.txt and contain:

ProjectType = Networking
ProjectDescription = The core network needs to be modified to allow everyone to do cool multicast broadcasts of their dorm room webcam throughout the day.

Last but not least, the html format outputs the data as a table structure with the file named AdditionalFormData.html:

<html>
  <body>
    <table border="1">
      <tr><td><b>ProjectType</b></td><td>Networking</td></tr>
      <tr><td><b>ProjectDescription</b></td><td>The core network needs to be modified to allow everyone to do cool multicast broadcasts of their dorm room webcam throughout the day.</td></tr>
    </table>
  </body>
</html>

An Example Form

Putting all of the information presented above together in one place, the following example illustrates the construction of a very simple DRS-compliant form.

<form method="post" action="https://pandora.nss.udel.edu/referral.php"
  enctype="multipart/form-data">
 
  <!-- The "Action" field is needed by the dropoff-processing code;
       do not modify this field's definition in any way and expect
       the dropoff to actually happen.
    -->
  <input type="hidden" name="Action" value="dropoff"/>
 
  <!-- Provide the prefix used in naming any fields you add to this form that should
       be added to the dropoff as an additional file in the payload.
    -->
  <input type="hidden" name="affPrefix" value="che_"/>
 
  <!-- What kind of file should be generated to contain the additional form field
       data:  "text", "xml", and "html" are allowed ("text" is the default).
    -->
  <input type="hidden" name="affFormat" value="xml"/>
 
  <!-- Direct to a specific URL based on success or failure of the dropoff: -->
  <input type="hidden" name="affSuccessURL"
    value="http://turin.nss.udel.edu/template-success.html"/>
  <input type="hidden" name="affFailureURL"
    value="http://turin.nss.udel.edu/template-failure.html"/>
 
  <!-- Recipients of the dropoff; should be ONLY @udel.edu email
       addresses.  Of course, these fields should absolutely be
       hidden!
 
       Additional recipients are added by duplicating the two
       fields shown below and incrementing the trailing integer
       (a'la "recipient_2").
    -->
  <input type="hidden" name="recipient_1" value="1"/>
  <input type="hidden" name="recipName_1" value="Jeffrey Frey"/>
  <input type="hidden" name="recipEmail_1" value="frey@udel.edu"/>
 
 
  <!-- Who may we ask is sending this form data?  At the very least the senderEmail
       must be presented and filled-in by the end user.
    -->
  Sender name:<input type="text" name="senderName"/><br/>
  Sender organization:<input type="text" name="senderOrganization"/><br/>
  Sender email:<input type="text" name="senderEmail"/>
  <hr/>
 
 
  <!-- The file(s) being dropped-off with accompanying textual
       description(s).
 
       Additional files are added by duplicating the two
       fields shown below and incrementing the trailing integer
       (a'la "file_2").
    -->
  File:<input type="text" name="desc_1"/>
  <input type="file" name="file_1"/>
  <hr/>
 
  Confirm delivery of this file:<input type="checkbox" name="confirmDelivery" checked/>
  <hr/>
 
  <!-- Any additional form fields we want to accompany this dropoff: -->
  Project description:<textarea name="che_projectDescription"></textarea><br/>
  Project code:<input type="text" name="che_projectCode" size="8" maxlen="8"/>
  <hr/>
 
  <button type="submit">Submit!</button>
</form>

Disclaimer

The DRS (Dropbox Referral Service) is provided free of charge to University of Delaware web developers by the IT/Network and Systems Services group. Web developers and end users are reminded that the Dropbox service does not virus-scan the files presented to it; always be wary of files you receive from other users and protect your computer with a virus scanner.

Feedback and questions should be directed to Jeff Frey.

 
Back to top
documentation/referral.txt · Last modified: 2012-12-04 17:14 (external edit)
Driven by DokuWiki Recent changes RSS feed