コンテンツエクスプローラ

ガイド Boxの埋め込み UI Element コンテンツエクスプローラ

コンテンツエクスプローラ

Box Content Explorer UI Elementを使用すると、開発者は、Boxに保存されているコンテンツのフォルダビューをデスクトップまたはモバイルウェブアプリに埋め込むことができます。ライブラリはBox APIを介して指定されたフォルダに関する情報を取得した後、メインのBoxウェブアプリと同様にそのコンテンツをフォルダビューにレンダリングします。ユーザーは、そのフォルダ階層内を移動し、名前の変更、削除、共有などのファイル操作を実行できます。

コンテンツエクスプローラで、メタデータビューを使用できるようになりました。このビューでは、メタデータクエリを使用して、メタデータに基づいてファイルやフォルダを検索できます。データは埋め込みのビューに表示されます。

インストール

NPMまたはBox CDN経由でBox UI Elementsをインストールする方法は、こちらを参照してください。

認証

UI Elementは認証に依存しない方法で設計されているため、Boxアカウントを持つユーザー (管理対象ユーザー) とBox以外のアカウントを持つユーザー (App User) のどちらにUI Elementを使用するかどうかに関係なく、UI Elementを使用するのに特別な設定は必要ありません。その理由は、UI Elementは認証のために「トークン」を受け取ることのみを予期しており、Boxにはトークンの生成方法としてOAuthとJWTの2つがあるからです。

認証方法の選択について確認する

サンプルHTML

<!DOCTYPE html>
<html lang="en-US">
    <head>
        <meta charset="utf-8" />
        <title>Box Content Explorer Demo</title>

        <!-- Latest version of the explorer css for your locale -->
        <link
            rel="stylesheet"
            href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.css" />
    </head>
    <body>
        <div class="container" style="height:600px"></div>
        <!-- Latest version of the explorer js for your locale -->
        <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.js"></script>
        <script>
            var folderId = "123";
            var accessToken = "abc";
            var contentExplorer = new Box.ContentExplorer();
            contentExplorer.show(folderId, accessToken, {
                container: ".container",
            });
        </script>
    </body>
</html>

デモ

API

const { ContentExplorer } = Box;
const contentExplorer = new ContentExplorer();

/**
 * Shows the content explorer.
 *
 * @param {string} folderId - The root folder id
 * @param {string} accessToken - Box API access token
 * @param {Object} [options] - Options
 * @return {void}
 */
contentExplorer.show(folderId, accessToken, options);

/**
 * Hides the content explorer, removes all event listeners, and clears out the
 * HTML.
 *
 * @return {void}
 */
contentExplorer.hide();

/**
 * Clears out the internal in-memory
 * cache for the content explorer forcing
 * re-load of items via the API.
 *
 * @public
 * @return {void}
 */
contentExplorer.clearCache();

/**
 * Adds an event listener to the content explorer. Listeners should be added
 * before calling show() so no events are missed.
 *
 * @param {string} eventName - Name of the event
 * @param {Function} listener - Callback function
 * @return {void}
 */
contentExplorer.addListener(eventName, listener);

/**
 * Removes an event listener from the content explorer.
 *
 * @param {string} eventName - Name of the event
 * @param {Function} listener - Callback function
 * @return {void}
 */
contentExplorer.removeListener(eventName, listener);

/**
 * Removes all event listeners from the content explorer.
 *
 * @return {void}
 */
contentExplorer.removeAllListeners();

パラメータ

パラメータ説明
folderIdStringBoxフォルダのID。中を移動するフォルダのIDになります。Boxの [すべてのファイル] フォルダを使用する場合は、folderIdとして0を使用します。
accessTokenString使用するBox APIアクセストークン。このトークンには、上記のフォルダに対する読み取り/書き込みアクセス権限が必要です。このトークンのために渡される値は、エクスプローラの表示中は有効期限切れにならないことが前提となっています。
optionsObject省略可能なオプション。詳細は以下を参照してください。たとえば、contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})を使用すると、削除オプションが非表示になります。

オプション

パラメータデフォルト説明
containerStringdocument.bodyコンテンツエクスプローラが配置されるコンテナのCSSセレクタ。hide() を呼び出すと、このコンテナは空になります。
sortByStringnameコンテンツリストの最初の並べ替え基準オプション。値はidnamedateまたはsizeになります。
sortDirectionStringASCコンテンツリストの最初の並べ替え方向オプション。値はASCまたはDESCになります。
logoUrlStringヘッダーに表示するカスタムロゴのURL。この値が「box」という文字列の場合は、Boxのロゴが表示されます。
canPreviewBooleantrueこのオプションがtrueに設定されていて、ファイルに対するcan_preview権限がtrueの場合、コンテンツエクスプローラでファイルをクリックできます。ファイルをクリックするとそのファイルのプレビューが開始されます。ファイルに対する権限can_previewfalseに設定されている場合、このオプションによる効果はありません。このオプションは、プレビュー可能なファイルのみに適用できます。
canDownloadBooleantrueこれをfalseに設定すると、ダウンロードオプションが非表示になります。このオプションを非表示にするだけではダウンロードを防ぐことはできず、ファイルに対する権限でもcan_downloadfalseに設定する必要があります。ファイルに対する権限can_downloadfalseに設定されている場合、このオプションによる効果はありません。このオプションは、ファイルのみに適用できます。
canDeleteBooleantrueこれをfalseに設定すると、削除オプションが非表示になります。このオプションを非表示にするだけでは削除を防ぐことはできず、項目に対する権限でもcan_deletefalseに設定する必要があります。項目に対する権限can_deletefalseに設定されている場合、このオプションによる効果はありません。
canRenameBooleantrueこれをfalseに設定すると、名前の変更オプションが非表示になります。このオプションを非表示にするだけでは名前の変更を防ぐことはできず、項目に対する権限でもcan_renamefalseに設定する必要があります。
canUploadBooleantrueこれをfalseに設定すると、アップロードオプションが非表示になります。このオプションを非表示にするだけではアップロードを防ぐことはできず、現在のフォルダに対する権限でもcan_uploadfalseに設定する必要があります。フォルダに対する権限can_uploadfalseに設定されている場合、このオプションによる効果はありません。
canCreateNewFolderBooleantrueフォルダの新規作成オプションが非表示になります。このオプションを非表示にするだけではフォルダの新規作成を防ぐことはできず、フォルダ項目に対する権限でもcan_uploadfalseに設定する必要があります。フォルダ項目に対する権限can_uploadfalseに設定されている場合、このオプションによる効果はありません。
canShareBooleantruefalseに設定すると、共有ボタンが非表示になります。このボタンを非表示にするだけでは共有を防ぐことはできず、項目のpermissionsでもcan_shareをfalseに設定する必要があります。項目に対する権限can_sharefalseに設定されている場合、このオプションによる効果はありません。
canSetShareAccessBooleantruefalseに設定すると、共有権限の変更を許可する共有ドロップダウン選択が非表示になります。この選択のドロップダウンを非表示にするだけでは共有権限の変更を防ぐことはできず、項目に対する権限でもcan_set_share_accessfalseに設定する必要があります。項目に対する権限can_set_share_accessfalseに設定されている場合、このオプションによる効果はありません。
sharedLinkString共有リンクのURL。フォルダが共有されており、アクセストークンがファイルの所有者またはコラボレータに属していない場合は必須です。
sharedLinkPasswordString共有リンクのパスワード。共有リンクにパスワードが設定されている場合は必須です。
sizeStringundefinedコンテンツエクスプローラがコンテナの幅の大小に合わせて表示されるように示します。値には空白か、smallまたはlargeを指定できます。空白にした場合、UI Elementはそのコンテナに合わせて調整され、自動でsmallの幅とlargeの幅が切り替わります。
isTouchBooleanデフォルトでは、ブラウザとデバイスのデフォルトのタッチサポートが設定されます。コンテンツエクスプローラがタッチ対応デバイスにレンダリングされることを示します。
autoFocusBooleanfalsetrueに設定すると、初回読み込み時に項目グリッドに焦点が当てられます。
defaultViewStringfiles値はfilesrecents、またはmetadataになります。recentsに設定すると、デフォルトで、通常のファイル/フォルダ構造ではなく、最近使用した項目が表示されます。コンテンツエクスプローラでメタデータビューを表示するには、metadataを指定する必要があります。指定しない場合、通常のフォルダビューが表示されます。
requestInterceptorFunctionリクエストをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。
responseInterceptorFunctionレスポンスをインターセプトする関数。例については、このCodePenを参照してください。基盤となるXHRライブラリはaxios.jsで、インターセプタでは同様のアプローチに従っています。
ContentOpenWithPropsObject{ show: false }エクスプローラからプレビューする際にOpen With Elementを表示できます。
tokenString開発者コンソールで生成された開発者トークン。
metadataQueryObjectメタデータビューの情報を取得するために使用されるメタデータクエリ。
rootFolderIDStringメタデータテンプレートが適用されているフォルダのID。metadataQueryはこのフォルダに適用されます。
fieldsToShowObject表示するメタデータフィールド/列 - メタデータテンプレートの有効なフィールド名を指定する必要があります。

イベント

イベント名イベントデータ説明
select`Array<FileウェブリンクFolder>`項目行が選択されたときに発生します。
rename`FileウェブリンクFolder`項目の名前が変更されたときに発生します。
previewFileファイルがプレビューされたときに発生します。
downloadArray<File>項目がダウンロードされたときに発生します。
deleteArray<File>項目が削除されたときに発生します。
uploadArray<File>項目がアップロードされたときに発生します。
navigateFolderフォルダ内に移動したときに発生します。
createFolder新しいフォルダが作成されたときに発生します。

キーボードショートカット

クリックによって手動で、またはJavaScriptや上記のautoFocusプロパティによってプログラムで項目グリッドがフォーカスされていると、以下のキーボードショットカットが機能します (対応する操作が適切で許可されている場合)。

キー動作
Arrow Up前の項目行
Arrow Down次の項目行
Ctrl/Cmd + Arrow Up最初の項目行
Ctrl/Cmd + Arrow Down最後の項目行
/検索
Shift + X項目行を選択
Delete選択した項目を削除
Enter選択した項目を開く
Shift + R選択した項目の名前を変更
Shift + S選択した項目を共有
Shift + D選択した項目をダウンロード
g then fルートフォルダに移動
g then u現在のフォルダにアップロード
g then bルートフォルダの階層リンクをフォーカス
g then r最近使用した項目

スコープ

アプリケーションで、エンドユーザーがコンテンツエクスプローラ機能のサブセットのみにアクセスできるようにする必要がある場合は、ダウンスコープを使用して、アクセストークンを適切にダウンスコープして必要な権限のセットを含むトークンを生成し、コンテンツエクスプローラを初期化するエンドユーザークライアントに安全に渡すことができます。

以下は、ダウンスコープと一緒に使用する、UI Element固有の新しいスコープのセットです。こうしたスコープにより、開発者は、ダウンスコープされたトークンに適切なスコープを構成して、コンテンツエクスプローラのUIコントロールを有効/無効にすることができます。詳細については、Box UI Elementsの専用スコープを参照してください。

基本スコープ

スコープ名付与される権限
base_explorerユーザー/ファイル/トークンの権限に基づいて、フォルダツリー内のコンテンツへのアクセスを許可します。

機能のスコープ

スコープ名付与される権限
item_previewユーザーがクリックしたときにファイルのプレビューを自動的に有効にします (プレビューUI Elementを参照する必要があります)。
item_downloadファイル/フォルダのコンテンツのダウンロードを許可します。
item_renameファイル/フォルダの名前変更を許可します。
item_shareダウンスコープリクエストの「resource」で指定されたリソースの共有を許可します。
item_deleteファイル/フォルダの削除を許可します。

サンプルのシナリオ

シナリオスコープ
ユーザーがフォルダ構造内を移動する (基本機能)base_explorer
ユーザーが基本機能とプレビューを必要とするbase_explorer + item_preview
ユーザーが基本機能、プレビュー、およびダウンロードを必要とするbase_explorer + item_preview + item_download
ユーザーが基本機能、プレビュー、ダウンロード、およびファイル/フォルダ名の変更を必要とするbase_explorer + item_preview + item_download + item_rename
ユーザーがすべての機能 (基本、プレビュー、ダウンロード、名前の変更、共有、アップロード、および削除) を必要とするbase_explorer + item_preview + item_download + item_rename + item_delete + item_share + item_upload

メタデータビュー

コンテンツエクスプローラを使用すると、メタデータに基づいてファイルやフォルダを表示することもできます。このビューはメタデータビューと呼ばれ、メタデータテンプレートとメタデータクエリを使用して、表示するデータを探します。

前提条件

以下がインストールされていることを確認してください。

  • Nodeのバージョン: >=18.18.2 <20.11.0
  • Reactのバージョン: >=17.0.2 <18.0.0
  • BUIEのバージョン: 19.0.0

アプリの作成と構成

  1. Boxアプリを作成します
  2. [CORSドメイン] にローカルでの開発用のアドレスを追加します。 CORSドメイン
  3. 開発者トークンを生成します。

メタデータテンプレートの作成

次の手順では、コンテンツエクスプローラにデータを設定するために使用するメタデータテンプレートを作成します。

  1. メタデータテンプレートを作成します。これには、メタデータAPIまたは管理コンソールを使用できます。
  2. すでに作成済みのテンプレートをBoxフォルダに適用します。必ずカスケードポリシーを有効にするようにしてください。詳細な手順については、テンプレートのカスタマイズと適用の手順を参照してください。

メタデータビューの表示

作業を簡単にするために、サンプルプロジェクトを使用してメタデータビューを起動できます。

  1. メタデータのサンプルプロジェクトを複製します。
  2. App.js内のプレースホルダを実際の値で更新します。
パラメータ説明
DEVELOPER_TOKEN開発者コンソールで生成された開発者トークン
ENTERPRISE_IDアプリケーションの [一般設定] タブからコピーしたEnterprise ID。
METADATA_TEMPLATE_NAME作成済みのメタデータテンプレートの名前。: 適切な名前を指定済みであることを確認するには、メタデータAPIを使用して名前を取得するか、管理コンソールでURLから名前をコピーします。管理コンソールにおけるメタデータ名 UIでテンプレート名を変更しても、変更されるのはラベルのみです。コンポーネントで使用する名前は、常に最初に指定した名前になります。
ROOTFOLDER_IDメタデータテンプレートを適用したBoxフォルダのID。

defaultViewfieldsToShowmetadataQueryの各パラメータは、以下の例に示すように、すでにサンプルプロジェクトで定義されています。

メタデータクエリの詳細については、こちらのガイドを参照してください。

  1. コンテンツエクスプローラコンポーネントに必須パラメータを渡します。
[...]

  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;

コンテンツエクスプローラのメタデータビューを含むReactコンポーネントのサンプルコードは次のようになります。

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">
                <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;

ヒント: 詳細なフローについては、メタデータビューに関するブログ記事を参照してください。