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.


Title Upload
Description Provides an upload field with support for thumbnail preview
Field Type upload
Base Field Type control


Property Type Default Description
enum array List of specific values for this property


Property Type Default Description
directory boolean Whether to allow directories (folders) to be dropped into the control for multi-document upload.
errorHandler function Optional function handler to be called when one or more files fails to upload. This function is responsible for parsing the underlying xHR request and populating the error message state.
fileTypes string A regular expression limiting the file types that can be uploaded based on filename
maxFileSize number -1 The maximum file size allowed per upload. If greater than zero, the maximum file size will be limited to the given size in bytes. If -1, then no limit is imposed.
maxNumberOfFiles number 1 The maximum number of files to allow to be uploaded. If greater than zero, the maximum number will be constrained. If -1, then no limit is imposed.
multiple boolean Whether to allow multiple file uploads. If maxNumberOfFiles is not specified, multiple will toggle between 1 and unlimited.
name string Field Name.
showUploadPreview boolean true Whether to show thumbnails for uploaded assets (requires preview support)
sort function Defines an f(a,b) sort function for the array of enumerated values [{text, value}]. This is used to sort enum and optionLabels as well as results that come back from any data sources (for select and radio controls). By default the items are sorted alphabetically. Don't apply any sorting if false.

Example 1

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'.

{% raw %} {% endraw %}

Example 2

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.

{% raw %} {% endraw %}

Example 3

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:

token value
index The # of the file being uploaded (starting at 0)
name Filename of the file (from browser)
size Size of the file in bytes
url Upload URL for the file
thumbnailUrl Thumbail URL for the file
{% raw %} {% endraw %}

Example 4

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.

{% raw %} {% endraw %}

Example 5

{% raw %} {% endraw %}

Example 6

{% raw %} {% endraw %}