Files management tutorials

How to upload a file

You need to perform these steps to integrate file uploads into your web application:

• (1) Configure file categories in the Console
• (2) Add the UI Component to your frontend
• (3) Optional: Relate the file to another object

(1) Configure file categories in the Console

Each uploaded file belongs to a file category which you can configure in ROQ Console (opens in a new tab): File Handling ➔ Categories. File categories have two purposes:

• Fetch files by categories (e.g. get all avatars)
• Define max file size of uploaded files

You need to input a key, which you'll use when uploading the file.

(2) Add the UI Component to your frontend

ROQ ships with two UI Components which can be used to upload files:

1. The <FileUpload/> component represents a button that opens a file selector and starts uploads.
2. The <FileDropzone/> UI component represents an area on your application where users can drag and drop files to be uploaded.

Please follow the respective instructions to integrate the UI component into your website. You'll need to pass the key of the previously created category as a prop.

(3) Optional: Relate the file to another object

In most scenarios, a file belongs to some other object. For instance, an uploaded PDF file could be related to a contract object that exists in your project. Therefore, it is usually needed to link files to other objects. There are two strategies to achieve this. In both cases, you must retrieve the file's ID and pass it to your server-side backend application. You can get the file's ID from the <FileUpload/> or <FileDropzone/> component using the onUploadSuccess handler.

1. You can add the file ID to your database tables (e.g., roqFileId). This way, you have full control over the relationships and can easily fetch and manipulate them. This works very well in the case of one-to-one relationships, but if an object is related to multiple files, you'll need to add additional tables just for the relation.
2. To keep your database schema clean, you can save the relation on the ROQ Platform side using the createFileAssociation() API.

(4) Optional: Set the visibility of the uploaded file

You can change the file's visibility using the makeFilePublic() and makeFilePrivate() APIs.

Note that when you create a URL for download, this URL can still be shared with anonymous users. The main difference from a public file is that the URL will work only for a short period.

How to fetch files via API

After you upload a file, you can access them using the files() API. This query is equipped with filters, which allow you to find files by their associated objects or to fetch files by category.