This field type uploads and temporarily stores files. Its exact behaviour depends on where and how your form is being used.
The default behaviour of the field is to allow a single file to be uploaded. It can also be set to allow multiple files to be uploaded, in which case the files will be stored in a single zip file. Once zipped, the field and file behaves in exactly the same way as uploading a single file.
You can restrict the file types that can be uploaded by adding a list of file extensions to the Validated File Types property.
Your form's "Encoding" property must be set to "Auto" (the default) or "Multi-part" to ensure the uploaded file is included in the post to the server (the field will prompt you to change this when added to your form if you have it set as URL encoded).
Uploaded files can be attached to emails (note that mail servers will put limits on file sizes, in AWS this is 40MB for the complete email), passed to the workflow engine, saved with form data, and referenced in History.
Field Value
When a file is first uploaded, the value of the field (before the page is submitted) is an obfuscated file path plus the name of the file, for example "C:\\fakepath\\my-photo.png". Once the page with the upload field on has been submitted (ie when you navigate forwards through the form) the value of the field becomes a reference to the file held in the platform, for example "file/D4C7D1D7-005F-4253-8CDA-E8CCE2C3E2D6/my-photo.png"
Multi-Language Sites
Some elements of this field, like the file upload button label and the placeholder text, are set automatically by the user's browser. The English text in most browsers is "Choose file" and "No file chosen", but even this will vary per browser and operating system. Change your browser's language settings to see this text in another language.
The text of the "clear" button and the links for files that have already been uploaded can be set in the field, as these are features we have designed.
Examples
The Handling File Uploads article has example forms that show validation, multiple file uploads, download links, and using file references. It also discusses file uploads and how they are stored in the platform more generally.
Properties
| Label | Description | Type Name |
|---|---|---|
| Label | The label for this field | LABEL |
| Show Label | Whether to show the label for this field or not. This property adds/removes a class on the field's label element. The styling itself is controlled by the site's style sheet | SHOWLABEL |
| Hint | Additional information displayed alongside the field to assist the user in completing it. The value of another field can be used by adding the field's name between # characters. See Common Field Properties for more information | HINT |
| Required | Whether or not the field is required to have a value to pass validation. Note that any attempt to upload zero-byte files will automatically fail validation | REQUIRED |
| Error Message | The error message that will be displayed if this field fails its validation | ERRMSG |
| Error Message Function | A function that can be used to override the default error message. You can return a different message for each error type. The message can include the value of another field can be used by adding the field's name between # characters. See Error Message Functions for more information. This field has the following error types:
| ERRMSGFUNC |
| Width | The display width of the field. The value matches a CSS class, which actually sets the width | WIDTH |
| Maximum File Size | Browser side validation that prevents users uploading files greater than the set size. The default options are 1MB, 2MB, 5MB and 10MB. You can also enter your own value, which can include decimals and one suffix from B|KB|MB|GB. If no suffix is set bytes are assumed. A blank or 0 value means there is no restriction. This test is only performed on HTML5 sites and is only performed browser-side. If you enable multiple file uploads (see below) each file will need to be smaller than this maximum | UPLOADLIMIT |
| Media Capture | This property is designed to enhance the field type when the form is used on mobiles. Set this as true to allow access to the phone's media capture, like camera or microphone, from within the file upload field. The Acceptable File Type property should also be set to prompt the phone for the type of file you're expecting | CAPTURE |
| Acceptable Types | This property prompts a user's device for the type of file you are expecting. The types in the list (PDF, Audio, Image etc) can be used with the Media Capture setting to suggest to mobiles to open the camera app etc. It will also prompt, for example on Windows machines, the file explorer window to only show files of the specified type. However, this property doesn't perform validation or restrict the type of file that can be uploaded, it's simply a prompt Picking "Use validated file types" will use the file extensions set in the Validated File Types property below. This performs the same prompting as picking an option from the list | ACCEPT |
| Validated File Types | If you pick "Use validated file types" above, these options come into play. A comma separated list of allowed file types. If a user attempts to upload a file type not in the list, validation will fail. For example, to restrict the file upload to jpg and png files, enter | ACCEPTVALIDATED |
| Force Reload | If this property is set to true the user will be forced to upload a new file when existing form data is viewed. This includes navigating backwards through a form to a previous page that had a file upload field on it. Setting this property overrides the download link when the form is being displayed normally. If false, the user will be shown the name of the existing file but will not be able to replace it | FORCERELOAD |
| Validation Function | A JavaScript function that can be used to provide custom field validation whenever the field value changes or the form is submitted. This function will be executed client-side, provided JavaScript is enabled in the browser, and repeated server-side | VALFUNC |
| Handlers | A JavaScript function that is executed client-side whenever the page loads, or the field value changes. This function is useful for modifying the values of other fields based on an entered value | HANDLERS |
| Read Only | Display the field as read only | READONLY |
| Download Link | Display a download link for the uploaded file when navigating backwards through a form to a previously uploaded file and when editing form data. The link will also appear in emails and PDFs generated by the form submission, although it won't do anything - uploaded files are attached to emails instead. This property is ignored if the force reload property is set as true | DOWNLOADLINK |
| Download Link Text | Text for the download link, which can include internationalisation tokens. Defaults to (download) | DOWNLOADLINKTEXT |
| Show Clear Button? | Either true or false. If true a button will appear next to the file upload that, when pressed, will clear the chosen file. The button will appear when a page is first loaded, and when navigating backwards through a form to a previously uploaded file, but won't appear when the form is being used to display a file that has already been submitted (eg in the form data browser) | SHOWCLEAR |
| Clear Button label | A label for the clear button, which can include internationalisation tokens. Defaults to "Clear" | CLEARLABEL |
| Multiple File Upload as Zip | Set this property as true to allow multiple files to be uploaded in one go. The files will be zipped into a single file | MULTIUPLOADTOZIP |
| Multiple File Upload - Maximum Combined File Size | The maximum size of the zip file. The default options are 1MB, 2MB, 5MB and 10MB. You can also enter your own value with an appropriate suffix from B|KB|MB|GB (if not set bytes are assumed) | MULTIUPLOADLIMIT |
| Multiple File Upload - Maximum Files | The maximum number of files that can be uploaded at once. Defaults to 100 | MULTIUPLOADFILES |
| Additional Styling Modifier | An optional CSS modifier for the field. See Common Field Properties for an example | ADDITIONALSTYLINGMODIFIER |
| Documentation | Add documentation to your field to help explain any complex functionality to future users. You might include information on what the field does and how it relates to other fields on the form. Notes added here are only ever visible in the Forms Designer, they can be searched for, viewed and downloaded from the action panel. See Common Field Properties for an example | DOCUMENTATION |
Share this page
