Quickly integrate file upload in your web app using the Chooser

// By JJ Kass • May 31, 2019

File upload from a web browser can be a hassle for both the developer and the end user. By integrating with Dropbox, you can help your users easily get to their files stored in Dropbox and streamline uploads into your app without the need for error handling or multipart form data with backend code. 

The Dropbox Chooser is an easy-to-implement, pre-built component that allows users to access their Dropbox files from within your app. Simply include our JavaScript snippet to add a file-browsing UI and handle authentication to a users’ Dropbox account. This post will cover the three simple steps to add Dropbox Chooser to your website or application.

Step 1: Create Your Dropbox App

Anything developers build on Dropbox needs to connect through a Dropbox app. If this is your first time creating a Dropbox app, head to our step-by-step setup wizard in the App Console, which will guide you through creating your Dropbox app.

Your Dropbox app has a unique app key that can be used (along with the app secret) to generate access tokens for making calls to the Dropbox API by implementing an OAuth flow. The Chooser helps you access files selected by a user without requiring a deep integration through OAuth, though you can certainly use the Chooser in combination with calls directly to the API to build more complex integrations.

Chooser itself can be implemented with any app permission level. While the user will be able to browse their entire Dropbox account with the Chooser , your app will only have access to the files explicitly selected by the user. You can read more about app permissions for Chooser here

Chooser also uses your unique app key to identify your app to Dropbox. To do this, you’ll need to include the Dropbox app key within your HTML in the next step. For now, let’s grab the app key from the “app settings” page within the App Console. 

Before moving on to the next step, add your application’s domain name into the Chooser/Saver domains” field in your app settings within the App Console. This keeps other websites from impersonating your app. You can also add the site to your “app settings” later you’ll be able to test locally without it.

Step 2: Integrate the Chooser into your App

With our Dropbox app prepared, we’re ready to add Chooser into our website or app. For this example, we’ll use some basic HTML and JavaScript to show what’s possible. You can also access basic Chooser set up instructions on the Dropbox developer website

To get started, copy and paste this boilerplate into a new HTML file: 

<!DOCTYPE html>
<head>
        <meta charset="UTF-8"/>
        <title>Chooser JS Integration Example</title>
        <script type="text/javascript" 
                src="https://www.dropbox.com/static/api/2/dropins.js" 
                id="dropboxjs" 
                data-app-key="YOUR-APP-KEY">
        </script>
</head>
<body>
        <h1>An Example of a Minimal Integration of Dropbox's Chooser JS</h1>
        <div id="dropboxContainer"></div>
        <script src="custom.js"></script>
</body>
</html>

There are a couple things to note here. First, the tag loads the Chooser from Dropbox. Be sure to replace YOUR-APP-KEY with the app key you grabbed from the App Settings page in the previous step. We also have an empty  and a call to a custom JavaScript file. We need to create that file (custom.js) and connect the to Chooser.

Again, here’s some boilerplate JavaScript. Copy it into a new file named `custom.js`:  

options = {
        success: function(files){
         
        },
        cancel: function(){
                 
        },
};
var button = Dropbox.createChooseButton(options);
document.getElementById("dropboxContainer").appendChild(button);

Here we create a new button by calling Dropbox’s createChooseButton function. We’ve passed a very basic options variable, which we’ll improve upon later. Next, we insert the button into the page by referencing the <div> in our HTML. 

Save your files in the same directory and load them up using a local web server of your choice; you will receive errors if you try to load them directly in your browser.  

Here is an example using express, a lightweight web framework for Node.js: 

  1. Run   in your terminal.
    * You’ll need npm (node package manager) to use this particular sample.
  2. Create a ‘server.js’ file and add the following code: 
var express = require('express');
var app = express();
// use line below if html file is in root directory
app.use(express.static(__dirname));
// use line below if html file is in nested folder
// app.use(express.static(path.join(__dirname, 'public')));
app.get('/', function(req, res) {
    res.render('index.html');
});
app.listen(8000)
console.log('Server listening on localhost:8000');

    3. Run your server with a node server.js command. 

You’ll have a page with a simple button that browses Dropbox files with very minimal code. In the next step, we’ll do something with the selected files.

Step 3: Customize Chooser to Your Needs

Dropbox Chooser is meant to support multiple use cases where you might otherwise need a direct file upload. However, since you don’t have to handle the bytes directly, some uses won’t even need a back-end at all. Your success function (empty in our previous example) will get an array of files, each with data about the file, such as the name and linkSee the Chooser documentation for the full list of available fields.

For this example, we’ll help users email PDF documents for others to review. This could be integrated as a lightweight publishing step within a workflow, where co-workers, or others involved with the project, would receive the email with preview links. To do this, we will only need the name and link fields.

To ensure this process is smooth, we will modify our options parameter by including several fields, as well as adding some code to the success function. Replace the previous `custom.js` file with the following JavaScript:

options = {
        success: function(files){
                send_files(files);
        },
        cancel: function(){
        },
        linkType: "preview",
        multiselect: true,
        extensions:['.pdf'],
};
var button = Dropbox.createChooseButton(options);
document.getElementById("dropboxContainer").appendChild(button);

We’ve set the linkType to preview to provide the user a preview link to the document for sharing. While this approach is useful for an end user, you’ll want to use the direct option if you intend to transfer the file to a backend.

There are a couple of other Chooser options we’re using. First, we set the multiselect field to true, which allows users to choose more than one file. Secondly, we limited our extensions to .pdf only—you can include multiple extensions as strings in the array, or remove the option to allow any file type.

The success function now calls to another function, send_files(), which will process the PDFs the user selects in the Chooser interface. Add this additional JavaScript to the bottom of your `custom.js` file:

function send_files(files) {
        var subject = "Shared File Links";
        var body = "";
        for(i = 0; i &amp;amp;amp;amp;lt; files.length; i++){
                body += files[i].name + "\n" + files[i].link + "\n\n";
        }
        location.href = 'mailto:coworker@example.com?Subject='+ escape(subject) + '&amp;amp;amp;amp;amp;body='+ escape(body),'200','200';
}

Our JavaScript function first sets a subject for the email, which we’ll use to send the links to the user’s PDF files. The for loop goes through all the files from the Chooser, getting the name of the file and the link to the file on Dropbox. Finally, we construct the mailto link (note the email address), being sure to escape the subject and body so all the data will make its way to our local email program.

Restart your localhost server and load up the HTML file in your browser. After choosing files, you’ll be ready to send the email, with the links pre-filled into the body of your message.

Potential Enhancements

In today’s mobile work environment, quick and easy file management through cloud services is essential for streamlined project communication. Dropbox’s Chooser gives developers a hassle-free component that easily integrates within their web applications, while providing the user an intuitive file browser with minimal code.

While the example we’ve shown above is pretty basic, Chooser is a versatile component, with many other customization options. For example, you could preview the contents with a call to window.open(). Or, work with the content in your app using a direct link. Anywhere you might use a standard file upload in your app’s workflow, you can instead more nimbly access a user’s Dropbox files with the Chooser. 

If this blog post was interesting to you, you should also check out the Dropbox Saver. With the Saver implemented into your app, a user can add files of any size into their Dropbox instantly.

For more Dropbox tutorials, check out our previous blog posts or our reference page. If you have any questions about Chooser or need help with anything else, you can always contact us here.

Build with Dropbox today at www.dropbox.com/developers


// Copy link