Skip to main content

Public Files

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 25MB. Contact your account manager if you'd like to increase capacity.

Requirements#

Widget#

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

<head>
<!-- ... -->
<script src="../../../scripts/buildfire/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/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 successfull
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 successfull
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 successfull
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 successfull
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.

buildfire.services.publicFiles.deleteFile(
{
files: [new File()],
},
(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 successfull
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.