Content Sidebar
Content Sidebar
The Box Content Sidebar UI Element allows developers to add support for viewing file related metadata (incl. Box Skills) and Activity Feed (incl. versions, comments and tasks) in their desktop or mobile web application.
Installation
Learn how to install Box UI elements either through NPM or the Box CDN.
Authentication
The UI Elements are designed in an authentication agnostic way so whether you are using UI Elements for users who have Box accounts (Managed Users) or non-Box accounts (App Users), UI Elements should work out of the box. The reason for this is that UI Elements only expect a "token" to be passed in for authentication, and Box provides two different ways to generate tokens - OAuth and JWT.
Learn about selecting an authentication method
Sample HTML
<!DOCTYPE html>
<html lang="en-US">
<head>
<meta charset="utf-8" />
<title>Box Content Sidebar</title>
<!-- Latest version of the sidebar css for your locale -->
<link
rel="stylesheet"
href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/sidebar.css"
/>
</head>
<body>
<div class="container" style="height:600px"></div>
<!-- Latest version of the sidebar js for your locale -->
<script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/sidebar.js"></script>
<script>
var fileId = "123";
var accessToken = "abc";
// At least one of the sub-sidebars (details, activity feed, skills, metadata) need to be turned on for something to render. Details is iteself further divided into notices, properties, access stats and versions, one of which need to be enabled for the details sidebar to render.
var sidebar = new Box.ContentSidebar();
sidebar.show(fileId, accessToken, {
container: ".container",
detailsSidebarProps: {
hasNotices: true,
hasProperties: true,
hasAccessStats: true,
hasVersions: true
},
hasActivityFeed: true,
hasSkills: true,
hasMetadata: true
});
</script>
</body>
</html>
Demo
Stand-alone Sidebar
Sidebar with Content Preview
Sidebar with Content Explorer
API
const { ContentSidebar } = Box;
const sidebar = new ContentSidebar();
/**
* Shows the file selection.
*
* @public
* @param {String} fileId - The file id.
* @param {String} token - The API access token.
* @param {Object|void} [options] - Optional options.
* @return {void}
*/
sidebar.show(fileId, token, options);
/**
* Hides the sidebar, removes all event listeners, and clears out the HTML.
*
* @public
* @return {void}
*/
sidebar.hide();
/**
* Clears out the internal in-memory cache for the sidebar. This forces
* items to be reloaded from the API.
*
* @public
* @return {void}
*/
sidebar.clearCache();
/**
* Adds an event listener to the sidebar. Listeners should be added before
* calling show() so no events are missed.
*
* @public
* @param {String} eventName - Name of the event.
* @param {Function} listener - Callback function.
* @return {void}
*/
sidebar.addListener(eventName, listener);
/**
* Removes an event listener from the sidebar.
*
* @public
* @param {String} eventName - Name of the event.
* @param {Function} listener - Callback function.
* @return {void}
*/
sidebar.removeListener(eventName, listener);
/**
* Removes all event listeners from the sidebar.
*
* @public
* @return {void}
*/
sidebar.removeAllListeners();
Parameters
| Parameter | Type | Description |
|---|---|---|
fileId | String | Box File ID. This will be the ID of the file for which you want the sidebar. |
token | String | Box API access token to use. It can have read/write access to the file above. The value passed in for the token is assumed to never expire while the sidebar is visible. |
options | Object | Additional options. For example, sidebar.show(FILE_ID, TOKEN, {hasProperties: true}) would be used to show file properties in the sidebar. |
Options
| Parameter | Type | Default | Description |
|---|---|---|---|
container | String | document.body | CSS selector of the container in which the content sidebar should be placed. Calling hide() will clear out this container. |
hasActivityFeed | Boolean | false | Set to true to show the activity feed that includes versions, comments and tasks. |
hasMetadata | Boolean | false | Set to true to show box metadata for the file. |
hasSkills | Boolean | false | Set to true to show the file skills data. |
detailsSidebarProps | Object | {} | See section below. |
requestInterceptor | Function | Function to intercept requests. For an example see this CodePen. Our underlying XHR library is axios.js and we follow a similar approach for interceptors. | |
responseInterceptor | Function | Function to intercept responses. For an example see this CodePen. Our underlying XHR library is axios.js and we follow a similar approach for interceptors. |
detailsSidebarProps
| Parameter | Type | Default | Description |
|---|---|---|---|
hasProperties | Boolean | false | Set to true to show file properties in the details sidebar. |
hasAccessStats | Boolean | false | Set to true to show file access stats in the details sidebar. |
hasVersions | Boolean | false | Set to true to show file versions in the details sidebar. |
hasNotices | Boolean | false | Set to true to show file related notices in the details sidebar. |
Scopes
If your application requires the end user to only be able to access a subset of the Content Sidebar's functionality, you can use Downscoping to appropriately downscope the Access Token to a resulting token that has the desired set of permissions, and can thus, be securely passed to the end user client initializing the Content Sidebar.
Below are a set of UI Element-specific scopes to go alongside Downscoping. These allow developers to enable/disable UI controls on the Content Sidebar by configuring the appropriate scopes on the downscoped token. To learn more, see Dedicated Scopes for Box UI Elements.
Base Scope
| Scope Name | Permissions granted |
|---|---|
base_sidebar | Allows the user to get basic file info needed for the sidebar. |
Feature Scopes
| Scope Name | Permissions granted |
|---|---|
item_comment | Allows adding and editing comments. |
item_rename | Allows editing of file description. |
item_upload | Allows editing of file metadata. |
item_task | Allows creating and resolving of tasks. |