Introducing enhanced metadata view of Box Content Explorer

|
Share
Introducing enhanced metadata view of Box Content Explorer

What’s new in v2

Starting from v24.0.0 of Box UI Elements package, you can include the enhanced metadata view of Box Content Explorer (v2) with:

  • Advanced filtering and editing interface: Multi-faceted filtering with dedicated UI for each metadata field type
  • Flexible display options: Toggle between list and grid views
  • Single and bulk custom actions: Select multiple items and perform batch actions
  • Pagination: Navigate between paginated content

Be sure to stay tuned for future announcements, as we’ll be adding even more exciting functionalities to this component.

⚠️ Important: Metadata view v1 has reached end of support. While v1 remains available in the 24.0.0 package version, it will no longer receive bug fixes or new features. Follow the migration guide and switch to the v2 metadata view of Content Explorer in order to receive the newest features.

Invoice

Prerequisites

To work with Box Content Explorer metadata view, you’ll need to:

  • Create a Box Platform app in Box Developer Console.
  • Add your custom app link to the Box app CORS settings.
  • Generate a developer token.
  • Set up a metadata template inBox Admin Console.
  • Apply the metadata template to chosen folders or files.

The Box UI Elements package v24.0.0 supports React 18.0.0 and requires node >=18.0.0.

If you’re developing your project in React, be sure to copy peer dependencies from the box-ui-elements package and add them to dependencies of your project and install them.

If you’re new to working with metadata in Box, check additional resources to help you get started:

Getting started with Box Metadata Administration

Working with Box Metadata Queries

Displaying the enhanced metadata view of Box Content Explorer

Depending on your needs and setup, Box UI Elements can be used with vanilla JS or React. You can learn more about installation from this guide. To display the new version of Content Explorer, install or upgrade the box-ui-elements package to v24.0.0. For simplicity, we’ll explore a basic setup example using vanilla JS. Capitalized strings need to be replaced with your custom values.

const contentExplorer = new Box.ContentExplorer();

contentExplorer.show(FOLDER_ID, ACCESS_TOKEN, {
  container: ".container",
  defaultView: "metadata",
  // metadataQuery must match the query files/folders by metadata API body request:
  // https://developer.box.com/reference/post-metadata-queries-execute-read/
  metadataQuery: {
      from: "METADATA_SCOPE.TEMPLATE_KEY", // For example from: "enterprise_123456789.templatename" where the number is the enterprise_123456789 is metadata template scope)
      ancestor_folder_id: "FOLDER_ID"
      // Metadata fields and values pulled to the component
      fields: [
          "metadata.TEMPLATE_SCOPE.TEMPLATE_KEY.FIELD_KEY1",
          "metadata.TEMPLATE_SCOPE.TEMPLATE_KEY.FIELD_KEY2",
          "metadata.TEMPLATE_SCOPE.TEMPLATE_KEY.FIELD_KEY3",  // For example "metadata.enterprise_123456789.templatename.date"
          ...
      ]
      // Optional for filtering data with specific metadata value
      query: "METADATA_FIELD_KEY = :arg1",
      query_params: { arg1: "METADATA_FIELD_VALUE" },
 },
 features: {
     contentExplorer: {
         metadataViewV2: true, // Required for enabling V2
     },
 },
 // NEW dynamic column configuration
 metadataViewProps: {
   columns // Required - for details see section below
   ...
 }
});

In case you’re using React, here is a code snippet:

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

// Fill with custom values of your metadata template
// You can use this endpoint to get all needed values: https://developer.box.com/reference/get-metadata-templates-id-id-schema/
const metadataScopeAndKey = `${METADATA_TEMPLATE_SCOPE}.${METADATA_TEMPLATE_KEY}`;
const metadataFieldNamePrefix = `metadata.${metadataScopeAndKey}`;
const folderID = "FOLDER_ID"

const metadataQuery = {
   // Check this endpoint for more details on query structure:
   // https://developer.box.com/reference/post-metadata-queries-execute-read/
   from: metadataScopeAndKey,
   ancestor_folder_id: folderID,
   fields: [
      "metadata.METADATA_SCOPE.TEMPLATE_KEY.METADATA_FIELD_KEY1",
      "metadata.METADATA_SCOPE.TEMPLATE_KEY.METADATA_FIELD_KEY2",  // For example "metadata.enterprise_123456789.templatename.date"
      ...
   ]
};

// Required - for details see section below
const columns = [
   {
      textValue: "METADATA_FIELD_DISPLAY_NAME1", // or our your custom value
      id: `${metadataFieldNamePrefix}.${METADATA_FIELD_KEY1}`,
      type: field.type,
      allowsSorting: true,
      minWidth: 150,
      maxWidth: 150,
   },
   {
      textValue: "METADATA_FIELD_DISPLAY_NAME2", // or our your custom value
      id: `${metadataFieldNamePrefix}.${METADATA_FIELD_KEY2}`,
      type: field.type,
      allowsSorting: true,
      minWidth: 150,
      maxWidth: 150,
   },
   ...
];

const componentProps = {
 features: {
   contentExplorer: {
       metadataViewV2: true,
   },
 },
 metadataQuery,
 metadataViewProps: {
   columns
 },
};

const ContentExplorerContainer = () => {
 const { features, metadataQuery, metadataViewProps } = componentProps;
 // Store token in a secure way
 return (
   <IntlProvider locale="en">
     <ContentExplorer
       title="Component title" // The title of the whole component, if not defined, defaults to the folder name specified in the `ancestor_folder_id`.
       token={TOKEN}
       defaultView="metadata"
       features={features}
       metadataQuery={metadataQuery}
       metadataViewProps={metadataViewProps}
     />
   </IntlProvider>
 );
};

export default ContentExplorerContainer;

Fetching data for Content Explorer 

To make things easier, you might want to pull data, like available metadata fields and their keys, from Box API. There are two very useful endpoints for querying data:

  1. Get metadata template by name: This endpoint returns a lot of useful data, like the metadata template scope and available fields, with associated keys, types, display names, and more. This might be helpful in crafting the metadataQuery and columns objects required for this component. 

  2. Query files/folders by metadata: This endpoint is used under the hood to query data for this UI component. That’s why the metadataQuery prop needs to be a valid query that matches the specification.

Note that the metadata template key may differ from its display name that is visible in the Admin Console UI (though it’s available in its URL address). The same goes for field keys and display names  —  once you change the display name of a field in the Admin Console UI, the change is not reflected in the field key. It prevents breaking the component in case somebody wants to change the display name. For field display names written in non-latin alphabets, the field key is changed to a more generic name.

Showing metadata columns

Let’s dive into defining metadata columns with precise control over display, sorting, and sizing. As you could see in the snippets above, there is a new way of displaying the metadata table in the component. Instead of fieldToShow there is a new property called columns. It accepts a few more parameters including minWidth, maxWidth, type, and more.

const columns = [
   {
      textValue: "METADATA_FIELD_DISPLAY_NAME", // or our your custom value
      id: `${metadataFieldNamePrefix}.${METADATA_FIELD_KEY}`,
      type: field.type, // Could be string, float, date, multiSelect, ect.
      allowsSorting: true,
      minWidth: 150,
      maxWidth: 150,
   },
   ...
];
This prop is an array of objects and is nested in the required metadataViewProps object:
metadataViewProps: {
   columns
},

This prop is an array of objects and is nested in the required metadataViewProps object:

metadataViewProps: {
   columns
},

Enabling rows selection

You can now enable the ability to select individual rows. Once the user selects one or more items, the header includes the selection descriptor and the metadata edit button. This feature is required to enable single and bulk actions described in the sections below. Row selection is scoped to the paginated content.

Enabling rows selection

To enable the selection feature, set the isSelectionEnabled to true, within the metadataViewProps object, just like in the code snippet below:

const contentExplorer = new Box.ContentExplorer();

contentExplorer.show(FOLDER_ID, ACCESS_TOKEN, {
 ...
 metadataViewProps: {
   columns,
   isSelectionEnabled: true
 },
});

Editing metadata

When one or more items are selected, the Metadata button in the component header may be selected, which opens up a sidebar. This allows for editing items displayed in the component sidebar. The amount of files selected is visible in the component header. This feature is enabled out of the box, with no additional props required.

Editing Metadata

Filtering metadata

Another functionality available in v2 of enhanced Content Explorer is filtering. Users can now filter items by the file type, filter folders, or filter by metadata field values specified in the Box metadata template.

Filtering metadata

Filter chips are enabled by default. To disable the All Filters chip, set the isAllFiltersDisabled to true in the actionBarProps object:

const contentExplorer = new Box.ContentExplorer();

contentExplorer.show(FOLDER_ID, ACCESS_TOKEN, {
... 
metadataViewProps: {
  columns,
  isSelectionEnabled: true,
  actionBarProps: {
    isAllFiltersDisabled: true,
  }
}
});

Toggling list and grid view

With v2 of Content Explorer, we’ve introduced the grid view. Users can now seamlessly toggle between the list and grid view with a dedicated button in the component action bar. Other functionalities like selecting, filtering, and editing are also available within this view.

Toggling list and grid view

To disable grid view set actionBarProps.isViewModeButtonDisabled to true within the metadataViewProps object, just like in the code snippet below:

const contentExplorer = new Box.ContentExplorer();

contentExplorer.show(FOLDER_ID, ACCESS_TOKEN, {
 ...
 metadataViewProps: {
   columns,
   actionBarProps: {
     isViewModeButtonDisabled: true,
   }
 },
});

Migrating to V2

Migrating to v2 requires the following configuration changes in your component invocation:

  1. Upgrade the box-ui-elements package version to at least 24.0.0.
  2. Add the feature flag to enable the enhanced metadata view.
features: {
  contentExplorer: {
      metadataViewV2: true
  }
}

3. Convert your metadata fieldToShow configuration to the new column object. Pass the columns array to the new metadataViewProps object.

const columns = [
   {
      textValue: "METADATA_FIELD_DISPLAY_NAME", // or our your custom value
      id: `${metadataFieldNamePrefix}.${METADATA_FIELD_KEY}`,
      type: field.type,
      allowsSorting: true,
      minWidth: 150,
      maxWidth: 150,
   },
   ...
];

4. Configure the component with additional options like custom actions, bulk actions, selection, and so on.

Style and customize

The enhanced metadata view of Content Explorer can be customized even further. Be sure to check out other articles on Box UI Elements theming, styling, and advanced customization.

How to style and customize Box UI Elements

Let’s talk about UI Elements and interceptors

This release included some significant uplift to the Content Explorer Metadata View. We recommend you to try it out and experience metadata management with ease and scale. Be sure to follow our developer changelog, as the list of features will expand in the following months.

🦄 Want to engage with other Box Platform champions?

Join our Box Developer Community for support and knowledge sharing.

Related Products
Related Articles