FilePicker

Upload or process files in Superblocks APIs

Use the FilePicker when your users upload assets like images, or when you need to manipulate text files like CSVs. Files can only be handled inside Superblocks API steps (i.e. the Upload Multiple Files action in S3, Python step, JavaScript step, etc.). If you are using the On-Premise Agent, files are sent directly from the user's computer to your agent. Superblocks supports files up to 150Mb.

Working with files in APIs

Each file that you upload is wrapped in a special <FilePickerComponentName>.files array item. To read the contents of a file, use the following language-specific syntax.

JavaScript

await <FilePickerComponentName>.files[<index>].readContentsAsync(<optional mode>)

API Step Bindings

{{ await <FilePickerComponentName>.files[<index>].readContentsAsync(<optional mode>) }}

Python

<FilePickerComponentName>.files[<index>].readContents(<optional mode>)

Available modes

Text

• Returns a utf-8 encoded string
• Default for non-binary files (e.g., .txt, .csv, .html)
• Configure manually by setting <optional mode> to text

Binary

• Returns a base64 encoded string
• Default for binary files (e.g., .pdf)
• Configure manually by setting <optional mode> to binary

Raw

• Returns the raw bytes buffer
• Configure manually by setting <optional mode> to raw


• Use raw when sending binary data like images and PDFs to S3 or in email attachments

Guide - Upload CSV and display in Table

This guide will quickly walk you through how to use the FilePicker in order to create a basic recipes explorer.

Use FilePicker to import files

1. Start by dragging a Container component from the Components panel to the empty canvas.
2. Now add a FilePicker component inside of the Container component.
3. Add a Button component inside of the Container component as well. Change the Label to Load File.
4. Lastly, add a Text component inside of the Container component. Change the Text to Add the Recipes CSV. Change the Text Size to Heading 2.

To configure our FilePicker to only allow certain file types, follow these steps:

1. Click the FilePicker widget to open the right side Properties panel.
2. Change Selection type to Single select.
3. Update the Allowed file types to only allow .csv and .txt file types:

[
  ".csv",".txt"
]

Now that we've restricted the file types allowed, you'll see that only .txt and .csv are available after clicking browse files.

Create an API to parse imported CSV

Now let's create an API in order to add some more functionality to our FilePicker component and show its data in a Table.

1. Click New API and select Python as the type
2. Change the name of the API to readCSVFile
3. Change the name of the step to parseCSV
4. Paste in the following code, which loads and reads the .csv file:

from io import StringIO
import csv

scsv = FilePicker1.files[0].readContents()
f = StringIO(scsv)

reader = csv.DictReader(f, delimiter=',')

return [row for row in reader]

Now that the API is up and running, update the Button component to have the readCSVFile API run when it's clicked. Select Run API as the Action Type for the onClick trigger and choose the readCSVFile API.

Show the file's data in a Table

1. Drag a Table component from the Component panel and place it below the Container component.
2. Update Table Data to {{readCSVFile.response}}
3. Update Table Header to the following code snippet to dynamically update the table's header based on the file loaded:

{{FilePicker1.files[0] ? "Viewing Recipes from: " + FilePicker1.files[0].name : "Waiting for Recipe Upload..."}}

You now have a working app that imports a csv file and shows it in a table!

Guide - File upload to S3

In this example, we will allow users to upload PDF and Microsoft Office documents to our S3 store.

1. Before starting, set up an S3 integration and note the name of the S3 bucket that you will upload to.

2. Drag and drop the Form component, and then drag and drop the FilePicker component inside the Form.

3. Change the "Allowed Files Types" to ["application/pdf", ".doc", ".docx"].

4. Click the Submit button to open the button properties. Under "onClick", add a new API to call. Choose the S3 integration from above.

5. Change the S3 action to "Upload Multiple Files", and configure the bucket name. Type {{FilePicker1.files}} as the File Objects Array. Alternatively, to allow for uploading a single file, set the S3 action to "Upload File" and set File Content to {{FilePicker1.files[0].readContents("raw")}}.

6. If you want to customize the name of each file, for example by adding a prefix, write this snippet instead:

   {{FilePicker1.files.map((file) => ({...file, name: '/prefix/' + file.name }))}}

7. Go back to the User Interface editor and select a file. Click "Submit" to upload the file. When the API is finished running, the form will clear itself.

Guide - Display an uploaded file in an image component

This is a short guide on how to display a jpeg file that was uploaded via a FilePicker component in an Image component. Instructions for uploading and displaying other types of data can be found below:

info

Files uploaded via the FilePicker are temporarily stored in your browser and do not persist between sessions. Consider uploading files to an external storage location (e.g., Amazon S3) for permanent storage.

1. Add a FilePicker component to the canvas.
2. Add an Image component to the canvas.
3. Add a new Backend API that has a single Python step.
4. Add the following code to the Python step to construct a Data URL from the file content:

file_content = FilePicker1.files[0].readContents();
return "data:image/jpeg;base64," + file_content

1. Rename the API to generateDataURL.
2. Click on the Image component and set the Image property to {{generateDataURL.response}}.
3. Upload a .jpeg file via the FilePicker.
4. Run the Backend API by clicking the blue Run button.

What are Data URLs?

Data URLs, also known as data URIs (Uniform Resource Identifiers), are a type of URI scheme that allows data to be embedded directly within a URL. In other words, a data URL contains the actual data itself instead of pointing to a separate resource.

Data URLs consist of four components: a prefix (data:), a MIME type that specifies the data type, an optional base64 token when dealing with non-textual data, and the actual data. The mediatype is a MIME type:

data:[<mediatype>][;base64],<data>

Replace the Data URL in the guide above with an example from the table below if you want to upload and display a file of a different data type:

File type	Data URL
jpeg	data:image/jpeg;base64," + file_content
png	data:image/png;base64," + file_content
gif	data:image/gif;base64," + file_content
pdf	data:application/pdf;base64," + file_content
...	find more types here.

Example: Display a pdf file uploaded via a file picker in a PDF viewer component:

caution

The PDF files that are uploaded via the File Picker component and passed to the PDF viewer component must be < 2 MB.

FilePicker Properties

Component Properties

FilePicker Property	Description
Selection Type	Set the FilePicker widget to Multi select to handle multiple files or Single select to restrict it to one file at a time
Allowed File Types	File types can either be mime types or suffixes. * represents a wildcard
Visible	Controls the visibility of the component, values are a boolean
Required	Makes adding a file mandatory, values are a boolean
Loading Animation	Controls the loading state of the component, values are a boolean

Reference Properties

Properties can be accessed from other frontend components and backend APIs by adding the name of the FilePicker, and dot referencing the property. For a FilePicker named FilePicker1:

Property	Description
FilePicker1.files	Returns an array of files
FilePicker1.isVisible	Returns the boolean value of the component's visibility (True, if it is visible)