Upload Field

The upload field provides a mechanism that enables end users to upload one or more files to a server endpoint and have references to those files stored in the JSON of your form. For example, you may have an array of files in your JSON consisting of filenames to assets that are uploaded to your server - something like:

{
    "title": "My Files",
    "files": [{
        "filename": "/folder1/folder2/file3.jpg"
    }, {
        "filename": "/folder1/folder2/file4.pdf"
    }]
}

This field renders an upload control so that end users can pick at local files and upload them. It provides the hook points so that you can learn about the uploaded files and wire back descriptors that get plugged into your array. Descriptors can be any format you like. That way, when people edit an existing JSON, the descriptors can be resolved to physical assets on your server.

In addition, the upload control supports thumbnail previews and progress bar controls. It uses the much-esteemed jQuery File Upload plugin under the hood.

The control accepts an upload configuration object which gets passed to the file upload plugin. The following are typically specified:

{
    // url of the endpoint
    "url": "/",

    // (optional) type of data being posted
    "dataType": "json",

    // (optional) "get" or "post" typically
    "method": "post",

    // whether to automatically upload when a file is selected
    "autoUpload": true,

    // whether to show a separate submit button (needed if not auto-upload)
    "showSubmitButton": false
}

And more properties can be specified as needed by the underlying plugin.

The control also supports drag and drop of files from the desktop into the web page provided that you're using an HTML5 File API compatible browser. Which, as you might expect, doesn't include IE8 or IE9.

Properties

Schema

Options

Example 1

Single related file upload. An example of a single file upload control. Uploads are posted to /fileupload/index.php. We've wired this up using a postRender callback so you can see the generated JSON by clicking 'view'.

Example 2

Content creation form with support for multiple uploads as attachments. Note that the file uploads post right away to /fileupload/index.php.

The form is not submitted until the user clicks submit at which time the form posts to form.php.

In addition, we specify the maxFileSize, maxNumberOfFiles, multiple and fileTypes settings to adjust the behavior of the control.

Example 3

The formData property lets us pass multipart data along with each upload. This is useful if the upload.php script knows how to handle multipart. It can use this form data to make decisions about where to place content. The upload control supports tokenization with some limited information:

Example 4

The errorHandler property lets us specify a custom error handler to be fired when an upload is attempted and is ruled to be invalid (such as an invalid file or an invalid size).

Here is an example where we restrict the file types to *.blahblah and a file size of 1. Attempting to upload just about anything will cause these to trip so that you can test it out. The custom errorHandler brings up a Bootstrap modal instead of a regular ol' JavaScript alert.

Example 5

Here is the upload control rendered in display only mode.

Example 6

The progressall property lets us specify a custom progress bar to indicate the progress of a file being uploaded.