Give us feedback
filepondupload
Web icon

FilePondUpload

Stable version 2.0.4 (Compatible with OutSystems 11)
Published on 11 June 2021 by 
5.0
 (8 ratings)
filepondupload

FilePondUpload

Documentation
2.0.4

File upload widgets that allows AJAX submit, automatic upload with no further submit needed, with drag/drop and image preview that works on all browsers, including Internet Explorer 11 and Edge. It uses the awesome FilePond javascript library. https://pqina.nl/filepond/ by Rik Schennink.

The widget requires that users are logged in and will prevent uploads for anonymous users.


Contents

  • Scenarios
  • Add Image Editing
  • Site Properties
  • Widgets
  • Actions
  • Structures
  • Team Membership Agreement


Scenarios

The following are scenarios for use of the FilePondUpload plugin.

Scenario #1 - Multiple file upload

The user drags multiple files onto the file upload widget.  The files show upload progress as well as a thumbnail if the files are images. Once files are uploaded, the Save button becomes enabled.

The user clicks on the Save button and the files are stored.

Scenario #2 - Automatic file upload

The user drags multiple files onto the automatic file upload widget.  The files show upload progress as well as a thumbnail if the files are images. Each file is stored once it has been uploaded.

Scenario #3 - Single MS Excel file upload limited by size

The user drags an MSWord document onto the file upload widget.  The widget shows an error.

The user drags an MSExcel file that is larger than the allowed size.  The widget shows an error.

The user drags an MSExcel file that is within the allowed size.  The file is uploaded.

Scenario #4 - Edit an image before uploading*

The user drags an image file onto the file upload widget.

The image editor is displayed.

The user crops the image, sets the aspect ratio, applies a filter, adds a text label and clicks "Done".

The edited image is uploaded.

* Image editing requires the purchase of the Doka image editing library.  See below for how to add support for image editing.


Add Image Editing

As the Doka image editing library is a paid library, the Doka files must be added separately.

Follow these steps:

  1. Switch on image editing,
  2. Purchase Doka and download the files,
  3. Create a webblock and add files, and
  4. Include the webblock with the upload widget.

1. Switch on image editing

To switch on image editing, set configuration item ImageEdit = True, and optionally InstantImageEdit = True.

2. Purchase Doka and download the files

Visit the Doka website and purchase a subscription.  Ensure the subscription matches your intended usage of the library.

Download and unzip the Doka files. You will need the files under folders .\bin\browser\ and .\bin\polyfill\ 

3. Create a webblock and add files

Using a webblock will ensure the Doka files required for image editing are available on the page.

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

4. Include the webblock with the upload widget

Whenever you use the file upload webblock, also drag on the FilePondUpload_DokaBlock webblock that you created in the previous step to allow image editing.


Site Properties

AllowAnonymousUpload

If True, upload will work even when there is no logged in user.  Otherwise, uploads will fail if there is no logged in user.  Defaults to False, so that anonymous uploads are prevented by default.  Enabling anonymous upload increases the risk of denial of service attack.  If it is to be used, additional steps should be taken, such as a captcha and restricting access to the site to an internal network, or a whitelisted IP address range.

UploadFileExpiryMinutes

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

Widgets

FileUploadBlock

This webblock provides drag and drop multiple file upload via an AJAX submit.  Retrieve uploaded files in the submit action using the FilePondUpload_GetUploadedFiles() action.  Configure the webblock with the FilePondUploadConfig structure.  See below for details of actions and structures.

How to use the web block:

  1. Drag the UploadBlock onto your page.
  2. Create The FilePondUploadConfiguration in the Preparation and pass it to the UploadBlock's Config parameter.
  3. Drag a text input control into the block.  This is for storing the tokens for uploaded files.
  4. On submit (can be ajax) call FilePondUpload_GetUploadedFiles() passing the submitted tokens to retrieve files.
  5. Upon retrieving the uploaded files, their temporary copy will be removed.
  6. A timer will remove temporary uploaded files older than 30 minutes.

AutoFileUploadBlock

This webblock provides drag and drop multiple file upload automatically without requiring the user to click a submit button. Uploaded files are provided via the FileUploaded event. Configure the webblock with the FilePondUploadConfig structure.

If one of the files errors during upload, it must be removed or re-uploaded before the FileUploaded event is triggered. 

See below for details of actions and structures.

How to use the web block:

  1. Drag the AutoUploadBlock onto your page.
  2. Create The FilePondUploadConfiguration in the Preparation and pass it to the AutoUploadBlock's Config parameter.
  3. Implement the FilesUploadedEvent event to retrieve files and process them.
  4. Upon retrieving the uploaded files, their temporary copy will be removed.
  5. A timer will remove temporary uploaded files older than 30 minutes.

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


Actions

The FilePondUpload plugin exposes the following actions.

FilePondUpload_CreateAcceptedFileTypes()

Helper function to create a list of accepted file types.

Parameters

FileType1 (Text) Mime file type eg "image/jpeg"

FileType2 (Text) Mime file type eg "image/jpeg"

FileType3 (Text) ...

FileType10 (Text) Mime file type eg "image/jpeg"

AcceptedFileTypes (Out, Text) Mime types accepted for upload. If empty, all file types are accepted. Array of accepted file types. Can be mime types or wild cards. For instance ['image/*'] will accept all images. ['image/png', 'image/jpeg'] will only accepts PNGs and JPEGs.

FilePondUpload_CreateCommonAcceptedFileTypes()

Helper action to create common accepted file types

Parameters

Images (Boolean) Include images "image/*"

Videos (Boolean) Include videos "video/*"

Text (Boolean) Include text "text/csv", "text/txt"

Documents (Boolean) Include documents "pdf, doc, docx, rft"

OfficeDocs (Boolean) Include MS Office documents "xls, xlsx, ppt, pptx"

FileType1 (Text) An additional mime file type eg "dsw"

FileType2 (Text) ...

FileType10 (Text)

AcceptedFileTypes (Out, Text) Mime types accepted for upload. If empty, all file types are accepted. Array of accepted file types. Can be mime types or wild cards. For instance ['image/*'] will accept all images. ['image/png', 'image/jpeg'] will only accepts PNGs and JPEGs.

FilePondUpload_GetUploadedFiles()

Retrieve files uploaded based on the specified FilePond tokens.  This action may only be called once, as the files are removed from temporary storage.  To access uploaded file details without removing them, use FilePondUpload_PeekUploadedFiles.  The FilePond tokens are populated in the hidden input textbox in the upload block placeholder.

Parameters

UploadTokens (Text) The variable held by the input text control in the UploadBlock placeholder.

FileList (Out, RequestFile List) Retrieve files uploaded based on the submitted hidden FilePond tokens.

FilePondUpload_PeekUploadedFiles()

Peek files uploaded based on the specified FilePond tokens.  The files are not removed from temporary storage.  Call FilePondUpload_GetUploadedFiles to retrieve the files the last time in order to remove them from temporary storage.

Parameters

UploadTokens (Text) The variable held by the input text control in the UploadBlock placeholder.

FileList (Out, RequestFile List) Retrieve files uploaded based on the submitted hidden FilePond tokens.


Structures

The FilePondUpload plugin exposes the following structure.

FilePondUploadConfig

A structure to hold configuration options for the FilePond upload blocks.

Attributes

Name (Text) Name to use for the internal file upload form control. Default='filePondUpload'

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

MaxFiles (Integer) Maximum number of files to upload. Defaults to zero.  Zero means unrestricted.

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

AcceptedFileTypes (Text List) Mime types accepted for upload. If empty, all file types are accepted.  Can be mime types or wild cards. For instance ['image/*'] will accept all images. ['image/png', 'image/jpeg'] will only accepts PNGs and JPEGs, ['*.doc', '*.docx'] will accept MSWord documents.  If empty all file types are accepted.

AllowBrowse (Boolean) Allow the user to browse for files. Default = True

AllowDrop (Boolean) Allow the user to drop files. Default = True

DropOnPage (Boolean) Catch all files dropped on the webpage. Default = False

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

InstantUpload (Boolean) Upload immediately the file is selected or dropped.

PreviewImages (Boolean) If the file is an image, show a preview

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

SubmitButtonId (Text) The HTML id of the submit button if DisableSubmit is set to yes.

DefaultFileURL (Text) The url for the initial file. When specified a file is displayed when the control is rendered. Consider setting InstantUpload=False when using this setting.

StyleAspectRatio (Text) Set a forced aspect ratio for the FilePond drop area. Useful to make the drop area take up a fixed amount of space. For example when cropping a single square image. Accepts human readable aspect ratios like '1:1'. Default is empty string.

StylePanelLayout (Text) Set a different layout render mode. Can be either 'integrated', 'compact', and/or 'circle'. Compact mode will remove padding, integrated mode is used to render FilePond as part of a bigger element. Circle mode adjusts the item position offsets so buttons and progress indicators don’t fall outside of the circular shape. Default is empty string.

Log (Boolean) Log messages in javascript. Useful for debugging. Default = False


The FilePondUpload plugin also uses the RequestFile structure from the HTTPRequestHandler extension.


RequestFile

A file uploaded to the website.

Attributes

FileName (Text) The name of the file uploaded

FileType (Text) The MIME type of the uploaded file

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

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


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.