File upload widgets that allows AJAX submit, automatic upload with no further submit needed, with drag/drop and image preview that works on all browsers, including Internet Explorer 11 and Edge. It uses the awesome FilePond javascript library. https://pqina.nl/filepond/ by Rik Schennink.
The widget requires that users are logged in and will prevent uploads for anonymous users.
Contents
Scenarios
The following are scenarios for use of the FilePondUpload plugin.
Scenario #1 - Multiple file upload
The user drags multiple files onto the file upload widget. The files show upload progress as well as a thumbnail if the files are images. Once files are uploaded, the Save button becomes enabled.
The user clicks on the Save button and the files are stored.
Scenario #2 - Automatic file upload
The user drags multiple files onto the automatic file upload widget. The files show upload progress as well as a thumbnail if the files are images. Each file is stored once it has been uploaded.
Scenario #3 - Single MS Excel file upload limited by size
The user drags an MSWord document onto the file upload widget. The widget shows an error.
The user drags an MSExcel file that is larger than the allowed size. The widget shows an error.
The user drags an MSExcel file that is within the allowed size. The file is uploaded.
Scenario #4 - Edit an image before uploading*
The user drags an image file onto the file upload widget.
The image editor is displayed.
The user crops the image, sets the aspect ratio, applies a filter, adds a text label and clicks "Done".
The edited image is uploaded.
* Image editing requires the purchase of the Doka image editing library. See below for how to add support for image editing.
Add Image Editing
As the Doka image editing library is a paid library, the Doka files must be added separately.
Follow these steps:
1. Switch on image editing
To switch on image editing, set configuration item ImageEdit = True, and optionally InstantImageEdit = True.
2. Purchase Doka and download the files
Visit the Doka website and purchase a subscription. Ensure the subscription matches your intended usage of the library.
Download and unzip the Doka files. You will need the files under folders .\bin\browser\ and .\bin\polyfill\
3. Create a webblock and add files
Using a webblock will ensure the Doka files required for image editing are available on the page.
4. Include the webblock with the upload widget
Whenever you use the file upload webblock, also drag on the FilePondUpload_DokaBlock webblock that you created in the previous step to allow image editing.
Site Properties
AllowAnonymousUpload
If True, upload will work even when there is no logged in user. Otherwise, uploads will fail if there is no logged in user. Defaults to False, so that anonymous uploads are prevented by default. Enabling anonymous upload increases the risk of denial of service attack. If it is to be used, additional steps should be taken, such as a captcha and restricting access to the site to an internal network, or a whitelisted IP address range.
UploadFileExpiryMinutes
Upload files are removed if they are older than this number of minutes
Widgets
FileUploadBlock
This webblock provides drag and drop multiple file upload via an AJAX submit. Retrieve uploaded files in the submit action using the FilePondUpload_GetUploadedFiles() action. Configure the webblock with the FilePondUploadConfig structure. See below for details of actions and structures.
How to use the web block:
AutoFileUploadBlock
This webblock provides drag and drop multiple file upload automatically without requiring the user to click a submit button. Uploaded files are provided via the FileUploaded event. Configure the webblock with the FilePondUploadConfig structure.
If one of the files errors during upload, it must be removed or re-uploaded before the FileUploaded event is triggered.
See below for details of actions and structures.
See the FilePondUpload_Sample for examples of how to use the widgets.
Actions
The FilePondUpload plugin exposes the following actions.
FilePondUpload_CreateAcceptedFileTypes()
Helper function to create a list of accepted file types.
Parameters
FileType1 (Text) Mime file type eg "image/jpeg"
FileType2 (Text) Mime file type eg "image/jpeg"
FileType3 (Text) ...
FileType10 (Text) Mime file type eg "image/jpeg"
AcceptedFileTypes (Out, Text) Mime types accepted for upload. If empty, all file types are accepted. Array of accepted file types. Can be mime types or wild cards. For instance ['image/*'] will accept all images. ['image/png', 'image/jpeg'] will only accepts PNGs and JPEGs.
FilePondUpload_CreateCommonAcceptedFileTypes()
Helper action to create common accepted file types
Images (Boolean) Include images "image/*"
Videos (Boolean) Include videos "video/*"
Text (Boolean) Include text "text/csv", "text/txt"
Documents (Boolean) Include documents "pdf, doc, docx, rft"
OfficeDocs (Boolean) Include MS Office documents "xls, xlsx, ppt, pptx"
FileType1 (Text) An additional mime file type eg "dsw"
FileType2 (Text) ...
FileType10 (Text)
FilePondUpload_GetUploadedFiles()
Retrieve files uploaded based on the specified FilePond tokens. This action may only be called once, as the files are removed from temporary storage. To access uploaded file details without removing them, use FilePondUpload_PeekUploadedFiles. The FilePond tokens are populated in the hidden input textbox in the upload block placeholder.
UploadTokens (Text) The variable held by the input text control in the UploadBlock placeholder.
FileList (Out, RequestFile List) Retrieve files uploaded based on the submitted hidden FilePond tokens.
FilePondUpload_PeekUploadedFiles()
Peek files uploaded based on the specified FilePond tokens. The files are not removed from temporary storage. Call FilePondUpload_GetUploadedFiles to retrieve the files the last time in order to remove them from temporary storage.
Structures
The FilePondUpload plugin exposes the following structure.
FilePondUploadConfig
A structure to hold configuration options for the FilePond upload blocks.
Attributes
Name (Text) Name to use for the internal file upload form control. Default='filePondUpload'
LabelIdle (Text), Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'
MaxFiles (Integer) Maximum number of files to upload. Defaults to zero. Zero means unrestricted.
MaxFileSizeMb (Decimal) The maximum size of a file in megabytes. If zero, there is no maximum.
AcceptedFileTypes (Text List) Mime types accepted for upload. If empty, all file types are accepted. Can be mime types or wild cards. For instance ['image/*'] will accept all images. ['image/png', 'image/jpeg'] will only accepts PNGs and JPEGs, ['*.doc', '*.docx'] will accept MSWord documents. If empty all file types are accepted.
AllowBrowse (Boolean) Allow the user to browse for files. Default = True
AllowDrop (Boolean) Allow the user to drop files. Default = True
DropOnPage (Boolean) Catch all files dropped on the webpage. Default = False
DropValidation (Boolean) When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.
InstantUpload (Boolean) Upload immediately the file is selected or dropped.
PreviewImages (Boolean) If the file is an image, show a preview
DisableSubmit (Boolean) Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.
SubmitButtonId (Text) The HTML id of the submit button if DisableSubmit is set to yes.
DefaultFileURL (Text) The url for the initial file. When specified a file is displayed when the control is rendered. Consider setting InstantUpload=False when using this setting.
StyleAspectRatio (Text) Set a forced aspect ratio for the FilePond drop area. Useful to make the drop area take up a fixed amount of space. For example when cropping a single square image. Accepts human readable aspect ratios like '1:1'. Default is empty string.
StylePanelLayout (Text) Set a different layout render mode. Can be either 'integrated', 'compact', and/or 'circle'. Compact mode will remove padding, integrated mode is used to render FilePond as part of a bigger element. Circle mode adjusts the item position offsets so buttons and progress indicators don’t fall outside of the circular shape. Default is empty string.
Log (Boolean) Log messages in javascript. Useful for debugging. Default = False
The FilePondUpload plugin also uses the RequestFile structure from the HTTPRequestHandler extension.
RequestFile
A file uploaded to the website.
FileName (Text) The name of the file uploaded
FileType (Text) The MIME type of the uploaded file
FileSize (Integer) The size of the uploaded file in bytes
BinaryContent (Binary Data) The content of the uploaded file.
Team Membership Agreement
As a member of this team, I agree to abide by the following rules: