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

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

Schema

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

Options

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

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

{% raw %} {% endraw %}

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.

{% raw %} {% endraw %}

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:

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

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.

{% raw %} {% endraw %}

Example 5

Here is the upload control rendered in display only mode.

{% raw %} {% endraw %}

Example 6

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

{% raw %} {% endraw %}