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.


TitleUpload Field
DescriptionProvides an upload field with support for thumbnail preview
JSON Schema Type(s)array
Field Typeupload
Base Field TypeNone


defaultanyThe default value to be assigned for this property. If the data for the field is empty or not provided, this default value will be plugged in for you. Specify a default value when you want to pre-populate the field's value ahead of time.
dependenciesarrayList of property dependencies.
descriptionstringDetailed description of the property.
disallowarrayList of disallowed values for the property.
enumarrayList of specific values for this property
formatstringData format of the property.
readonlybooleanIndicates that the field is read-only. A read-only field cannot have it's value changed. Read-only fields render in a grayed-out or disabled control. If the field is rendered using a view with the displayReadonly attribute set to false, the read-only field will not appear.
requiredbooleanIndicates whether the field's value is required. If set to true, the field must take on a valid value and cannnot be left empty or unassigned.
titlestringShort description of the property.
typestringarrayData type of the property.


directorybooleanWhether to allow directories (folders) to be dropped into the control for multi-document upload.
disabledbooleanField will be disabled if true.
errorHandlerfunctionOptional 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.
fieldClassstringSpecifies one or more CSS classes that should be applied to the dom element for this field once it is rendered. Supports a single value, comma-delimited values, space-delimited values or values passed in as an array.
fileTypesstringA regular expression limiting the file types that can be uploaded based on filename
focuscheckboxtrueIf true, the initial focus for the form will be set to the first child element (usually the first field in the form). If a field name or path is provided, then the specified child field will receive focus. For example, you might set focus to 'name' (selecting the 'name' field) or you might set it to 'client/name' which picks the 'name' field on the 'client' object.
formobjectOptions for rendering the FORM tag.
helperstringField help message.
helpersarrayAn array of field help messages. Each message will be displayed on it's own line.
helpersPositionstringbelowDefines the placement location of the helper text relative to the control (either 'above' or 'below')
hiddenbooleanField will be hidden if true.
hideInitValidationErrorbooleanHide initial validation errors if true.
idstringUnique field id. Auto-generated if not provided.
labelstringField label.
maxFileSizenumber-1The 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.
maxNumberOfFilesnumber1The 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.
multiplebooleanWhether to allow multiple file uploads. If maxNumberOfFiles is not specified, multiple will toggle between 1 and unlimited.
namestringField Name.
optionLabelsarrayAn array of string labels for items in the enum array
readonlybooleanField will be readonly if true.
showMessagesbooleantrueDisplay validation messages if true.
showUploadPreviewbooleantrueWhether to show thumbnails for uploaded assets (requires preview support)
sortfunctionDefines 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.
typestringuploadField type.
validatebooleantrueField validation is required if true.
viewstringAllows for this field to be rendered with a different view (such as 'display' or 'create')

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:

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

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.

© 2018 Gitana Software, Inc.

Alpaca is sponsored by