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

• How to Use ReactFilePondUpload
• Scenarios
• Note on Internet Explorer 11 (not supported)
• Add Image Editing
• Site Properties
• Widgets
• Actions
• Structures
• Roadmap
• Team Membership Agreement

How to Use ReactFilePondUpload

Follow these steps to use the Upload Block or the Auto Upload block in your application.

Upload Block

1. Create the dependencies that allow the usage of the component

The UploadBlock is used to upload files from the client side. The user drags multiple files onto the file upload widget, either by selecting the files or dragging a folder with the need of the user to click on a submit button. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the UploadBlock on the screen

Create a form and place the UploadBlock inside to be able to upload a file.

An example is provided in the picture UploadBlock in form below

UploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

Create a client action, name it "GetUploadConfig" and set the function to yes.

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

So 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(), as can be seen in the picture below as a sample.

AddNoteOnClick action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles() to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

Auto Upload Block

1. Create the dependencies that allow the usage of the component

The AutoUploadBlock is used to upload files from the client side. The user drags multiple files onto the automatic file upload widget, without requiring the user to click a submit button. Uploaded files are provided via the Uploaded event. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the AutoUploadBlock

Create a form and place the AutoUploadBlock inside to be able to upload a file.

An example is provided in the picture AutoUploadBlock in form below

AutoUploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

These configurations will allow manipulation of the upload. Such as:

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: Set a different layout render mode. Can be either 'integrated', 'compact', 'circle', 'integrated circle' or 'compact 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

On the client side, handle the Uploaded event, passing the Tokens parameter to a server action to process files, as can be seen in the picture below as a sample.

HandleUploadFiles action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So, on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles(UploadTokens) to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Upon retrieving the uploaded files, their temporary copy will be removed. Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

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.

Scenario #5 - Multiple file upload widgets on the one page

When multiple FilePondUpload blocks are on the same page, the WidgetId of the block must be specified as a parameter to the block and client actions FilePondUpload_GetTokens and FilePondUpload_Reset.

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

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

TraceLog

Set to True to enable trace logging for server actions.

UploadFileExpiryMinutes

Upload files are removed if they are older than this number of minutes.

UploadFileTimeoutSeconds

The timeout for the server action called from the client that uploads a file chunk. Valid values are 30, 60, 120, and 180. Any other values will fail.

If timeouts are occurring, increase this timeout value.

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.

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

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().

Events

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

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.

Parameters

WidgetId (Text) The id of the auto upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

Events

Uploaded 

A file or files have completed uploading. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(UploadTokens), then process the files as required.

Note, due to the asynchronous nature of uploads, GetTokens() may return multiple tokens, and retrieve multiple files, and the next event may then return no tokens and retrieve no files.

Ensure file processing will handle multiple or zero files.

Parameters

Tokens (Text) The tokens for uploaded files. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(Tokens).

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

UploadProgress

Reports the percentage progress of the file upload and an estimated time remaining

Parameters

File (UploadingFile) The file uploading

Client Actions

FilePondUpload_GetTokens()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePondUpload_Reset()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePond_HumanReadableFileSize()

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

Parameters

FileSize (Long 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, UploadedFileR 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, UploadedFileR 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. 

MaxParallelUploads (Integer) The maximum number of parallel uploads at a time

MaxParallelUploadsPerFile (Integer) The maximum number of parallel uploads at a time for a given file. Only applicable to SQL Server databases, other databases reset it to 1 so file chunks upload sequentially. Default = 4.

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.

MustMatchFilenameRegex (Text) If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex (Text) If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive (Boolean) If either match filename options are specified, this will control if the match is case sensitive

ShowCredits (Boolean) If True, shows the credits in faint text below the upload widget. Default = True

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.

UploadedFileR

A file uploaded to the website.

Attributes

UniqueToken (Text) The token representing the file

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

BinaryContent (Binary Data) The content of the uploaded file.

UploadingFile

A file where upload is in progress. Used by the UploadedStarted and UploadProgress callbacks.

Attributes

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

ProgressPercent (Decimal) The percentage progress of the file upload.

EstimatedTimeRemaining (Integer) The estimated number of seconds until the file upload completes. 

Roadmap

Please contact me if you would like specific features included, or an upcoming feature would be genuinely helpful for you. I cannot promise I will implement, but all suggestions will be given fair consideration.

Next release

• Option to retrieve files from a background task rather than requiring it to be in the user's session.
• Improved handling of empty files.

Future releases

• Option to compress large files prior to upload.
• Configuration options allowing for languages other than English.
• Support for Internet Explorer 11- depends on support in OutSystems React Web Apps (Thanks Jan Ancukiewicz!)

Team Membership Agreement

As a member of this team, I agree to abide by the following rules:

• All communication between developers and users is polite, constructive and in good faith,
• New features are listed on the roadmap (in plugin documentation) and announced to the team before work begins,
• Any disagreements about a feature must be resolved before a change is published,
• New features in extensions are unit tested in the extension,
• New versions are tested by the developer before being published,
• New versions are published in "Under Development" status until a team member has given it a successful test before being changed to "Stable",
• Any new teams members must agree to the ground rules. If a team member is not able to follow the ground rules, they must leave the team.

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

• How to Use ReactFilePondUpload
• Scenarios
• Note on Internet Explorer 11 (not supported)
• Add Image Editing
• Site Properties
• Widgets
• Actions
• Structures
• Roadmap
• Team Membership Agreement

How to Use ReactFilePondUpload

Follow these steps to use the Upload Block or the Auto Upload block in your application.

Upload Block

1. Create the dependencies that allow the usage of the component

The UploadBlock is used to upload files from the client side. The user drags multiple files onto the file upload widget, either by selecting the files or dragging a folder with the need of the user to click on a submit button. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the UploadBlock on the screen

Create a form and place the UploadBlock inside to be able to upload a file.

An example is provided in the picture UploadBlock in form below

UploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

Create a client action, name it "GetUploadConfig" and set the function to yes.

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

So 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(), as can be seen in the picture below as a sample.

AddNoteOnClick action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles() to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

Auto Upload Block

1. Create the dependencies that allow the usage of the component

The AutoUploadBlock is used to upload files from the client side. The user drags multiple files onto the automatic file upload widget, without requiring the user to click a submit button. Uploaded files are provided via the Uploaded event. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the AutoUploadBlock

Create a form and place the AutoUploadBlock inside to be able to upload a file.

An example is provided in the picture AutoUploadBlock in form below

AutoUploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

These configurations will allow manipulation of the upload. Such as:

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: Set a different layout render mode. Can be either 'integrated', 'compact', 'circle', 'integrated circle' or 'compact 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

On the client side, handle the Uploaded event, passing the Tokens parameter to a server action to process files, as can be seen in the picture below as a sample.

HandleUploadFiles action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So, on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles(UploadTokens) to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Upon retrieving the uploaded files, their temporary copy will be removed. Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

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.

Scenario #5 - Multiple file upload widgets on the one page

When multiple FilePondUpload blocks are on the same page, the WidgetId of the block must be specified as a parameter to the block and client actions FilePondUpload_GetTokens and FilePondUpload_Reset.

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

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

TraceLog

Set to True to enable trace logging for server actions.

UploadFileExpiryMinutes

Upload files are removed if they are older than this number of minutes.

UploadFileTimeoutSeconds

The timeout for the server action called from the client that uploads a file chunk. Valid values are 30, 60, 120, and 180. Any other values will fail.

If timeouts are occurring, increase this timeout value.

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.

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

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().

Events

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

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.

Parameters

WidgetId (Text) The id of the auto upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

Events

Uploaded 

A file or files have completed uploading. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(UploadTokens), then process the files as required.

Note, due to the asynchronous nature of uploads, GetTokens() may return multiple tokens, and retrieve multiple files, and the next event may then return no tokens and retrieve no files.

Ensure file processing will handle multiple or zero files.

Parameters

Tokens (Text) The tokens for uploaded files. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(Tokens).

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

UploadProgress

Reports the percentage progress of the file upload and an estimated time remaining

Parameters

File (UploadingFile) The file uploading

Client Actions

FilePondUpload_GetTokens()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePondUpload_Reset()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePond_HumanReadableFileSize()

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

Parameters

FileSize (Long 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, UploadedFileR 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, UploadedFileR 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. 

MaxParallelUploads (Integer) The maximum number of parallel uploads at a time

MaxParallelUploadsPerFile (Integer) The maximum number of parallel uploads at a time for a given file. Only applicable to SQL Server databases, other databases reset it to 1 so file chunks upload sequentially. Default = 4.

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.

MustMatchFilenameRegex (Text) If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex (Text) If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive (Boolean) If either match filename options are specified, this will control if the match is case sensitive

ShowCredits (Boolean) If True, shows the credits in faint text below the upload widget. Default = True

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.

UploadedFileR

A file uploaded to the website.

Attributes

UniqueToken (Text) The token representing the file

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

BinaryContent (Binary Data) The content of the uploaded file.

UploadingFile

A file where upload is in progress. Used by the UploadedStarted and UploadProgress callbacks.

Attributes

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

ProgressPercent (Decimal) The percentage progress of the file upload.

EstimatedTimeRemaining (Integer) The estimated number of seconds until the file upload completes. 

Roadmap

Please contact me if you would like specific features included, or an upcoming feature would be genuinely helpful for you. I cannot promise I will implement, but all suggestions will be given fair consideration.

Next release

• Option to retrieve files from a background task rather than requiring it to be in the user's session.
• Improved handling of empty files.

Future releases

• Option to compress large files prior to upload.
• Configuration options allowing for languages other than English.
• Support for Internet Explorer 11- depends on support in OutSystems React Web Apps (Thanks Jan Ancukiewicz!)

Team Membership Agreement

As a member of this team, I agree to abide by the following rules:

• All communication between developers and users is polite, constructive and in good faith,
• New features are listed on the roadmap (in plugin documentation) and announced to the team before work begins,
• Any disagreements about a feature must be resolved before a change is published,
• New features in extensions are unit tested in the extension,
• New versions are tested by the developer before being published,
• New versions are published in "Under Development" status until a team member has given it a successful test before being changed to "Stable",
• Any new teams members must agree to the ground rules. If a team member is not able to follow the ground rules, they must leave the team.

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

• How to Use ReactFilePondUpload
• Scenarios
• Note on Internet Explorer 11 (not supported)
• Add Image Editing
• Site Properties
• Widgets
• Actions
• Structures
• Roadmap
• Team Membership Agreement

How to Use ReactFilePondUpload

Follow these steps to use the Upload Block or the Auto Upload block in your application.

Upload Block

1. Create the dependencies that allow the usage of the component

The UploadBlock is used to upload files from the client side. The user drags multiple files onto the file upload widget, either by selecting the files or dragging a folder with the need of the user to click on a submit button. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the UploadBlock on the screen

Create a form and place the UploadBlock inside to be able to upload a file.

An example is provided in the picture UploadBlock in form below

UploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

Create a client action, name it "GetUploadConfig" and set the function to yes.

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

So 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(), as can be seen in the picture below as a sample.

AddNoteOnClick action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles() to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

Auto Upload Block

1. Create the dependencies that allow the usage of the component

The AutoUploadBlock is used to upload files from the client side. The user drags multiple files onto the automatic file upload widget, without requiring the user to click a submit button. Uploaded files are provided via the Uploaded event. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the AutoUploadBlock

Create a form and place the AutoUploadBlock inside to be able to upload a file.

An example is provided in the picture AutoUploadBlock in form below

AutoUploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

These configurations will allow manipulation of the upload. Such as:

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: Set a different layout render mode. Can be either 'integrated', 'compact', 'circle', 'integrated circle' or 'compact 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

On the client side, handle the Uploaded event, passing the Tokens parameter to a server action to process files, as can be seen in the picture below as a sample.

HandleUploadFiles action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So, on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles(UploadTokens) to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Upon retrieving the uploaded files, their temporary copy will be removed. Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

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.

Scenario #5 - Multiple file upload widgets on the one page

When multiple FilePondUpload blocks are on the same page, the WidgetId of the block must be specified as a parameter to the block and client actions FilePondUpload_GetTokens and FilePondUpload_Reset.

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

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

TraceLog

Set to True to enable trace logging for server actions.

UploadFileExpiryMinutes

Upload files are removed if they are older than this number of minutes.

UploadFileTimeoutSeconds

The timeout for the server action called from the client that uploads a file chunk. Valid values are 30, 60, 120, and 180. Any other values will fail.

If timeouts are occurring, increase this timeout value.

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.

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

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().

Events

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

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.

Parameters

WidgetId (Text) The id of the auto upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

Events

Uploaded 

A file or files have completed uploading. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(UploadTokens), then process the files as required.

Note, due to the asynchronous nature of uploads, GetTokens() may return multiple tokens, and retrieve multiple files, and the next event may then return no tokens and retrieve no files.

Ensure file processing will handle multiple or zero files.

Parameters

Tokens (Text) The tokens for uploaded files. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(Tokens).

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

UploadProgress

Reports the percentage progress of the file upload and an estimated time remaining

Parameters

File (UploadingFile) The file uploading

Client Actions

FilePondUpload_GetTokens()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePondUpload_Reset()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePond_HumanReadableFileSize()

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

Parameters

FileSize (Long 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, UploadedFileR 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, UploadedFileR 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. 

MaxParallelUploads (Integer) The maximum number of parallel uploads at a time

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.

MustMatchFilenameRegex (Text) If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex (Text) If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive (Boolean) If either match filename options are specified, this will control if the match is case sensitive

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.

UploadedFileR

A file uploaded to the website.

Attributes

UniqueToken (Text) The token representing the file

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

BinaryContent (Binary Data) The content of the uploaded file.

UploadingFile

A file where upload is in progress. Used by the UploadedStarted and UploadProgress callbacks.

Attributes

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

ProgressPercent (Decimal) The percentage progress of the file upload.

EstimatedTimeRemaining (Integer) The estimated number of seconds until the file upload completes. 

Roadmap

Please contact me if you would like specific features included, or an upcoming feature would be genuinely helpful for you. I cannot promise I will implement, but all suggestions will be given fair consideration.

Next release

• Option to retrieve files from a background task rather than requiring it to be in the user's session.
• Improved handling of empty files.

Future releases

• Option to compress large files prior to upload.
• Configuration options allowing for languages other than English.
• Support for Internet Explorer 11- depends on support in OutSystems React Web Apps (Thanks Jan Ancukiewicz!)

Team Membership Agreement

As a member of this team, I agree to abide by the following rules:

• All communication between developers and users is polite, constructive and in good faith,
• New features are listed on the roadmap (in plugin documentation) and announced to the team before work begins,
• Any disagreements about a feature must be resolved before a change is published,
• New features in extensions are unit tested in the extension,
• New versions are tested by the developer before being published,
• New versions are published in "Under Development" status until a team member has given it a successful test before being changed to "Stable",
• Any new teams members must agree to the ground rules. If a team member is not able to follow the ground rules, they must leave the team.

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

• How to Use ReactFilePondUpload
• Scenarios
• Note on Internet Explorer 11 (not supported)
• Add Image Editing
• Site Properties
• Widgets
• Actions
• Structures
• Roadmap
• Team Membership Agreement

How to Use ReactFilePondUpload

Follow these steps to use the Upload Block or the Auto Upload block in your application.

Upload Block

1. Create the dependencies that allow the usage of the component

The UploadBlock is used to upload files from the client side. The user drags multiple files onto the file upload widget, either by selecting the files or dragging a folder with the need of the user to click on a submit button. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the UploadBlock on the screen

Create a form and place the UploadBlock inside to be able to upload a file.

An example is provided in the picture UploadBlock in form below

UploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

Create a client action, name it "GetUploadConfig" and set the function to yes.

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

So 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(), as can be seen in the picture below as a sample.

AddNoteOnClick action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles() to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

Auto Upload Block

1. Create the dependencies that allow the usage of the component

The AutoUploadBlock is used to upload files from the client side. The user drags multiple files onto the automatic file upload widget, without requiring the user to click a submit button. Uploaded files are provided via the Uploaded event. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the AutoUploadBlock

Create a form and place the AutoUploadBlock inside to be able to upload a file.

An example is provided in the picture AutoUploadBlock in form below

AutoUploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

These configurations will allow manipulation of the upload. Such as:

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: Set a different layout render mode. Can be either 'integrated', 'compact', 'circle', 'integrated circle' or 'compact 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

On the client side, handle the Uploaded event, passing the Tokens parameter to a server action to process files, as can be seen in the picture below as a sample.

HandleUploadFiles action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So, on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles(UploadTokens) to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Upon retrieving the uploaded files, their temporary copy will be removed. Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

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.

Scenario #5 - Multiple file upload widgets on the one page

When multiple FilePondUpload blocks are on the same page, the WidgetId of the block must be specified as a parameter to the block and client actions FilePondUpload_GetTokens and FilePondUpload_Reset.

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

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

TraceLog

Set to True to enable trace logging for server actions.

UploadFileExpiryMinutes

Upload files are removed if they are older than this number of minutes.

UploadFileTimeoutSeconds

The timeout for the server action called from the client that uploads a file chunk. Valid values are 30, 60, 120, and 180. Any other values will fail.

If timeouts are occurring, increase this timeout value.

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.

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

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().

Events

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

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.

Parameters

WidgetId (Text) The id of the auto upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

Events

Uploaded 

A file or files have completed uploading. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(UploadTokens), then process the files as required.

Note, due to the asynchronous nature of uploads, GetTokens() may return multiple tokens, and retrieve multiple files, and the next event may then return no tokens and retrieve no files.

Ensure file processing will handle multiple or zero files.

Parameters

Tokens (Text) The tokens for uploaded files. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(Tokens).

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

UploadProgress

Reports the percentage progress of the file upload and an estimated time remaining

Parameters

File (UploadingFile) The file uploading

Client Actions

FilePondUpload_GetTokens()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePondUpload_Reset()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePond_HumanReadableFileSize()

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

Parameters

FileSize (Long 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, UploadedFileR 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, UploadedFileR 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. 

MaxParallelUploads (Integer) The maximum number of parallel uploads at a time

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.

MustMatchFilenameRegex (Text) If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex (Text) If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive (Boolean) If either match filename options are specified, this will control if the match is case sensitive

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.

UploadedFileR

A file uploaded to the website.

Attributes

UniqueToken (Text) The token representing the file

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

BinaryContent (Binary Data) The content of the uploaded file.

UploadingFile

A file where upload is in progress. Used by the UploadedStarted and UploadProgress callbacks.

Attributes

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

ProgressPercent (Decimal) The percentage progress of the file upload.

EstimatedTimeRemaining (Integer) The estimated number of seconds until the file upload completes. 

Roadmap

Please contact me if you would like specific features included, or an upcoming feature would be genuinely helpful for you. I cannot promise I will implement, but all suggestions will be given fair consideration.

Next release

• Option to retrieve files from a background task rather than requiring it to be in the user's session.
• Improved handling of empty files.

Future releases

• Option to compress large files prior to upload.
• Configuration options allowing for languages other than English.
• Support for Internet Explorer 11- depends on support in OutSystems React Web Apps (Thanks Jan Ancukiewicz!)

Team Membership Agreement

As a member of this team, I agree to abide by the following rules:

• All communication between developers and users is polite, constructive and in good faith,
• New features are listed on the roadmap (in plugin documentation) and announced to the team before work begins,
• Any disagreements about a feature must be resolved before a change is published,
• New features in extensions are unit tested in the extension,
• New versions are tested by the developer before being published,
• New versions are published in "Under Development" status until a team member has given it a successful test before being changed to "Stable",
• Any new teams members must agree to the ground rules. If a team member is not able to follow the ground rules, they must leave the team.

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

• How to Use ReactFilePondUpload
• Scenarios
• Note on Internet Explorer 11 (not supported)
• Add Image Editing
• Site Properties
• Widgets
• Actions
• Structures
• Roadmap
• Team Membership Agreement

How to Use ReactFilePondUpload

Follow these steps to use the Upload Block or the Auto Upload block in your application.

Upload Block

1. Create the dependencies that allow the usage of the component

The UploadBlock is used to upload files from the client side. The user drags multiple files onto the file upload widget, either by selecting the files or dragging a folder with the need of the user to click on a submit button. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the UploadBlock on the screen

Create a form and place the UploadBlock inside to be able to upload a file.

An example is provided in the picture UploadBlock in form below

UploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

Create a client action, name it "GetUploadConfig" and set the function to yes.

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

So 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(), as can be seen in the picture below as a sample.

AddNoteOnClick action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles() to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

Auto Upload Block

1. Create the dependencies that allow the usage of the component

The AutoUploadBlock is used to upload files from the client side. The user drags multiple files onto the automatic file upload widget, without requiring the user to click a submit button. Uploaded files are provided via the Uploaded event. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the AutoUploadBlock

Create a form and place the AutoUploadBlock inside to be able to upload a file.

An example is provided in the picture AutoUploadBlock in form below

AutoUploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

These configurations will allow manipulation of the upload. Such as:

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: Set a different layout render mode. Can be either 'integrated', 'compact', 'circle', 'integrated circle' or 'compact 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

On the client side, handle the Uploaded event, passing the Tokens parameter to a server action to process files, as can be seen in the picture below as a sample.

HandleUploadFiles action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So, on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles(UploadTokens) to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Upon retrieving the uploaded files, their temporary copy will be removed. Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

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.

Scenario #5 - Multiple file upload widgets on the one page

When multiple FilePondUpload blocks are on the same page, the WidgetId of the block must be specified as a parameter to the block and client actions FilePondUpload_GetTokens and FilePondUpload_Reset.

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

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

TraceLog

Set to True to enable trace logging for server actions.

UploadFileExpiryMinutes

Upload files are removed if they are older than this number of minutes.

UploadFileTimeoutSeconds

The timeout for the server action called from the client that uploads a file chunk. Valid values are 30, 60, 120, and 180. Any other values will fail.

If timeouts are occurring, increase this timeout value.

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.

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

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().

Events

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

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.

Parameters

WidgetId (Text) The id of the auto upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

Events

Uploaded 

A file or files have completed uploading. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(UploadTokens), then process the files as required.

Note, due to the asynchronous nature of uploads, GetTokens() may return multiple tokens, and retrieve multiple files, and the next event may then return no tokens and retrieve no files.

Ensure file processing will handle multiple or zero files.

Parameters

Tokens (Text) The tokens for uploaded files. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(Tokens).

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

UploadProgress

Reports the percentage progress of the file upload and an estimated time remaining

Parameters

File (UploadingFile) The file uploading

Client Actions

FilePondUpload_GetTokens()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePondUpload_Reset()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePond_HumanReadableFileSize()

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

Parameters

FileSize (Long 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, UploadedFileR 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, UploadedFileR 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. 

MaxParallelUploads (Integer) The maximum number of parallel uploads at a time

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.

MustMatchFilenameRegex (Text) If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex (Text) If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive (Boolean) If either match filename options are specified, this will control if the match is case sensitive

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.

UploadedFileR

A file uploaded to the website.

Attributes

UniqueToken (Text) The token representing the file

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

BinaryContent (Binary Data) The content of the uploaded file.

UploadingFile

A file where upload is in progress. Used by the UploadedStarted and UploadProgress callbacks.

Attributes

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

ProgressPercent (Decimal) The percentage progress of the file upload.

EstimatedTimeRemaining (Integer) The estimated number of seconds until the file upload completes. 

Roadmap

Please contact me if you would like specific features included, or an upcoming feature would be genuinely helpful for you. I cannot promise I will implement, but all suggestions will be given fair consideration.

Next release

• Option to retrieve files from a background task rather than requiring it to be in the user's session.
• Improved handling of empty files.

Future releases

• Option to compress large files prior to upload.
• Configuration options allowing for languages other than English.
• Support for Internet Explorer 11- depends on support in OutSystems React Web Apps (Thanks Jan Ancukiewicz!)

Team Membership Agreement

As a member of this team, I agree to abide by the following rules:

• All communication between developers and users is polite, constructive and in good faith,
• New features are listed on the roadmap (in plugin documentation) and announced to the team before work begins,
• Any disagreements about a feature must be resolved before a change is published,
• New features in extensions are unit tested in the extension,
• New versions are tested by the developer before being published,
• New versions are published in "Under Development" status until a team member has given it a successful test before being changed to "Stable",
• Any new teams members must agree to the ground rules. If a team member is not able to follow the ground rules, they must leave the team.

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

• How to Use ReactFilePondUpload
• Scenarios
• Note on Internet Explorer 11 (not supported)
• Add Image Editing
• Site Properties
• Widgets
• Actions
• Structures
• Roadmap
• Team Membership Agreement

How to Use ReactFilePondUpload

Follow these steps to use the Upload Block or the Auto Upload block in your application.

Upload Block

1. Create the dependencies that allow the usage of the component

The UploadBlock is used to upload files from the client side. The user drags multiple files onto the file upload widget, either by selecting the files or dragging a folder with the need of the user to click on a submit button. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the UploadBlock on the screen

Create a form and place the UploadBlock inside to be able to upload a file.

An example is provided in the picture UploadBlock in form below

UploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

Create a client action, name it "GetUploadConfig" and set the function to yes.

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

So 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(), as can be seen in the picture below as a sample.

AddNoteOnClick action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles() to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

Auto Upload Block

1. Create the dependencies that allow the usage of the component

The AutoUploadBlock is used to upload files from the client side. The user drags multiple files onto the automatic file upload widget, without requiring the user to click a submit button. Uploaded files are provided via the Uploaded event. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the AutoUploadBlock

Create a form and place the AutoUploadBlock inside to be able to upload a file.

An example is provided in the picture AutoUploadBlock in form below

AutoUploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

These configurations will allow manipulation of the upload. Such as:

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

On the client side, handle the Uploaded event, passing the Tokens parameter to a server action to process files, as can be seen in the picture below as a sample.

HandleUploadFiles action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So, on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles(UploadTokens) to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Upon retrieving the uploaded files, their temporary copy will be removed. Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

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.

Scenario #5 - Multiple file upload widgets on the one page

When multiple FilePondUpload blocks are on the same page, the WidgetId of the block must be specified as a parameter to the block and client actions FilePondUpload_GetTokens and FilePondUpload_Reset.

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

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

TraceLog

Set to True to enable trace logging for server actions.

UploadFileExpiryMinutes

Upload files are removed if they are older than this number of minutes.

UploadFileTimeoutSeconds

The timeout for the server action called from the client that uploads a file chunk. Valid values are 30, 60, 120, and 180. Any other values will fail.

If timeouts are occurring, increase this timeout value.

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.

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

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().

Events

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

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.

Parameters

WidgetId (Text) The id of the auto upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

Events

Uploaded 

A file or files have completed uploading. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(UploadTokens), then process the files as required.

Note, due to the asynchronous nature of uploads, GetTokens() may return multiple tokens, and retrieve multiple files, and the next event may then return no tokens and retrieve no files.

Ensure file processing will handle multiple or zero files.

Parameters

Tokens (Text) The tokens for uploaded files. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(Tokens).

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

UploadProgress

Reports the percentage progress of the file upload and an estimated time remaining

Parameters

File (UploadingFile) The file uploading

Client Actions

FilePondUpload_GetTokens()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePondUpload_Reset()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePond_HumanReadableFileSize()

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

Parameters

FileSize (Long 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, UploadedFileR 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, UploadedFileR 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. 

MaxParallelUploads (Integer) The maximum number of parallel uploads at a time

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.

MustMatchFilenameRegex (Text) If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex (Text) If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive (Boolean) If either match filename options are specified, this will control if the match is case sensitive

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.

UploadedFileR

A file uploaded to the website.

Attributes

UniqueToken (Text) The token representing the file

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

BinaryContent (Binary Data) The content of the uploaded file.

UploadingFile

A file where upload is in progress. Used by the UploadedStarted and UploadProgress callbacks.

Attributes

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

ProgressPercent (Decimal) The percentage progress of the file upload.

EstimatedTimeRemaining (Integer) The estimated number of seconds until the file upload completes. 

Roadmap

Please contact me if you would like specific features included, or an upcoming feature would be genuinely helpful for you. I cannot promise I will implement, but all suggestions will be given fair consideration.

Next release

• Option to retrieve files from a background task rather than requiring it to be in the user's session.
• Improved handling of empty files.

Future releases

• Option to compress large files prior to upload.
• Configuration options allowing for languages other than English.
• Support for Internet Explorer 11- depends on support in OutSystems React Web Apps (Thanks Jan Ancukiewicz!)

Team Membership Agreement

As a member of this team, I agree to abide by the following rules:

• All communication between developers and users is polite, constructive and in good faith,
• New features are listed on the roadmap (in plugin documentation) and announced to the team before work begins,
• Any disagreements about a feature must be resolved before a change is published,
• New features in extensions are unit tested in the extension,
• New versions are tested by the developer before being published,
• New versions are published in "Under Development" status until a team member has given it a successful test before being changed to "Stable",
• Any new teams members must agree to the ground rules. If a team member is not able to follow the ground rules, they must leave the team.

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

• How to Use ReactFilePondUpload
• Scenarios
• Note on Internet Explorer 11 (not supported)
• Add Image Editing
• Site Properties
• Widgets
• Actions
• Structures
• Roadmap
• Team Membership Agreement

How to Use ReactFilePondUpload

Follow these steps to use the Upload Block or the Auto Upload block in your application.

Upload Block

1. Create the dependencies that allow the usage of the component

The UploadBlock is used to upload files from the client side. The user drags multiple files onto the file upload widget, either by selecting the files or dragging a folder with the need of the user to click on a submit button. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the UploadBlock on the screen

Create a form and place the UploadBlock inside to be able to upload a file.

An example is provided in the picture UploadBlock in form below

UploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

Create a client action, name it "GetUploadConfig" and set the function to yes.

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

So 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(), as can be seen in the picture below as a sample.

AddNoteOnClick action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles() to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

Auto Upload Block

1. Create the dependencies that allow the usage of the component

The AutoUploadBlock is used to upload files from the client side. The user drags multiple files onto the automatic file upload widget, without requiring the user to click a submit button. Uploaded files are provided via the Uploaded event. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the AutoUploadBlock

Create a form and place the AutoUploadBlock inside to be able to upload a file.

An example is provided in the picture AutoUploadBlock in form below

AutoUploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

These configurations will allow manipulation of the upload. Such as:

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

On the client side, handle the Uploaded event, passing the Tokens parameter to a server action to process files, as can be seen in the picture below as a sample.

HandleUploadFiles action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So, on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles(UploadTokens) to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Upon retrieving the uploaded files, their temporary copy will be removed. Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

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.

Scenario #5 - Multiple file upload widgets on the one page

When multiple FilePondUpload blocks are on the same page, the WidgetId of the block must be specified as a parameter to the block and client actions FilePondUpload_GetTokens and FilePondUpload_Reset.

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

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

TraceLog

Set to True to enable trace logging for server actions.

UploadFileExpiryMinutes

Upload files are removed if they are older than this number of minutes.

UploadFileTimeoutSeconds

The timeout for the server action called from the client that uploads a file chunk. Valid values are 30, 60, 120, and 180. Any other values will fail.

If timeouts are occurring, increase this timeout value.

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.

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

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().

Events

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

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.

Parameters

WidgetId (Text) The id of the auto upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

Events

Uploaded 

A file or files have completed uploading. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(UploadTokens), then process the files as required.

Note, due to the asynchronous nature of uploads, GetTokens() may return multiple tokens, and retrieve multiple files, and the next event may then return no tokens and retrieve no files.

Ensure file processing will handle multiple or zero files.

Parameters

Tokens (Text) The tokens for uploaded files. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(Tokens).

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

UploadProgress

Reports the percentage progress of the file upload and an estimated time remaining

Parameters

File (UploadingFile) The file uploading

Client Actions

FilePondUpload_GetTokens()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePondUpload_Reset()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePond_HumanReadableFileSize()

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

Parameters

FileSize (Long 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, UploadedFileR 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, UploadedFileR 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. 

MaxParallelUploads (Integer) The maximum number of parallel uploads at a time

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.

MustMatchFilenameRegex (Text) If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex (Text) If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive (Boolean) If either match filename options are specified, this will control if the match is case sensitive

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.

UploadedFileR

A file uploaded to the website.

Attributes

UniqueToken (Text) The token representing the file

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

BinaryContent (Binary Data) The content of the uploaded file.

UploadingFile

A file where upload is in progress. Used by the UploadedStarted and UploadProgress callbacks.

Attributes

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

ProgressPercent (Decimal) The percentage progress of the file upload.

EstimatedTimeRemaining (Integer) The estimated number of seconds until the file upload completes. 

Roadmap

Please contact me if you would like specific features included, or an upcoming feature would be genuinely helpful for you. I cannot promise I will implement, but all suggestions will be given fair consideration.

Next release

• Option to retrieve files from a background task rather than requiring it to be in the user's session.
• Improved handling of empty files.

Future releases

• Option to compress large files prior to upload.
• Configuration options allowing for languages other than English.
• Support for Internet Explorer 11- depends on support in OutSystems React Web Apps (Thanks Jan Ancukiewicz!)

Team Membership Agreement

As a member of this team, I agree to abide by the following rules:

• All communication between developers and users is polite, constructive and in good faith,
• New features are listed on the roadmap (in plugin documentation) and announced to the team before work begins,
• Any disagreements about a feature must be resolved before a change is published,
• New features in extensions are unit tested in the extension,
• New versions are tested by the developer before being published,
• New versions are published in "Under Development" status until a team member has given it a successful test before being changed to "Stable",
• Any new teams members must agree to the ground rules. If a team member is not able to follow the ground rules, they must leave the team.

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

• How to Use ReactFilePondUpload
• Scenarios
• Note on Internet Explorer 11 (not supported)
• Add Image Editing
• Site Properties
• Widgets
• Actions
• Structures
• Roadmap
• Team Membership Agreement

How to Use ReactFilePondUpload

Follow these steps to use the Upload Block or the Auto Upload block in your application.

Upload Block

1. Create the dependencies that allow the usage of the component

The UploadBlock is used to upload files from the client side. The user drags multiple files onto the file upload widget, either by selecting the files or dragging a folder with the need of the user to click on a submit button. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the UploadBlock on the screen

Create a form and place the UploadBlock inside to be able to upload a file.

An example is provided in the picture UploadBlock in form below

UploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

Create a client action, name it "GetUploadConfig" and set the function to yes.

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

So 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(), as can be seen in the picture below as a sample.

AddNoteOnClick action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles() to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

Auto Upload Block

1. Create the dependencies that allow the usage of the component

The AutoUploadBlock is used to upload files from the client side. The user drags multiple files onto the automatic file upload widget, without requiring the user to click a submit button. Uploaded files are provided via the Uploaded event. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the AutoUploadBlock

Create a form and place the AutoUploadBlock inside to be able to upload a file.

An example is provided in the picture AutoUploadBlock in form below

AutoUploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

These configurations will allow manipulation of the upload. Such as:

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript. Only set to True when debugging. Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

On the client side, handle the Uploaded event, passing the Tokens parameter to a server action to process files, as can be seen in the picture below as a sample.

HandleUploadFiles action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So, on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles(UploadTokens) to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Upon retrieving the uploaded files, their temporary copy will be removed. Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server. You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

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.

Scenario #5 - Multiple file upload widgets on the one page

When multiple FilePondUpload blocks are on the same page, the WidgetId of the block must be specified as a parameter to the block and client actions FilePondUpload_GetTokens and FilePondUpload_Reset.

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

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

TraceLog

Set to True to enable trace logging for server actions.

UploadFileExpiryMinutes

Upload files are removed if they are older than this number of minutes.

UploadFileTimeoutSeconds

The timeout for the server action called from the client that uploads a file chunk. Valid values are 30, 60, 120, and 180. Any other values will fail.

If timeouts are occurring, increase this timeout value.

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.

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

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().

Events

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

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.

Parameters

WidgetId (Text) The id of the auto upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

Events

Uploaded 

A file or files have completed uploading. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(UploadTokens), then process the files as required.

Note, due to the asynchronous nature of uploads, GetTokens() may return multiple tokens, and retrieve multiple files, and the next event may then return no tokens and retrieve no files.

Ensure file processing will handle multiple or zero files.

Parameters

Tokens (Text) The tokens for uploaded files. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(Tokens).

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

UploadProgress

Reports the percentage progress of the file upload and an estimated time remaining

Parameters

File (UploadingFile) The file uploading

Client Actions

FilePondUpload_GetTokens()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePondUpload_Reset()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePond_HumanReadableFileSize()

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

Parameters

FileSize (Long 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, UploadedFileR 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, UploadedFileR 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. 

MaxParallelUploads (Integer) The maximum number of parallel uploads at a time

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.

MustMatchFilenameRegex (Text) If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex (Text) If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive (Boolean) If either match filename options are specified, this will control if the match is case sensitive

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.

UploadedFileR

A file uploaded to the website.

Attributes

UniqueToken (Text) The token representing the file

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

BinaryContent (Binary Data) The content of the uploaded file.

UploadingFile

A file where upload is in progress. Used by the UploadedStarted and UploadProgress callbacks.

Attributes

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

ProgressPercent (Decimal) The percentage progress of the file upload.

EstimatedTimeRemaining (Integer) The estimated number of seconds until the file upload completes. 

Roadmap

Please contact me if you would like specific features included, or an upcoming feature would be genuinely helpful for you. I cannot promise I will implement, but all suggestions will be given fair consideration.

Next release

• Option to retrieve files from a background task rather than requiring it to be in the user's session.
• Improved handling of empty files.

Future releases

• Option to compress large files prior to upload.
• Configuration options allowing for languages other than English.
• Support for Internet Explorer 11- depends on support in OutSystems React Web Apps (Thanks Jan Ancukiewicz!)

Team Membership Agreement

As a member of this team, I agree to abide by the following rules:

• All communication between developers and users is polite, constructive and in good faith,
• New features are listed on the roadmap (in plugin documentation) and announced to the team before work begins,
• Any disagreements about a feature must be resolved before a change is published,
• New features in extensions are unit tested in the extension,
• New versions are tested by the developer before being published,
• New versions are published in "Under Development" status until a team member has given it a successful test before being changed to "Stable",
• Any new teams members must agree to the ground rules. If a team member is not able to follow the ground rules, they must leave the team.

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

• How to Use ReactFilePondUpload
• Scenarios
• Note on Internet Explorer 11 (not supported)
• Add Image Editing
• Site Properties
• Widgets
• Actions
• Structures
• Roadmap
• Team Membership Agreement

How to Use ReactFilePondUpload

Follow these steps to use the Upload Block or the Auto Upload block in your application.

Upload Block

1. Create the dependencies that allow the usage of the component

The UploadBlock is used to upload files from the client side. The user drags multiple files onto the file upload widget, either by selecting the files or dragging a folder with the need of the user to click on a submit button. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the UploadBlock on the screen

Create a form and place the UploadBlock inside to be able to upload a file.

An example is provided in the picture UploadBlock in form below

UploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

Create a client action, name it "GetUploadConfig" and set the function to yes.

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript.  Only set to True when debugging.  Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

So 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(), as can be seen in the picture below as a sample.

AddNoteOnClick action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles() to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server.  You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

Auto Upload Block

1. Create the dependencies that allow the usage of the component

The AutoUploadBlock is used to upload files from the client side. The user drags multiple files onto the automatic file upload widget, without requiring the user to click a submit button. Uploaded files are provided via the Uploaded event. The files show upload progress as well as a thumbnail if the files are images.

To enable it establishes a dependency in your application according to the picture below.

Manage Dependencies

2. Using the AutoUploadBlock

Create a form and place the AutoUploadBlock inside to be able to upload a file.

An example is provided in the picture AutoUploadBlock in form below

AutoUploadBlock in Form

3. Understand and configure the block with a FilePondUploadConfig structure

These configurations will allow manipulation of the upload. Such as:

Name: Name to use for the internal file upload form control.

LabelIdle: Label shown to indicate this is a drop area. Defaults to 'Drag & Drop your files or <span class="filepond--label-action"> Browse </span>'.

MaxFiles: Maximum number of files to upload. Defaults to zero. Zero means unrestricted.

MaxParallelUploads: The maximum number of parallel uploads at a time.

MaxFileSizeMb: The maximum size of a file in megabytes. If zero, there is no maximum.

AcceptedFileTypes: Mime types accepted for upload. If empty, all file types are accepted.

MustMatchFilenameRegex: If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex: If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive: If either match filename options are specified, this will control if the match is case sensitive.

AllowBrowse: Allow the user to browse for files. Default = True.

AllowDrop: Allow the user to drop files. Default = True.

DropOnPage: Catch all files dropped on the webpage. Default = False.

DropValidation: When enabled, files are validated before they are dropped. A file is not added when it’s invalid. Default = False.

InstantUpload: Upload immediately the file is selected or dropped.

PreviewImages: If the file is an image, show a preview.

ImageEdit: Edit images. Requires the Doka image plugin.

InstantImageEdit: Edit images as soon as they are uploaded. Requires the Doka image editing library. See ImageEdit configuration option and ReactFilePondUpload forge component documentation for further detail.

DisableSubmit: Disable the submit button during file upload. Adds attribute disabled="disabled" when files are uploading and removes when done.

SubmitButtonId: The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL: The url for the default file. Set InstantUpload to False to prevent immediate upload.

StyleAspectRatio: 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 an empty string.

StylePanelLayout: 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 an empty string.

Log: Log messages in javascript.  Only set to True when debugging.  Set to False for normal production use.

Once those configurations are understood, let's configure them.

Create a client action, name it "GetUploadConfig" and set the function to yes to later associate the button.

Fill the properties as below:

GetUploadConfig action

Configuration

4. Create a flow to get the Tokens

It's mandatory to get the tokens to be able to upload a file. Each uploaded file is allocated a token which can be used to retrieve the file.

On the client side, handle the Uploaded event, passing the Tokens parameter to a server action to process files, as can be seen in the picture below as a sample.

HandleUploadFiles action

5. Create a flow to pass the tokens

To retrieve the uploaded file we need to pass the tokens.

So, on the server side, pass the tokens to server action FilePondUpload_GetUploadedFiles(UploadTokens) to retrieve the uploaded files, as can be seen in the picture below as a sample.

AddNote action

Upon retrieving the uploaded files, their temporary copy will be removed. Uploaded files last for 30 minutes, or until they are retrieved by FilePondUpload_GetUploadedFiles()

NOTE: This component use a site properties "UploadFileExpiryMinutes" and "UploadFileTimeoutSeconds", that can be accessed through the service center. "UploadFileExpiryMinutes" controls how long uploaded files remain until they expire and are removed. "UploadFileTimeoutSeconds" controls the timeout for the upload to the server.  You can change it's value accordingly with your preferences to the sizes of uploading files. Valid values are in seconds: Valid values are 30, 60, 120, and 180. Any other values will fail. If timeouts are occurring, increase this timeout value.

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.

Scenario #5 - Multiple file upload widgets on the one page

When multiple FilePondUpload blocks are on the same page, the WidgetId of the block must be specified as a parameter to the block and client actions FilePondUpload_GetTokens and FilePondUpload_Reset.

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

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

TraceLog

Set to True to enable trace logging for server actions.

UploadFileExpiryMinutes

Upload files are removed if they are older than this number of minutes.

UploadFileTimeoutSeconds

The timeout for the server action called from the client that uploads a file chunk.  Valid values are 30, 60, 120, and 180.  Any other values will fail.

If timeouts are occurring, increase this timeout value.

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.

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

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().

Events

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

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.

Parameters

WidgetId (Text) The id of the auto upload block, required when there are multiple FilePondUpload blocks on a single page

Config (FilePondUploadConfig) Configuration for the upload block

Events

Uploaded 

A file or files have completed uploading.  Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(UploadTokens), then process the files as required.

Note, due to the asynchronous nature of uploads, GetTokens() may return multiple tokens, and retrieve multiple files, and the next event may then return no tokens and retrieve no files.

Ensure file processing will handle multiple or zero files.

Parameters

Tokens (Text) The tokens for uploaded files. Pass tokens to a server action which retrieves uploaded files with FilePondUpload_GetUploadedFiles(Tokens).

UploadStarted

The upload of a file has started

Parameters

File (UploadingFile) The file which started uploading

UploadProgress

Reports the percentage progress of the file upload and an estimated time remaining

Parameters

File (UploadingFile) The file uploading

Client Actions

FilePondUpload_GetTokens()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePondUpload_Reset()

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

Parameters

WidgetId (Text) The id of the upload block, required when there are multiple FilePondUpload blocks on a single page

FilePond_HumanReadableFileSize()

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

Parameters

FileSize (Long 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, UploadedFileR 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, UploadedFileR 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. 

MaxParallelUploads (Integer) The maximum number of parallel uploads at a time

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.

MustMatchFilenameRegex (Text) If specified, the filename must match this regular expression, otherwise upload will error.

MustNotMatchFilenameRegex (Text) If specified, upload will error if the filename matches this javascript regular expression.

MatchFilenameCaseSensitive (Boolean) If either match filename options are specified, this will control if the match is case sensitive

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.

UploadedFileR

A file uploaded to the website.

Attributes

UniqueToken (Text) The token representing the file

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

BinaryContent (Binary Data) The content of the uploaded file.

UploadingFile

A file where upload is in progress.  Used by the UploadedStarted and UploadProgress callbacks.

Attributes

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

FileSize (Long Integer) The size of the uploaded file in bytes

ProgressPercent (Decimal) The percentage progress of the file upload.

EstimatedTimeRemaining (Integer) The estimated number of seconds until the file upload completes. 

Roadmap

Please contact me if you would like specific features included, or an upcoming feature would be genuinely helpful for you.  I cannot promise I will implement, but all suggestions will be given fair consideration.

Next release

• Option to retrieve files from a background task rather than requiring it to be in the user's session.
• Improved handling of empty files.

Future releases

• Option to compress large files prior to upload.
• Configuration options allowing for languages other than English.
• Support for Internet Explorer 11- depends on support in OutSystems React Web Apps (Thanks Jan Ancukiewicz!)

Team Membership Agreement

As a member of this team, I agree to abide by the following rules:

• All communication between developers and users is polite, constructive and in good faith,
• New features are listed on the roadmap (in plugin documentation) and announced to the team before work begins,
• Any disagreements about a feature must be resolved before a change is published,
• New features in extensions are unit tested in the extension,
• New versions are tested by the developer before being published,
• New versions are published in "Under Development" status until a team member has given it a successful test before being changed to "Stable",
• Any new teams members must agree to the ground rules.  If a team member is not able to follow the ground rules, they must leave the team.