Class: Upload

Upload

With "uploads", you can store files on Built.io Backend.Uploads on Built.io Backend are similar to objects. Each upload object holds a file, and they have an unique uid.

new Upload(File){Upload}

upload.js, line 24
Represents an upload on Built.io Backend
Name Type Description
File String | Buffer | Input | File | FormData | base64 | Bytes Accepts a File to be uploaded or Uid of an existing file
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance

On Browser

// Example using input element var upload = Built.App('blt5d4sample2633b').Upload() upload = upload.setFile(document.getElementById('input_element')); upload .save() .then(function(upload){ console.log(upload.toJSON()) }) //fileObj could be a instance of File or FormData var upload = Built.App('blt5d4sample2633b').Upload(fileObj); upload.save() .then(function(upload){ console.log(upload.toJSON()) });

On Node

var upload = Built.App('blt5d4sample2633b').Upload("/home/abc/Pictures/game-over.jpg"); // File path upload.save() .then(function(upload){ console.log(upload.toJSON()) }); var buffer = fs.readFileSync('images/cartoon.jpeg'); var upload = Built.App('blt5d4sample2633b').Upload({ bytes : buffer, contentType: 'image/jpeg', name: 'jerry.jpeg' }); upload.save() .then(function(upload){ console.log(upload.toJSON()) });

Common

var upload = Built.App('blt5d4sample2633b').Upload({ base64: "V29ya2luZyBhdCBQYXJzZSBpcyBncmVhdCE", contentType: 'image/jpeg', //Optional name: 'cartoon.jpg' });

Methods

staticUpload.on(event, callback){Upload}

realtime.js, line 1320

[Only avaliable with realtime plugin]

This function registers an event listener on Upload constructor.

Given below is the list of supported events.

  • Create
  • Create event is triggered when a new file is uploaded in this application. Registered callback is invoked with the uploaded data.

  • Update
  • Update event is triggered when the content and/or the ACL of any upload on this application is modified. Registered callback is invoked with the updated upload data.

  • Delete
  • Delete event is triggered when any upload on this application is deleted. Registered callback is invoked with the deleted upload data.

  • Broadcast
  • Broadcast event is triggered when a message is broadcast across all uploads. Registered callback is invoked with the broadcast message.

Name Type Description
event String The event on which listener needs to be registered
callback function The callback function to be invoked on event trigger
Example
// 'blt5d4sample2633b' is a dummy Application API key
// app.Upload returns a 'Upload' constructor
var app = Built.App('blt5d4sample2633b').enableRealtime();
var Upload = app.Upload;

Upload.on('create', function(jsonObject) {
   // newly created upload
});
Upload.on('update', function(jsonObject) {
   // updated upload data
});
Upload.on('delete', function(jsonObject) {
   // deleted upload data
});
Upload.on('broadcast', function(message) {
   // The message broadcasted across all the uploads in this application.
});
		

delete(){Promise.<null>}

upload.js, line 352
Deletes the upload from Built.io Backend
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
// 'blt212sample24a6b' is uid of an upload on Built.io Backend
var upload = Built.App('blt5d4sample2633b').Upload('blt212sample24a6b'); 
upload
.delete()
.then(function(){
   // do something here
}); 

download(){Promise.<Stream>}

upload.js, line 108
Downloads the file
Throws:
throw new Error("Object cannot be downloaded as download link not found");
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance

On Browser

var upload = Built.App('blt5d4sample2633b').Upload(formData); // formData is instance of FormData upload.fetch() .then(function(upload){ upload.download(); // A new tab is opened and the file gets downloaded. });

On Node

var upload = Built.App('blt5d4sample2633b').Upload(formData); // formData is instance of FormData upload.fetch() .then(function(upload){ upload.download() .then(function(stream){ // a nodejs 'Stream' is returned }); });

fetch(){Promise.<Upload>}

upload.js, line 381
Fetches the upload from Built.io Backend
Throws:
new Error('Upload object needs to be associated with a uid');
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
// 'blt212sample24a6b' is uid of an upload on Built.io Backend
var upload = Built.App('blt5d4sample2633b').Upload('blt212sample24a6b'); 
upload
.fetch()
.then(function(upload){
   // do something here
}); 

getACL(){ACL}

upload.js, line 439
Gets the ACL object from an upload
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
// 'blt212sample24a6b' is uid of an upload on Built.io Backend
var upload = Built.App('blt5d4sample2633b').Upload('blt212sample24a6b');
upload.fetch()
.then(function(upload){
   var acl = upload.getACL();
   console.log(acl.toJSON())
}) 

getContentType(){String}

upload.js, line 521
Gets the content type of an upload
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
// 'blt212sample24a6b' is uid of an upload on Built.io Backend
var upload = Built.App('blt5d4sample2633b').Upload('blt212sample24a6b');
upload
.fetch()
.then(function(upload){
   upload.getContentType(); 
})
upload.js, line 483
Gets the download link for the upload
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
var upload = Built.App('blt5d4sample2633b').Upload(formData); // formData is instance of FormData
upload.save()
.then(function(upload){
   var link = upload.getDownloadLink();
});

getFileName(){String}

upload.js, line 558
Gets the file name of the upload
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
// 'blt212sample24a6b' is uid of an upload on Built.io Backend
var upload = Built.App('blt5d4sample2633b').Upload('blt212sample24a6b');
upload.fetch()
.then(function(upload){
   upload.getFileName(); 
})

getFileSize(){String}

upload.js, line 540
Gets the file size of the upload
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
// 'blt212sample24a6b' is uid of an upload on Built.io Backend
var upload = Built.App('blt5d4sample2633b').Upload('blt212sample24a6b');
upload.fetch()
.then(function(upload){
   upload.getFileSize(); 
})

getHeaders(){object}

upload.js, line 576
Gets the header object of the upload
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
// 'blt212sample24a6b' is uid of an upload on Built.io Backend
var upload = Built.App('blt5d4sample2633b').Upload('blt212sample24a6b');
upload.getHeaders();

getTags(){Array}

upload.js, line 501
Gets the tag(s) assigned to an upload
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
// 'blt212sample24a6b' is uid of an upload on Built.io Backend
var upload = Built.App('blt5d4sample2633b').Upload('blt212sample24a6b');
upload
.fetch()
.then(function(upload){
   upload.getTags(); // Returns the ACL for this upload
});

getUid(){String}

upload.js, line 188
Gets the uid associated with this upload object
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
var upload = Built.App('blt5d4sample2633b').Upload(formData); // formData is instance of FormData
upload.fetch()
.then(function(upload){
   upload.getUid();
}); 

isNew(uid){Object}

upload.js, line 151
Helps in determining whether a uid is assigned to this upload or not
Name Type Description
uid String Uid of the upload
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
// 'blt212sample24a6b' is uid of an upload on Built.io Backend
var person = Built.App('blt5d4sample2633b').Upload('blt212sample24a6b')
var boolean = person.isNew(); // true

on(event, callback){Upload}

realtime.js, line 1368

[Only avaliable with realtime plugin]

This function registers an event listener on Upload instance.

Given below is the list of supported events.

  • Update
  • Update event is triggered when the content and/or the ACL of an upload on this application is modified. Registered callback is invoked with the updated upload data.

  • Delete
  • Delete event is triggered when an upload on this application is deleted. Registered callback is invoked with the deleted upload data.

  • Broadcast
  • Broadcast event is triggered when a message is broadcast over this upload instance. Registered callback is invoked with the broadcast message.

Name Type Description
event String The event on which listener should be registered
callback function The callback function to be invoked on event trigger
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'blt5dsamplef62a633b' is uid of an upload on Built.io Backend
var app = Built.App('blt5d4sample2633b').enableRealtime();
var upload = app.Upload('blt5dsamplef62a633b');

upload.on('update', function(jsonObject) {
   // updated upload data
});
upload.on('delete', function(jsonObject) {
  // deleted upload data
});
upload.on('broadcast', function(message) {
   // The message broadcasted over this upload instance
});
	

save(){Promise.<Upload>}

upload.js, line 297
Saves/Updates the upload
Fires:
  • upload:start and upload:end events of Events
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
// Creates a new upload as upload object does not have a uid property set
var upload = Built.App('blt5d4sample2633b').Upload(); 
upload = upload.setFile('/home/abc/Pictures/game-over.jpg');
upload.save()
.then(function(upload){
   // do something here
});

//Updates the existing upload as upload object has a uid property set
var upload = Built.App('blt5d4sample2633b').Upload('blt212sample24a6b'); //upload_uid
upload  = upload.setFile('/home/abc/Pictures/game-over.jpg');
upload.save()
.then(function(upload){
   // do something here
});

setACL(aclObject){Upload}

upload.js, line 417
Sets ACL on an upload
Name Type Description
aclObject ACL The ACL object
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
var upload = Built.App('blt5d4sample2633b').Upload(); 
var acl = Built.ACL();
acl  = acl.setPublicReadAccess(true);
upload = upload.setACL(acl);

setFile(file){Upload}

upload.js, line 220
Assigns file to an object
Name Type Description
file File Accepts a form input element, File instance or FormData instance
Throws:
new Error("Invalid file path: /home/user/...");
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance

On Browser

// Example using input element var upload = Built.App('blt5d4sample2633b').Upload() .setFile(document.getElementById('input_element')); upload.save() .then(function(upload){ console.log(upload.toJSON()) }) //fileObj could be a instance of File or FormData var upload = Built.App('blt5d4sample2633b').Upload(fileObj); upload.save() .then(function(upload){ console.log(upload.toJSON()) });

On Node

var upload = Built.App('blt5d4sample2633b').Upload("/home/abc/Pictures/game-over.jpg"); // File path upload.save() .then(function(upload){ console.log(upload.toJSON()) }); var buffer = fs.readFileSync('images/cartoon.jpeg'); var upload = Built.App('blt5d4sample2633b').Upload({ bytes : buffer, contentType: 'image/jpeg', name: 'jerry.jpeg' }); upload.save() .then(function(upload){ console.log(upload.toJSON()) });

Common

var upload = Built.App('blt5d4sample2633b').Upload({ base64: "V29ya2luZyBhdCBQYXJzZSBpcyBncmVhdCE", contentType: 'image/jpeg', //Optional name: 'cartoon.jpg' });

setTags(tag){Upload}

upload.js, line 461
Assigns tag(s) to an upload
Name Type Description
tag Array Array of tags that you want to associate this upload with
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
// 'blt212sample24a6b' is uid of an upload on Built.io Backend
var upload = Built.App('blt5d4sample2633b').Upload('blt212sample24a6b'); 
upload = upload.setTags(['tag1','tag2']);

setUid(uid){String}

upload.js, line 169
Sets the uid for this upload object
Name Type Description
uid String Uid of the existing built upload object
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
var upload = Built.App('blt5d4sample2633b').Upload(); 
upload = upload.setUid('blt212sample24a6b');

unsetFile(){Upload}

upload.js, line 277
Removes a file
Example
// 'blt5d4sample2633b' is a dummy Application API key
// 'app.Upload() returns a 'Upload' instance
var upload = Built.App('blt5d4sample2633b').Upload(); 
upload = upload.setFile('/home/abc/Pictures/game-over.jpg');
upload = upload.unsetFile();