Box Developerドキュメント

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

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

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

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

概要

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

メタデータビュー

前提条件

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

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

インターフェースの領域

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

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

メタデータビューの表示

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

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

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

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

Vanilla JavaScriptのコードスニペット

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

Reactのコードスニペット

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;

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

プロパティ必須説明
idstringはい次の形式のメタデータフィールド識別子: metadata.<scope>.<templateKey>.<field>
textValuestringはい列ヘッダーの表示名。
typestringはいBoxメタデータフィールドのタイプ (stringnumberdatesingleSelectmultiSelect)。
allowsSortingbooleanいいえ列ヘッダーの並べ替えを有効にします。
minWidthnumberいいえ列の幅の最小値 (ピクセル単位)。
maxWidthnumberいいえ列の幅の最大値 (ピクセル単位)。

機能

行の選択の有効化

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

行の選択

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

const contentExplorer = new Box.ContentExplorer();

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

メタデータ値の編集

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

メタデータの編集

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

メタデータのフィルタ

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

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

const contentExplorer = new Box.ContentExplorer();

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

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

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

グリッドビュー

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

const contentExplorer = new Box.ContentExplorer();

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

ページ割り

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

v1からv2への移行

Npmパッケージ

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

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

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

  1. メタデータの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
    },
    ...
];

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

CDN

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

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

  1. メタデータの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
    },
    ...
];

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