Metadata view in Box Content Explorer

Photo by Niklas Ohlrogge on Unsplash

Box UI Element, the Content Explorer, is now extended with the metadata view! By following this article, you’ll learn how to add the component to your custom React-based project.

Additionally, we are more than happy to announce that Box UI Elements are now responsive, so you can provide a more tailored experience for all mobile device users. 🎉

Metadata view in the content explorer

Prerequisites for this demo:

• Node version: ^18.18.2
• React version: ^17.0.2
• Latest released box-ui-elements package: ^19.0.0

Steps you need to perform for this project:

1. Set up Box a account

If you don’t have a Box developer account yet, please do so to follow along.

2. Create a Box app and configure it

For a detailed introduction to Box app types, head to our developer guide.

For this project, make sure to add the local development address in the CORS setting in the Developer Console.

Avoid the use of training slashes in the URL unless specifically required.

CORS Domains settings in Developer Console

Also, generate the developer token, as this will be needed for the development of this application.

The developer token is valid only for one hour, so make sure you revoke it once it’s no longer valid.

3. Create a metadata template and apply it to a folder

Check out Rui Barbosa’s blog post or our documentation quick-start guide to grasp core Box metadata concepts. You’ll also find detailed instructions on how to create a metadata template and apply it to a folder.

Getting started with Box Metadata Administration

Metadata Template in Admin Console

You can configure the metadata template, for example:

• directly in the Box Admin Console,
• using API (create metadata instance on folder, create metadata cascade policy)
• using TS SDK: (MetadataTemplatesManager, MetadataCascadePoliciesManager)

Pick a folder in Box, and apply the metadata template to it. Make sure you enable the cascade policy.

The screenshot below shows the folder settings popup in the Box app with the contentExplorer metadata template being applied. The cascade policy is marked as enabled.

Box app view, applying metadata template on a folder

Metadata view in Content Explorer

You can directly clone the finished sample project here. If you wish to follow along from scratch, create a React app using this command in your terminal:

npx create-react-app my-app

Box UI Elements currently support React v17. By default, create-react-app initiates React v18, so in this case, we need to downgrade.

You may also need to instal react-scripts on your local machine.

npm i react-scripts

To avoid complications due to some dependency conflicts, you can find my package.json file content below:

{
  "name": "content-explorer-metadata",
  "version": "0.1.0",
  "private": true,
  "dependencies": {
    "box-ui-elements": "^19.0.0",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "react-intl": "^6.6.1",
    "react-scripts": "^5.0.1"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build",
    "test": "react-scripts test",
    "eject": "react-scripts eject"
  },
  "eslintConfig": {
    "extends": "react-app"
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  },
  "overrides": {
    "draft-js": {
      "react": "$react",
      "react-dom": "$react-dom"
    },
    "react-tether": {
      "react": "$react",
      "react-dom": "$react-dom"
    },
    "react-beautiful-dnd": {
      "react": "$react",
      "react-dom": "$react-dom"
    },
    "react-textarea-autosize": {
      "react": "$react",
      "react-dom": "$react-dom"
    }
  },
  "devDependencies": {
    "postcss-flexbugs-fixes": "^5.0.2",
    "postcss-preset-env": "^9.3.0",
    "web-vitals": "^3.5.1"
  }
}

Next, make sure you adjust the index.js file with the React v17 syntax.

import React from 'react';
import { render } from 'react-dom';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';

const root = document.getElementById('root');
render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  root
);

reportWebVitals();

Now, let’s finally switch to theApp.js file. First, add some imports:

import React from "react";
import "./App.css";
import {IntlProvider} from "react-intl";
import ContentExplorer from "box-ui-elements/es/elements/content-explorer";

Next, define the data that will be passed to the ContentExplorer component:

function App() {
  // Get the token from Developer Console (app's configuration tab)
  const token = "<DEVELOPER_TOKEN>";

  // Folder ID with a metadata template applied
  // The metadataQuery will apply to this folder
  const rootFolderID = "<ROOTFOLDER_ID>";

  // Get ENTERPRISE_ID from Developer Console (app's general settings)
  const EID = "<ENTERPRISE_ID>"

  // Get templatekey from Admin Console (Content -> Metadata -> check url for ID)
  const templateName = "<METADATA_TEMPLATE_NAME>"
  
  // Define metadata source
  // Example: enterprise_123456789.metadatatemplate
  const metadataSource = `metadata.enterprise_${EID}.${templateName}`

  const metadataQuery = {
    from: metadataSource,

    // Filter items in the folder by existing metadata key
    query: "key = :arg1",

    // Display items with value
    query_params: { arg1: "value" },

    // Define the ancestor folder ID
    ancestor_folder_id: 0,

    // Define which other metadata fields you'd like to display
    fields:[
      `${metadataSource}.name`,
      `${metadataSource}.last_contacted_at`,
      `${metadataSource}.industry`,
      `${metadataSource}.role`,
    ]
  };

  // The metadata fields/columns to view - must be valid field names from the metadata template
  const fieldsToShow = [

    // Determine if the user can edit the metadata directly from Content Explorer component
    { key: `${metadataSource}.name`, canEdit: false },

    // Determine label alias on metadata column with displayName prop
    { key: `${metadataSource}.industry`, canEdit: false, displayName: "alias" },
    { key: `${metadataSource}.last_contacted_at`, canEdit: true },
    { key: `${metadataSource}.role`, canEdit: true },
  ];
  
  // defaultView - a required prop to paint the metadata view.
  // If not provided, you'll get regular folder view.
  const defaultView = "metadata";

  return (
      <IntlProvider locale="en">
        <div className="App">
          TODO
        </div>
      </IntlProvider>
  );
}

export default App;

See some example metadata queries:

// Filter all files withing given folder that are due by date: 17/01/24.
query: "dueByDate = :arg1",
query_params: { arg1: "2024-01-17T00:00:00.000Z" },

// or

// Filter all files withing given folder in the technology industry.
query: "industry = :arg1",
query_params: { arg1: "Technology" },

Want to learn more about Box metadata queries? Check out an in-depth guide prepared by Rui Barbosa:

Working with Box Metadata Queries

Once you’ve prepared all the necessary details, let’s pass those data to the Content Explorer component:

[...]

function App() {
  [...]

  return (
      <IntlProvider locale="en">
        <div className="App">
          <header className="App-header">
            <h2>Metadata view in Content Explorer</h2>
          </header>
          <section>
            <div className="metadata-based-view">
              <ContentExplorer
                rootFolderId={rootFolderID}
                token={token}
                metadataQuery={metadataQuery}
                fieldsToShow={fieldsToShow}
                defaultView={defaultView}
              />
            </div>
          </section>
        </div>
      </IntlProvider>
  );
}

export default App;

You might also programatically get the metadata for a given folder or file using the Box TS SDK. For this, install the package:

npm install box-typescript-sdk-gen

Import SDK in the App.js file,

import { BoxClient, BoxDeveloperTokenAuth } from "box-typescript-sdk-gen";

and pull metadata for a given file or folder:

  const getMetadata = async function main(token) {
    try {
      const client = new BoxClient({
        auth: new BoxDeveloperTokenAuth({ token }),
      });
      const metadata = await client.fileMetadata.getFileMetadataById(
        'FOLDER_ID',
        'enterprise_123456789',
        'templatekey'
      );
      console.log(metadata)
    } catch (e) {
      alert(String(e));
      console.error(e);
    }
  }

This snippet will log in to the console metadata file details:

canEdit: true
extraData: 
  $canEdit: true
  $id: "ID"
  $parent: "file_ID"
  $scope: "enterprise_123456789"
  $template: "templatekey"
  $type: "templatekey-ID"
  $typeVersion: 5
  $version: 6
  dueByDate: "2024-01-17T00:00:00.000Z"
  owner: "Peter Pan"
  type: "Internal"

Check Box TS SDK docs: FolderMetadataManager, FileMetadataManager. Alternatively, you can perform a Get metadata instance on file or Get metadata instance on folder API call.

Find the finished sample project here.

You may also like to explore more details on How to Create the Right Metadata Structure for Your Enterprise.

Follow for more tutorials and Box Platform updates!

Join our Box Developer Community for support and knowledge sharing!

Cheers!