🔗

Link to plugin page: https://zeroqode.com/plugin/aws-file-uploader-1533465056312x784389392881156100

Demo to preview the settings

🔗

Bubble Editor: https://bubble.is/page?type=page&name=aws-uploader&id=zeroqode-demo-02&tab=tabs-1

🔗

Live Demo: https://zeroqode-demo-02.bubbleapps.io/aws-uploader

Introduction

AWS File Uploader Plugin is a powerful tool, that allows you or your users to upload files from Bubble apps directly to your AWS (Amazon Web Services) S3 Bucket without any file size limits.

The plugin comes with the multi-file uploader element as well as the S3 objects element that returns a list of all the files uploaded to your AWS S3 bucket or a special folder on that bucket. The plugin also allows you to delete S3 objects from your bucket.

Each uploaded file has its own visual progress bar, so you or your users can see the upload progress. Plugin will also return a state with file URL(s), file size(s), last modified date(s), etc.

⚠️

Note: We use CORS Configuration and Bucket Policy for informative purposes only for the test case. For Access Permissions (CORS, Bucket Policy, Access Control List, etc.) please follow Amazon AWS's Setup Documentation to better understand your personal requirements. ❕https://docs.aws.amazon.com/AmazonS3/latest/dev/cors.html ❕https://docs.aws.amazon.com/AmazonS3/latest/user-guide/add-cors-configuration.htmlhttps://docs.aws.amazon.com/AmazonS3/latest/dev/example-bucket-policies.html

Prerequisites

To run this plugin you need the following to set it up on the AWS side:

1. AWS account

You can create the AWS account for free, just by visiting the following link: https://aws.amazon.com/console/

❕

Please note that the AWS Free Tier has limitations like the number of free GET/POST requests per 12 months: https://aws.amazon.com/s3/pricing/ https://aws.amazon.com/free/?nc1=h_ls&all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc

2. AWS Cognito Identity account

To create the AWS Cognito Identity, please follow the instructions below:

https://console.aws.amazon.com/cognito/home

❗

IMPORTANT! It is necessary to check the “Enable access to unauthenticated identities” checkbox, so the plugin can connect to it. You can go deeper, and set the Cognito identity some more secure way by yourself.

Now create IAM Roles for Cognito Identity (the values from inputs can be changed):

Once you have created the IAM Roles, you will get the identity pool ID which will be used in the plugin settings (shown in red on the screenshot below)

❗

IMPORTANT! Make sure your identity pool id is in the same region as your S3 bucket and the region is indicated with LOWER CASE in the plugin settings.

3. IAM Security Roles

In Your IAM Dashboard, you will find two new roles: https://console.aws.amazon.com/iam/home

❕

Tip: In our case, the values are “Cognito_zeroqodedemo02Auth_Role” and “Cognito_zeroqodedemo02Unauth_Role”.

You can edit policy details by clicking the "Edit Policy" button to the much-desired requirements, please be sure to check AWS's documentation on this one.

By clicking each role name you will open the role settings, where you need to replace the default policy with the following lines* :

javascript
{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Action": [
               "cognito-sync:*",
               "cognito-identity:*",
               "S3:*"
           ],
           "Resource": [
               "*"
           ]
       }
   ]
}

⚠️

*If necessary, you can set your own rules to make your application more secure, check AWS's documentation for more details.

4. AWS S3 Bucket located on the desired Server

You can manage your S3 storage using the link below:

https://s3.console.aws.amazon.com/s3/buckets?region=eu-central-1

To create a new S3 Bucket, click the “Create Bucket” button and follow the instructions.

The name and Region you choose on the first screen will then be used in the plugin setup.

You need to set the S3 Bucket available to the public, so everyone can view your files.

Setting CORS and Politics.

Is CORS Configuration Required Amazon S3 buckets require CORS configuration before you can perform operations on them. In some JavaScript environments, CORS may not be enforced and therefore configuring CORS is unnecessary. For example, if you host your application from an Amazon S3 bucket and access resources from *.s3.amazonaws.com or some other specific endpoint, your requests won't access an external domain. Therefore, this configuration doesn't require CORS. In this case, CORS is still used for services other than Amazon S3.

There are two ways for this:

First mode:

On a test page, add a button and add the action "Set standard Cross-origin". Add the "origin" and include the allowed methods to have access to your bucket and for can manipulation with files

Second mode: Manual setting

Add security to your AWS bucket by configuring policies on the 'Permissions' tab:

In the next steps, we'll show you how to set Access Control, Bucket Policy, and CORS policy to get started with basic security restrictions.

1. In the 'Block public access' area unlock public access to all for time being.

2. In the 'Bucket Policy' area you can configure the rules for security and privacy via Bucket Policy. Take a look at the "Action", "Resource" and "Condition" fields where we grant access to reading the objects from our bucket.

In this case, we are granting read file access only to users from our application domain, so if a user gets an image URL and tries to open it in a new tab or a new window, the bucket policy will block this request because we stated in the privacy rules that the link can be opened only from our domain:

Here's a code example (JSON):

javascript
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AddPerm",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",            
            "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*",
            "Condition": {
                "StringLike": {
                    "aws:Referer": "https://zeroqode-demo-02.bubbleapps.io/*"
                }
            }
        },
        {
            "Sid": "AddPerm2",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "*",
            "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
        }
    ]
}

YOUR-BUCKET-NAME - should be your S3 bucket name (ex: zeroqodedemo02).

You can find more Bucket Policy examples here. Feel free to try out other rules in order to improve your bucket security.

3. In the Access control list (ACL) area make sure that all the options look like the image below to match our configuration:

4. Use the 'Cross-origin resource sharing' area to configure the CORS policy for the S3 bucket.

To configure access from all domains, you can use the following JSON for CORS policy:

javascript
[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET",
            "PUT",
            "DELETE",
            "POST"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": [
            "ETag"
        ],
        "MaxAgeSeconds": 30000
    }
]

Setting the CORS policy like this will allow everyone to change anything in your bucket, but you can definitely go deeper and set it up more securely.

For example, you can use the following JSON for CORS policy to allow access from your domain only (change the allowed origin to the URL of your app starting with https://)

javascript
[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET",
            "PUT",
            "DELETE",
            "POST"
        ],
        "AllowedOrigins": [
            "https://yourdomain.com",
            "https://yourdomain.bubbleapps.io"
        ],
        "ExposeHeaders": [
            "ETag"
        ],
        "MaxAgeSeconds": 30000
    }
]

Example

Here is an example of a successful image rendering in our application:

Trying to open the same image in another tab or window (incognito) by URL will now result in the following error as restricted access to the file:

How to Setup

On the Bubble side, in plugin settings.

Provide the S3 Bucket name, the region, and the identity pool id in the plugin settings:

❗

It is important to provide the exact server region, where you have launched the S3 storage. The region and the region indicated in the Identity Pool ID should be the same. You can get the Identity Pool ID from your Cognito account.

✅

Here's a good Introduction Video by Amazon Team on how to get started with Amazon S3 - https://www.youtube.com/watch?v=vFfY_-TL-pc

Plugin Elements Proprieties

The plugin has 3 visual elements: File uploader, S3 Objects, and File Upload No GUI. In order to work with one of the elements, you have to add it to the page.

❗

Note: Only use one File upload No GUI element on the current page.

File uploader element

This element lets you easily upload files into your S3 Bucket using the User Interface.

Element properties

Placeholder - default text description that will be displayed in the editor until there is something to preview

Max file size (MB) - maximum file size for each file (in MB)

Max timeout (s) - maximum time that the app will wait for a file to upload; if the file doesn't get uploaded during this time, the upload request will be canceled

Enable preview - checkbox; if checked, enables preview for the uploaded files

Create image thumbnails - checkbox; if checked, enables image thumbnail creation

Show remove/cancel button - checkbox; if checked, the Remove/Cancel button will appear for each of the uploaded files, so you can remove them

Folder structure - this defines the way the files are stored in the S3 bucket. Available values: "uuid_filename" - the Unique ID will be added to the file name;"UUID/filename" - the file will be added to a new folder that will have Unique ID as a name, while the file name will remain unchanged; "folder_name/uuid_filename" - the folder name indicated in the next property will be used, and the Unique ID will become part of the file name; if this value is selected, but the 'Folder name' property is not set or is set to a dynamic value that resolves to 'null', the folder name 'unknown' will be used

A folder name - folder name to be used for files upload; is used only if the above property is set to 'folder_name/uuid_filename'; if the folder name resolves to 'null', the name 'unknown' is used

Add prefix to the filename - checkbox; if checked, file names will get custom prefixes to make it easier to locate them on S3 Bucket

Filenames prefix - custom prefix to add to file names; is applied only if the 'Add prefix to filename' checkbox is checked

Many files - checkbox; if checked, will allow users to upload multiple files at once

File extensions - used to specify allowed file extensions for the files to be uploaded to the S3 bucket; to allow all file extensions, set it to 'all'

Thumbnail method - dropdown; available values: contain, crop. Method to be used when creating thumbnails; it defines how the overlapping parts of the image preview will be handled

Thumbnail width (px) - width of the image thumbnail (in px), to best fit your design

Thumbnail height (px) - the height of the image thumbnail (in px), to best fit your design

Remove button caption - text that will be displayed on the Remove button

Cancel button caption - text that will be displayed on the Cancel button

Allow Image Cropping (Single File) - checkbox; if checked, will allow image cropping (use it only if the “Many Files” checkbox is unchecked)

Aspect ratio - aspect ratio for cropping

Allow image processing - checkbox; if checked, will allow image processing

Image resize method - dropdown; available values: crop, contain. Method to be used when processing images

Image resize quality - dropdown; available values: 0.2,0.4,0.6,0.8,1Quality of the resized image

Image resize Height - resized image height

Image resize Width - resized image width

Crop if the size is smaller than Image Resize Width or Height - checkbox; if checked, will allow cropping even if the cropped image size is smaller than Image Resize Width or Height

Crop modal title - the title of the Crop modal window

Crop Save Button Caption - text that will be displayed on the Save button in the Crop modal window

Crop Cancel Button Caption - text that will be displayed on the Cancel button in the Crop modal window

Initial Value - file to be uploaded to AWS initially, when the page with the plugin loads (optional)

Element actions

Reset input - used to reset the user input in the uploader

Element events

an error occurred - is triggered when an error occurs

uploading is finished - is triggered when file uploading is finished

the initial value is set - is triggered if the initial value is set for this uploader element

Element states

File URL - URL of the uploaded file

List of file URLs - list of uploaded file URLs

File Name - the name of the uploaded file

List of file names - list of uploaded files names

Filesize (KB) - uploaded file size (in KB)

List of files sizes (KB) - list of uploaded file sizes (KB)

Progress of files upload (%) - progress of the total file upload

Upload progress of current file - progress of the current file upload

Images Width - width of the image (only for image files)

Images Height - the height of the image (only for image files)

Too Big Files Names - names of the files that are too big for the current upload

Cropped image width - width of the cropped image (only if cropping is allowed)

Cropped image height - the height of the cropped image (only if cropping is allowed)

Initial Value URL - URL of the file set as the plugin element Initial Value

Error message - error message in case of an error

File Upload No GUI element

This element lets you easily upload files into your S3 Bucket without a graphical user interface but should be placed on the page in order to interact:

Element properties

Title - the title of the File Upload No GUI element

Unique file prefix format - dropdown; available values: uuid_, zq_randomThe unique prefix format you want to be used when adding a unique id to the file names when they are uploaded to the bucket.

❗

Note: the uuid_ format prefix will always have a constant length of 36+1 = 37 characters, while for the prefix with the zq_random format the length will vary.

Element actions

Upload File - is used to upload a file.

Action property:

file - indicate here the URL of the file to be uploaded

Element events

Upload Start - is triggered when the upload is started

Upload End - is triggered when the upload is ended (whether successfully or with error)

Error - is triggered if an error occurs during upload

Element states

URL - URL of the uploaded file

Name - a name of the uploaded file

Size - the size of the uploaded file

Type - file type of the uploaded file

Error - error message in case the file upload resulted in an error

S3 Objects

This element lets you get the list of files from the S3 Bucket. Should be placed on the page to get access to element actions, events, and states.

Element properties

This plugin element has no properties.

Element actions

Get all files from s3 - is used to get information about all the files from an S3 bucket or all the files from a certain folder on the bucket

Action properties:

A folder name - the name of the folder on the S3 bucket you want to get the files from. If left empty, the action will get all the files from the bucket

Element events

bucket's objects are loaded - is triggered once the Get all files from s3 action finished execution

Element states

List of file URLs - list of URLs of all the files on the S3 bucket

List of filenames - list of filenames of all the files on the S3 bucket

Last Modified - list of last modified dates for all the files from the S3 bucket

List of file size (MB) - list of file sizes for all the files on the S3 bucket

Plugin actions

1. Delete file

This action should be used in order to delete one file from an S3 Bucket

Action properties:

Key - URL of the file to be deleted

2. Delete Files

This action should be used in order to delete a list of files from an S3 Bucket

Action properties:

Files List - list of files to be deleted

Using URLs - checkbox, check it if you want to pass into the 'Files List' property a list of file URLs

Workflow/settings Example

File uploader element example To work with the 'File uploader' element, place it on the page and configure the settings according to your requirements. Here is just one of many possible examples:

2. S3 Objects element example

Example workflow with 'S3 Objects' element.

Place a button on the page and give it a name (for example, 'Get Files'). Then trigger the following workflow on this button click:

After this action has been run, you will have access to file information (in the element states: List of file URLs, List of filenames, Last Modified, and List of file size (MB)) for all the files that are currently located on S3 in the folder with the name 'MY_FOLDER'.

3. File Upload No GUI element example

To work with the 'File Upload No GUI' element, place it on the page, and, optionally, use some Bubble or other User Interface element in combination with this plugin element to make your design more user-friendly.

As an example, on our demo page, it is used in combination with the Bubble File Uploader element. Then choose the right settings for the 'Title' and 'Unique file prefix format', and start using them.

4. Delete Files plugin action example

Place a button on the page and give it a name (for example, 'Delete Files'). Then trigger the following workflow on this button click:

After the workflow has run, the indicated files will be deleted from the S3 Bucket.

Changelogs

Update: 12/29/2020 –

Changes to File uploader element:

Added 'Folder name' property

Added 'folder_name/uuid_filename' value for the 'Folder structure' property

2. Changes to S3 Objects element:

Added 'Folder name' property to 'Get all files from s3' element action

3. Changes .to File Upload No GUI element:

Added 'Unique file prefix format' property

4. Fixed issue with special characters in file names in SafariUpdate: 12/01/2021 -

Fixed 'File Upload No GUI' element bug in case of multiple visual elements on the page

Update: 04/03/2021 -

Fixed the problem with height in the reset function

Update: 19/04/2021 -

fixed problem with any size

Update: 26/04/2021 -

encoding URL for special character

Update: 05/05/2021 -

Standardization the logic for encode/decode S3 object

Update: 07/06/21 - Version: 1.76.0

Minor fixed problem with 'Allow Image Cropping

Update: 19/06/21 - Version 1.77.0

Has been updated documentation for fields

Update: 06/07/21 - Version 1.78.0

All areas of the element have become clickable

Update: 16/07/21 - Version 1.79.0

Fixed problem with the signature

Update: 20.11.21 - Version 1.82.0

Improved NoGui element with multiple files uploads and selecting the folder.

Update: 06.12.21 - Version: 1.84.0

Improvement with image orientation correction function.

Update: 14.12.21 - Version: 1.85.0

Fixed problem with the area clickability.

Update: 17.12.21 - Version: 1.86.0

Fixed problem with the dynamic prefix.

Update: 15.02.22 - Version: 1.87.0

Fixed problem with removing. (DOT) from the file URL"

Update: 23.05.22 - Version 1.93.0

"fixed the problem with states Size, type etc."

Update: 30.06.22 - Version 1.95.0

updated endpoint for action "get files".

Update 22.08.22 - Version: 1.97.0.

“Added new action for delete files in backend"

Update 02.09.22 - Version: 1.99.0

"Fixed problem with deleting files”

Update 12.09.22 - Version 1.101.0

added max files limit and event "file limit exceeded”

Update 26.09.22 - Version: 1.103.0

Fixed event "AWS Uploading is finished" and added the "Display text title only" field.

Update 03.10.22 - Version: 1.104.0

Fixed event "uploading is finished”

Update 04.10.22 - Version: 1.105.0

Fixed the "Upload File" action

Update 26.10.22 - Version: 1.107.0

Fixed the "Allow image processing" option and minor fixes

Update 14.11.22 - Version: 1.110.0

Added "List of FileNames Original" state

Update 22.11.22 - Version: 1.111.0.

Fixed Crop pop-up and fixed Prefix