ReactFilePondUpload

Stable Version 1.0.6 (OutSystems 11)
Published on 27 May (9 days ago) by 
Created on 21 December 2019
Documentation

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
  • Note on Internet Explorer 11 (not supported)
  • Add Image Editing
  • Site Properties
  • Widgets
  • Actions
  • Structures
  • Roadmap


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, either by selecting the files or dragging a folder*.  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.

* Set MaxFiles = 0 to enable folder drag and drop.

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.


Note on Internet Explorer 11

Internet Explorer 11 is not currently supported by the ReactFilePondUpload control.  The FilePond library itself supports IE 11, however, testing in OutSystems React Web Apps has not been successful.  When React Web Apps work well enough in IE 11, support in this component will follow.

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,
  2. Purchase Doka and download the files,
  3. Create a webblock and add files, and
  4. Include the webblock with the upload widget.

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.

  1. Create a webblock called FilePondUpload_DokaBlock
  2. Use an editor with good text support, such as Notepad++ or Visual Studio Code.  Do not use Notepad.
  3. Copy the content of the javascript files into the webblock's Javascript attribute
    .\bin\polyfill\doka.polyfill.min.js, and
    .\bin\browser\doka.min.js
  4. Copy the content of the CSS file into the webblock's Stylesheet attribute
    .\bin\browser\doka.min.css

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

UploadBlock

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:

  1. Place an UploadBlock in a form,
  2. Configure the block with a FilePondUploadConfig structure,
  3. Each uploaded file is allocated a token which can be used to retrieve the file,
  4. On the client side, when the submit button is clicked, get file tokens with FilePondUpload_GetTokens(). Pass these tokens to a server function to retrieve uploaded files. Then clear the upload control with client action FilePondUpload_Reset(),
  5. On the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles(UploadTokens) to retrieve the uploaded files.
  6. Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles().

AutoUploadBlock

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 Uploaded event. Configure the webblock with the FilePondUploadConfig structure.  See below for details of actions and structures.

When multiple files are uploading, the Uploaded event will trigger when they have all completed.  Tokens for all successful files uploads will be returned in the Uploaded event.

How to use the web block:

  1. Place an AutoUploadBlock on a page,
  2. Configure the block with a FilePondUploadConfig structure,
  3. Each uploaded file is allocated a token which can be used to retrieve the file.
  4. On the client side, handle the Uploaded event, passing the Tokens parameter to a server action to process files.
  5. On the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles(UploadTokens) to retrieve the uploaded files.
  6. Upon retrieving the uploaded files, their temporary copy will be removed.
  7. A timer will remove temporary uploaded files older than 30 minutes.

See the ReactFilePondUpload_Sample for examples of how to use the widgets.


Client Actions

FilePondUpload_GetTokens()

Retrieve the tokens for uploaded files.  Pass the returned string to the server, then call FilePondUpload_GetUploadedFiles().

FilePondUpload_Reset()

Reset the upload widget, removing uploaded files and clearing upload tokens.

FilePond_HumanReadableFileSize()

Convert the number of bytes to a human readable string eg "10.25 GB"

Parameters

FileSize (Integer) The file size in bytes

Decimals (Integer) The number of decimal places, defaults to 2.

FileSizeText (Text) Human readable file size text. eg "10.25 GB"


Server 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

Parameters

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)

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

Parameters

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.

Parameters

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.


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.  To enable folder drag and drop set MaxFiles to zero. 

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.

Attributes

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.

Roadmap

Next release

  • Update to the latest version of FilePond.

Future releases

  • Update the sample application to include a demo page with multiple uploads on a single page.
  • Display percent upload progress.
  • Support for Internet Explorer 11- depends on support in OutSystems React Web Apps (Thanks Jan Ancukiewicz!)


Support Options
This component is not supported by OutSystems. You may use the discussion forums to leave suggestions or obtain best-effort support from the community, including from Stuart Harris who created this component.
Dependencies
ReactFilePondUpload has no dependencies.