Using Box UI Elements and Python (Part 2)
In part 1 of this getting started with Box UI Elements and Python, we demonstrated how to use the Explorer. In part 2, we will look into the Previewer UI Element. Reference part 1 on how to get started and create your Box app.
Preparation
For this example, we are going to need some files and folders.
Go to Box.com and make sure you are logged in with the same user from part 1.
Go to the developer console and generate your developer token.
Back in your Box account, create a folder named “Box UI Elements Demo” and upload some files into it. Choose some pdf, doc, xlsx, images, movies — anything that represents content.
Finally, open your .env file and set the following variables:
Replace the dummy variables with Id’s from your uploaded files. You can get the id’s directly from the browser, e.g.:
In my case, for UPLOADER_FOLDER_ID = 163436720758
In my case, for PREVIEWER_FILE_ID = 976816493098
Grab a few more file id’s from the content you uploaded and create the previewer file list. Make sure the previewer file id is included on that list.
In my case, for PREVIEWER_FILE_LIST=976816493098, 960391244732, 962024331798, 962023145830
Let’s get started!
UI Element: Previewer
The Preview UI Element allows developers to embed high quality and interactive previews of Box files in their applications. This UI Element also allows previews of multiple files to be loaded in the same container and exposes arrows to navigate between those files.
The Previewer element, does just that, it allows you application to display the content of a file.
It supports 120+ file types, including most document and image formats, HD video, 3D models, 360-degree images, and 360-degree videos. You can find the full list of supported file types here.
A typical implementation would look like:
The file_id represents the file you want to preview on your app.
The collection represents the multiple files you want to preview. Make sure the file_id is included in this array.
Logo URL represents the logo displayed. You can use a URL to an image. The string ‘box’ represents the Box logo.
And the corresponding template:
The Preview element is also very rich in events your app can capture.
Viewer triggered when we first show the previewer on a file. A specific viewer will display the file. It returns the JavaScript object of the specific viewer being used, e.g. pdf’s have a specific viewer which id different from mp4 files.
Load is triggered when any viewer loads and returns the file and viewer objects.
Navigate is triggered when the user press the carets to navigate between file.
Notification is triggered when either the preview wrapper or one of the viewers wants to notify something like a warning or non-fatal error.
Viewer event is triggered when a specific viewer trigger their own events.
This is what it looks like on my app when using the multi file (notice the carets):
Like the Explorer, the Previewer also comes packed with another UI Element, the Sidebar, you just need to add the options to configure it:
Which looks like this:
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 Previewer UI Element, you have, base_preview, item_download, annotation_edit, annotation_view_all, and annotation_view_self.
Check out the documentation for more details.
You should always down scope the access token using the above permissions.
Let me know in the comments if you’d like to explore OAuth 2.0 or JWT Authentication
Putting it all together
You can get this sample app from my repo. Once you run it you get:
Now that you are familiar with three preview types (single file, multi file and with side bar), start coding with real content. Happy Building!
