コンテンツエクスプローラ – メタデータビューv2

ガイド Boxの埋め込み UI Element コンテンツエクスプローラ – メタデータビューv2

必須のガイド

ガイドインストール

コンテンツエクスプローラ – メタデータビューv2

コンテンツエクスプローラのメタデータビューを使用すると、メタデータに基づいてファイルやフォルダを表示できます。

メタデータビューv2は、Box Content Explorer UI Elementの元のメタデータビューのデザインを根本から変更したもので、メタデータ駆動型ワークフローに合わせて合理化されたインターフェースが導入されています。主な機能には、メタデータフィールドのタイプごとに専用のUIを備えたフィルタおよび編集用のインターフェース、リストビューとグリッドビューを使用した柔軟な表示オプション、ページネーションのサポートなどがあります。

コンテンツエクスプローラのメタデータビューv2を実装する前に、以下を準備できていることを確認してください。

box-ui-elementsパッケージv24.0.0以上、React v18.0.0、Node.js v18.0.0以上
適切なCORS設定を含むBox Platformアプリ
有効な開発者トークン
対象のフォルダまたはファイルに適用されている構成済みのメタデータテンプレート。APIを使用したテンプレートの作成または管理コンソールを使用したテンプレートの作成を確認してください。

必ずカスケードポリシーを有効にするようにしてください。詳細な手順については、テンプレートのカスタマイズと適用の手順を参照してください。

メタデータビューのインターフェースは、以下の領域で構成されています。

ヘッダー – 現在のビューのタイトル、ナビゲーション、コンテキストに応じた情報 (選択数など) が表示されます。ヘッダーの値は、titleプロパティで指定できます。定義されていない場合は、デフォルトで、ancestor_folder_idで指定されているフォルダ名に設定されます。
操作バー – 各メタデータフィールドのフィルタチップ、並べ替えオプション、表示モードの切り替えボタン (リストまたはグリッド) が含まれています。
ページネーションのフッター – [前へ] および [次へ] ナビゲーションボタンとページインジケータが提供されます。

コンテンツエクスプローラのメタデータビューを表示するには、以下のプロパティが必要です。

プロパティ	説明
`token`	開発者コンソールで生成された開発者トークン。
`title`	コンポーネント全体のタイトル。定義されていない場合は、デフォルトで、`ancestor_folder_id`で指定されているフォルダ名が設定されます。
`defaultView`	`metadata`に設定する必要があります。
`features.contentExplorer.metadataViewV2`	メタデータビュー (v2) を有効にするには、trueに設定する必要があります。
`metadataQuery`	メタデータクエリAPIのスキーマに一致するメタデータクエリのリクエスト本文。
`metadataViewProps`	コンポーネントの構成。構成の詳細については、`metadataViewProps`オブジェクトを参照してください。
`columns`	メタデータテーブルの列の構造と動作を定義します。詳細については、列を参照してください。

ニーズや設定に応じて、Box UI Elementsは、Vanilla JavaScriptまたはReactとともに使用できます。インストールの詳細については、インストールガイドを参照してください。

大文字で記述された文字列は、カスタム値に置き換える必要があります。

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
    ...
  }
});

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
       token={TOKEN}
       defaultView="metadata"
       features={features}
       metadataQuery={metadataQuery}
       metadataViewProps={metadataViewProps}
     />
   </IntlProvider>
 );
};

export default ContentExplorerContainer;

列プロパティでは、メタデータテーブルの列の構造と動作を定義します。

プロパティ	型	必須	説明
`id`	string	はい	次の形式のメタデータフィールド識別子: `metadata.<scope>.<templateKey>.<field>`
`textValue`	string	はい	列ヘッダーの表示名。
`type`	string	はい	Boxメタデータフィールドのタイプ (`string`、`number`、`date`、`singleSelect`、`multiSelect`)。
`allowsSorting`	boolean	いいえ	列ヘッダーの並べ替えを有効にします。
`minWidth`	number	いいえ	列の幅の最小値 (ピクセル単位)。
`maxWidth`	number	いいえ	列の幅の最大値 (ピクセル単位)。

個々の行の選択を有効化できます。1行以上が選択されると、ヘッダーが更新され、選択記述子とメタデータ編集ボタンが表示されます。これにより、ユーザーは、単一の操作または一括操作を実行できます。行の選択の範囲は、ページ割りされたコンテンツに限定されます。

選択機能を有効にするには、metadataViewPropsオブジェクト内でisSelectionEnabledプロパティをtrueに設定します。

const contentExplorer = new Box.ContentExplorer();

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

1つ以上の項目が選択されると、コンポーネントのヘッダーには、選択した数が表示され、[メタデータ] ボタンがアクティブになります。[メタデータ] ボタンをクリックすると、サイドバーが開き、ユーザーは、選択した項目のメタデータを表示したり編集したりできます。

この動作は、デフォルトで有効になっています。つまり、有効にするために、追加のプロパティは必要ありません。

ファイルタイプで項目にフィルタをかけたり、フォルダにフィルタをかけたり、Boxのメタデータテンプレートで指定されたメタデータフィールド値でフィルタをかけたりできます。

フィルタチップは、デフォルトで有効になっています。[すべてのフィルタ] チップを無効にするには、actionBarPropsオブジェクトのisAllFiltersDisabledをtrueに設定します。

const contentExplorer = new Box.ContentExplorer();

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

グリッドビューは、操作バーにある表示モード切り替えボタンからデフォルトで利用可能です。グリッドビューがアクティブな場合は、ズームコントロールが使用可能になります。選択、フィルタ、編集などのその他の機能もこのビュー内で使用できます。

グリッドビューを無効にするには、metadataViewPropsオブジェクト内でactionBarProps.isViewModeButtonDisabledをtrueに設定します。

const contentExplorer = new Box.ContentExplorer();

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

このUI Elementでは、フッターが常に表示された状態で、マーカーベースのページネーションのみが使用されます。オフセットまたはページ番号は設定できません。ユーザーが移動する際は [前へ] と [次へ] しか使用できません。無制限のスクロールはサポートされていません。

コンテンツエクスプローラのメタデータビューのv1は公式サポートが終了しました。v1は24.0.0パッケージで引き続き利用できますが、バグ修正や新機能は提供されなくなります。最新の機能が提供されるようにするには、移行ガイドに従い、コンテンツエクスプローラのv2のメタデータビューに切り替えてください。

box-ui-elementsパッケージを使用してプロジェクト内でv1からv2に移行するには:

box-ui-elementsパッケージのバージョンをバージョン24.0.0以上にアップグレードします。
box-ui-elementsピア依存関係が依存関係としてpackage.jsonファイルに追加されていることを確認します。これは、パッケージマネージャを使用してインストールします。
featuresフラグを追加して、強化されたメタデータビューを有効にします。

features: {
   contentExplorer: {
       metadataViewV2: true
   }
}

メタデータのfieldToShowの構成を新しい列オブジェクトに変換します。Boxメタデータテンプレートの値に対応するフィールドタイプを追加します。列の配列を新しいmetadataViewPropsオブジェクトに渡します。

const columns = [
    {
       textValue: "METADATA_FIELD_DISPLAY_NAME", // Altenratively pass a custom value
       id: `${metadataFieldNamePrefix}.${METADATA_FIELD_KEY}`,
       type: field.type,
       allowsSorting: true, // Optional
       minWidth: 150, // Optional; the default value is 220
       maxWidth: 150, // Optional; the default value is 220
    },
    ...
];

必要に応じて、このガイドで説明されている追加機能を構成します。

CDNのインポートを使用してプロジェクト内でv1からv2に移行するには:

CDNリンクにバージョン24.0.0以上のパッケージバージョンが含まれていることを確認します。
featuresフラグを追加して、強化されたメタデータビューを有効にします。

features: {
   contentExplorer: {
       metadataViewV2: true
   }
}

メタデータのfieldToShowの構成を新しい列オブジェクトに変換します。Boxメタデータテンプレートの値に対応するフィールドタイプを追加します。列の配列を新しいmetadataViewPropsオブジェクトに渡します。

const columns = [
    {
       textValue: "METADATA_FIELD_DISPLAY_NAME", // Altenratively pass a custom value
       id: `${metadataFieldNamePrefix}.${METADATA_FIELD_KEY}`,
       type: field.type,
       allowsSorting: true, // Optional
       minWidth: 150, // Optional; the default value is 220
       maxWidth: 150, // Optional; the default value is 220
    },
    ...
];

必要に応じて、このガイドで説明されている追加機能を構成します。

コンテンツエクスプローラ – メタデータビューv2

必須のガイド

コンテンツエクスプローラ – メタデータビューv2

概要

前提条件

インターフェースの領域

メタデータビューの表示

Vanilla JavaScriptのコードスニペット

Reactのコードスニペット

列

機能

行の選択の有効化

メタデータ値の編集

メタデータのフィルタ

リストビューとグリッドビューの切り替え

ページネーション

v1からv2への移行

Npmパッケージ

CDN

関連するガイド