Box Developer Documentation
Log in

Content Sidebar

Guides Embed Box UI Elements Content Sidebar
Edit this page

Required Guides

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

ParameterTypeDescription
fileIdStringBox File ID. This will be the ID of the file for which you want the sidebar.
tokenStringBox 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.
optionsObjectAdditional options. For example, sidebar.show(FILE_ID, TOKEN, {hasProperties: true}) would be used to show file properties in the sidebar.

Options

ParameterTypeDefaultDescription
containerStringdocument.bodyCSS selector of the container in which the content sidebar should be placed. Calling hide() will clear out this container.
hasActivityFeedBooleanfalseSet to true to show the activity feed that includes versions, comments and tasks.
hasMetadataBooleanfalseSet to true to show box metadata for the file.
hasSkillsBooleanfalseSet to true to show the file skills data.
detailsSidebarPropsObject{}See section below.
requestInterceptorFunctionFunction to intercept requests. For an example see this CodePen. Our underlying XHR library is axios.js and we follow a similar approach for interceptors.
responseInterceptorFunctionFunction 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

ParameterTypeDefaultDescription
hasPropertiesBooleanfalseSet to true to show file properties in the details sidebar.
hasAccessStatsBooleanfalseSet to true to show file access stats in the details sidebar.
hasVersionsBooleanfalseSet to true to show file versions in the details sidebar.
hasNoticesBooleanfalseSet 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 NamePermissions granted
base_sidebarAllows the user to get basic file info needed for the sidebar.

Feature Scopes

Scope NamePermissions granted
item_commentAllows adding and editing comments.
item_renameAllows editing of file description.
item_uploadAllows editing of file metadata.
item_taskAllows creating and resolving of tasks.

Related Guides