Using Box UI Elements and Python (Part 1)
Box UI Elements are pre-built UI components that allow developers to add elements of the main Box web application into their own applications. They can be used to navigate through, upload, preview, and select content stored on Box and are available both as React components and framework-agnostic JavaScript libraries.
Suppose you have some sort of web portal and need to manage documents for your users, or your customer is using Box.com and you need to integrate with it so they can access its features like sign, skills, etc.
UI Elements are a practical way to bring basic document management features from Box.com into your apps.
Need a file browser, a previewer, a way to upload files into a specific folder, explore the file metadata and add comments, or even a way to allow the user to select files and pass those reference into your app?
In this article we will explore how to use the UI Elements in a python flask application.
Let’s get started.
Get a Box Developer Account
First you need to have a Box developer account.
If you already have one, you can skip ahead to the next step.
You may also skip this step if you have a standard Box account. Creating an application in the next step will upgrade your account to the developer type automatically.
Visit the developer account signup page. Fill out the text boxes and click Get Started.
You will receive a prompt to confirm your email address.
After clicking the confirmation url in your email, you will be taken to a login screen.
Once authenticated, you will see the Box Developer Console home screen.
Create a Box App
Visit the Box Developer Console.
Create a new application.
You’ll probably need to set up 2 factor authentication to make changes to apps.
In the configuration tab, make sure you have a Developer Token
The developer token is only valid for 1 hour.
Adjust your CORS Domains to match the URL from where you are running the app:
Start your Python project
Checkout this example in my repo, I’m using Python and Flask to create a simple web site.
UI Element: Explorer
The Explorer is an all-in-one component for your app users to interact with digital content stored in Box.
It can browse, search, preview, upload, download, delete, rename, create, and share files and folders.
Basics
The bare minimum you need to use the Explorer component is an access token, a root folder id and a container to display the Explorer.
For now, use the developer access token from the box app you generated.
Copy the .env.example to .env and update the developer token with your token.
The main app file will look something like this:
Let me know in the comments if you would like to explore an oAuth 2.0 or JWT example.
You can see the import explorer, here is where we call the explorer template:
The explorer template is where we have the html and JavaScript necessary to display the Explorer.
Load the explorer.css and explorer.js from the box CDN. Notice the version and localization.
Take a look at your browser console to see the logging for the options and the explorer object.
When you run the app it looks something like this:
Properties
Explorer has many properties to adjust its behavior.
The basic set of properties:
The root folder id represents the folder above which the element can not navigate. Zero represents the root folder for the user.
The current folder id represents the folder currently being displayed.
Logo URL represents the logo displayed. You can use a URL to an image. The string ‘box’ represents the Box logo.
There is also a set of flags you can toggle on and off, which will enable or disable features or actions a user can perform:
Because Explorer packs the Previewer and Sidebar components, there are also some options for those:
Events
If your application needs to keep track of what the user is doing, you can implement the Explorer events and pass context back.
Here is an example of events implementation:
In this example, to send event data data back to the server, I’m using a simple ajax call:
Of course your app needs an entry point to handle the event data. In the example I’m just printing the event data:
Security
Although in this example we are using a developer token directly, the access token is passed to the JavaScript UI Element object. Like any other JavaScript object, it can be inspected in the browser console.
In order to solve this issue Box has created a set of specific permissions or grants for the UI Elements. These are more restrictive than the app permissions.
Specific for the Explorer UI Element, you have, base_explorer, item_preview, item_download, item_rename, item_share, and item_delete.
Check out the documentation for more details.
You should always down scope the access token using the above permissions.
Putting it all together
You can get this sample app from my repo. Once run, you’ll see:
Take a look at the Explorer object and the events in the console of the browser.
The Explorer component also includes a previewer and a side bar to display extra information about a file.
And you can upload multiple files.
For more information, checkout our developer guides about UI Elements.
Now, you know how to use the Box Content Explorer with Python. Try out the other UI Element types for yourself. Happy Building!
