1 Create and place a block type element like div on your webpage. Specify the height and width of the element.

<div id="myUploader" style="width:600px; height:200px"></div>

2 Include the base BrowserPlus library, and the advanced upload JavaScript library at the bottom of your webpage:

<script src="http://bp.yahooapis.com/2.4.21/browserplus-min.js"></script> <script src="http://bp.yahooapis.com/toolbox/uploader/1.0.6/uploader-min.js"></script>

3 Create an instance of the Uploader tool and point it at your uploader element. The second argument contains configuration parameters, detailed below.

var uploader = BPTool.Uploader.create("myUploader", { /* config params */}); uploader.render();

It's important to understand that this JavaScript library is a convenience wrapper around BrowserPlus services, and its use is completely optional. Much more flexibility and control is available by directly using the BrowserPlus JavaScript API.

4 Optionally customize the look and feel of the uploader. As a second parameter to create(), you may pass in a map with any of the follow parameters (defaults shown):

var customUploader = BPTool.Uploader.create("anotherDiv", { uploadUrl: null, // where files are uploaded fileVarName: "file", // name of file upload variable zipFiles: false, // compress all files into 1 .zip file // Optional Callbacks, Details below in Step 5 fileCB: null, // called for every file action postCB: null, // associate data with each file constraintCB: null, // called for constraint violations uploadCB: null, // called after all files uploaed // Upload constraints maxFileSize: 0, // maximum size in KB for each file, 0 is any size maxFiles: 0, // maximum number of files that can be added to // uploader at one time mimeTypes: null, // array of mime types allowed, like: // ["application/pdf", "application/text"] // Upload UI uploadBackground: "#f7f7f7", uploadFont: "8pt tahoma,sans-serif", uploadColor: "#666", // Uploader labels fileLabel: "File", filesLabel: "Files", sizeLabel: "Size", removeLabel: "Remove?", trashLabel: "Remove file from list", // Files fileBorder: "1px solid #ccc", fileBackground: "#fff", fileColor: "#666", // Select and Hover selectBackground: "#006adb", selectColor: "#fff", hoverBackground: "#ffd", // Progress progressBackground: "#def", progressTextColor: "#000", progressBarColor: "#b3b3b3", progressBarBackground: "#fff", progressComplete: "Upload Complete!", // Footer footerBackground: "#eee", footerFont: "bold 8pt tahoma,sans-serif", footerBorder: "1px solid #ccc", footerColor:"#000", // Footer labels (plus file(s)label above) browseLabel: "Browse...", uploadLabel: "Upload", totalLabel: "Total" });

File Color and Font Parameters

Progress Color and Font Parameters

5 Optionally choose to have all files compressed and archived into a *.zip file before upload. Depending on the files being uploaded, this can save a lot of bandwidth.

NOTE: Directory structure is not preserved when zipping files in the Uploader tool. The path information is stripped and the files are all stored on the top level. If you need directory structure in a zipped file, check out the zipper code example.

var uploader = BPTool.Uploader.create("myUploader", { zipFiles: true }); uploader.render();

6 Optionally register for one or more of the callbacks though the configuration parameters.

fileCB

The fileCB() function is called when a file is added, selected, unselected, removed or uploaded.

function fileCB = function(result) { if (result.success) { // result looks like this: result = { id: "div_id", // the id of the element you called create with action: "action", // uploaded | add | remove | select | unselect name: "filename", // file name size: "filesize", // size of file in bytes uuid: "uuid" // unique id: uploader_inst + file_id value: {} // set when action=="uploaded" contains response // from server. Example value: // { // statusCode:200, // statusString:"200 OK", // headers: { /* headers from server */} // body: "response body" // } }; } else { // result looks like this: result = { id: "div_id", error: "short error message", verboseError: "optional longer error message" }; } }

postCB()

The postCB allows you to associate extra data with each file that is then passed as POST data when each file is uploaded. You may write a small form that connects to the uploader widget through file select/unselect events which then allows the user to provide a description of each file uploaded.

function postCB = function(uuid) { return MyPostData[uuid]; }

uploadCB

The uploadCB is fired when all files have been uploaded.

function uploadCB = function(resul) { // result is result = { id: "div_id", success: true/false }; }

constraintCB

You are notified of constraint violations when you register the constraintCB. You may wish to show an error message if any of the constraints are violated.

function constraintCB = function(res) { // result is result = { id: "div_id", constraint: "constraint", // "toobig" | "toomany" | "mimeType" name: "filename", mimeType: "application/text", size: 123 // size in bytes }; }