Skip to main content

buildfire.services.publicFiles

API accessible via the plugin SDK that allows plugin developers to upload files to our servers.

note

Additional charges may be added to the app owner. Current Maximum file size is 1 GB.

Requirements

Widget

Include publicFiles.js file in widget header right after the buildfire.min.js

<head>
<!-- ... -->
<script src="../../../scripts/buildfire.min.js"></script>
<script src="../../../scripts/buildfire/services/publicFiles/publicFiles.js"></script>
</head>

Control

Include publicFiles.js file in control header right after the buildfire.min.js

<head>
<!-- ... -->
<script src="../../../../scripts/buildfire.min.js"></script>
<script src="../../../../scripts/buildfire/services/publicFiles/publicFiles.js"></script>
</head>

Methods

showDialog()

buildfire.services.publicFiles.showDialog(options, onProgress, onComplete, callback)

This method will show up the browse dialog in order to be used by the app user to select the needed files.

buildfire.services.publicFiles.showDialog(
{ filter: ["image/jpeg", "image/png"], allowMultipleFilesUpload: true },
(onProgress) => {
console.log("onProgress" + JSON.stringify(onProgress));
},
(onComplete) => {
console.log("onComplete" + JSON.stringify(onComplete));
},
(err, files) => {
if (err) return console.error(err);

console.log("Files", files);
}
);

options

NameTypeRequiredDescriptionDefault
allowMultipleFilesUploadbooleannoThis property will give the plugin developers the functionality for allowing the users to select multiple files or single file.false
filter[string]noThis property will give the plugin developers the functionality to filter the file types allowed to be uploaded.
permissionsobjectnoThis property will give the plugin developers the functionality to restrict file access by managing users who have read, write, delete and admin access to file. If no permissions object is passed, file will be public by default. Read more on permissions management below.

onProgress

Function that will be invoked when uploading each file and it will return the percentage of completion for each file

NameTypeRequiredDescriptionDefault
onProgressfunctionyesFunction that will be invoked when uploading each file and it will return the percentage of completion for each file

onComplete

Function will be invoked after each file has been uploaded and it will be called on each file completion.

NameTypeRequiredDescriptionDefault
onCompletefunctionyesFunction will be invoked after each file has been uploaded and it will be called on each file completion.

callback(err, files)

NameTypeDescription
errstringerror string, null when operation is successful
files[object]Array of file objects

file

NameTypeDescription
fileIdstringFile unique id
fileNamestringName of the file
urlstringFile url used to access the file
sizenumberFile size in KB
status[]File upload status "failed" or "success"
typestringFile type

getFileUrl()

buildfire.services.publicFiles.getFileUrl(options, callback)

This method will get signed url that enables access to private files. Any file without "public" in read permissions is considered private.

note

In case the file is not private, it can be accessed directly using url returned from showDialog callback. Read more on permissions management below.

buildfire.services.publicFiles.getFileUrl(
{ fileId: "thisIsFileIdFromShowDialogCallback" },
(err, file) => {
if (err) return console.error(err);

console.log("File url", file.url);
}
);

options

NameTypeRequiredDescriptionDefault
fileIdstringyesUnique file id

callback(err, file)

NameTypeDescription
errstringerror string, null when operation is successful
fileobjectObject containing url

modifyPermissions()

buildfire.services.publicFiles.modifyPermissions(options, callback)

This method will modify file permissions. User needs to be file admin in order to change file permissions. Read more on permissions management below.

buildfire.services.publicFiles.modifyPermissions(
{
fileId: "thisIsFileIdFromShowDialogCallback",
permissions: {
read: ["public"],
write: ["user@email.com"],
delete: ["user@email.com"],
admin: ["user@email.com"],
},
},
(err, file) => {
if (err) return console.error(err);

console.log("File permissions updated", file);
}
);

options

NameTypeRequiredDescriptionDefault
fileIdstringyesUnique file id
permissionsobjectyesNew permissions

callback(err, file)

NameTypeDescription
errstringerror string, null when operation is successful
fileobjectModified file

deleteFile()

buildfire.services.publicFiles.deleteFile(options, callback)

This method will modify file permissions. User needs to be file admin in order to change file permissions. Read more on permissions management below.

buildfire.services.publicFiles.deleteFile(
{
fileId: "thisIsFileIdFromShowDialogCallback",
},
(err, file) => {
if (err) return console.error(err);

console.log("File deleted", file);
}
);

options

NameTypeRequiredDescriptionDefault
fileIdstringyesUnique file id

callback(err, file)

NameTypeDescription
errstringerror string, null when operation is successful
fileobjectDeleted file

uploadFiles()

buildfire.services.publicFiles.uploadFiles(files, options, onProgress, onComplete, callback)

This method lets plugin developers upload files without showing file dialog. This way developer has more freedom on how to display file selection.

note

The user must be logged in otherwise the function will return a callback error

buildfire.services.publicFiles.uploadFiles(
{
files: [new File()],
},
null,
(onProgress) => {
console.log("onProgress" + JSON.stringify(onProgress));
},
(onComplete) => {
console.log("onComplete" + JSON.stringify(onComplete));
},
(err, files) => {
if (err) return console.error(err);

console.log("Files", files);
}
);

files

Array of javascript File objects

options

NameTypeRequiredDescriptionDefault
allowMultipleFilesUploadbooleannoThis property will give the plugin developers the functionality for allowing the users to select multiple files or single file.false
filter[string]noThis property will give the plugin developers the functionality to filter the file types allowed to be uploaded.
permissionsobjectnoThis property will give the plugin developers the functionality to restrict file access by managing users who have read, write, delete and admin access to file. If no permissions object is passed, file will be public by default. Read more on permissions management below.

onProgress

Function that will be invoked when uploading each file and it will return the percentage of completion for each file

NameTypeRequiredDescriptionDefault
onProgressfunctionyesFunction that will be invoked when uploading each file and it will return the percentage of completion for each file

onComplete

Function will be invoked after each file has been uploaded and it will be called on each file completion.

NameTypeRequiredDescriptionDefault
onCompletefunctionyesFunction will be invoked after each file has been uploaded and it will be called on each file completion.

callback(err, files)

NameTypeDescription
errstringerror string, null when operation is successful
files[object]Array of file objects

file

NameTypeDescription
fileIdstringFile unique id
fileNamestringName of the file
urlstringFile url used to access the file
sizenumberFile size in KB
status[]File upload status "failed" or "success"
typestringFile type

Managing Permissions

Permissions object

NameTypeDescription
readArrayWho can access file?
writeArrayWho can edit file?
deleteArrayWho can delete file?
adminArrayWho can change the read, write and delete arrays above?

Each Array above can be made by each of the following:

  • userId BuildFire user id
  • email Email linked to BuildFire user
  • tag BuildFire tag
  • public word public

Example:

{
"read": ["public"],
"write": ["janedoe@example.com", "__ADMIN__"],
"delete": ["user@example.com"],
"admin": ["user@example.com"]
}

In the example above, anyone with link can access file since read permission have word public inside. User with email janedoe@example and anyone with tag __ADMIN__ can edit file. Only user with user@example.com can delete file and change file permissions.

If no permsissions object is passed in any of the functions above it defaults to

{
"read": ["public"],
"write": ["public"],
"delete": ["public"],
"admin": ["user@example.com"]
}

where user@example.com is email of the user uploading the file.