Simple hierarchical select
タクソノミーフィールドを階層セレクトボックスで表示するウィジェットを提供するモジュールです。
shs
インストール
composer require 'drupal/shs:^2.0'
概要
Simple hierarchical select (SHS) は、Drupalのタクソノミータームリファレンスフィールドを、階層構造を反映した連動セレクトボックスとして表示するモジュールです。親タームを選択すると、その子タームが次のセレクトボックスに自動的に表示される、ユーザーフレンドリーな階層選択UIを提供します。
このモジュールは、エンティティフォームでのフィールドウィジェットとしてだけでなく、Viewsの公開フィルター（Exposed Filter）としても利用可能です。さらに、選択されたタームを階層パンくずリスト形式で表示するフォーマッターも含まれています。
Backbone.jsを使用したAjax駆動のウィジェットにより、大量のタクソノミータームを持つボキャブラリでも軽快に動作します。タームデータはAjaxで非同期に読み込まれ、キャッシュされるため、パフォーマンスが最適化されています。
Features
- タクソノミータームリファレンスフィールドを階層構造を反映した連動セレクトボックスとして表示
- Viewsの公開フィルターとして使用可能（Has taxonomy terms / Has taxonomy terms with depth フィルター対応）
- 選択されたタームの階層パスをパンくずリスト形式で表示するフォーマッター
- 最深レベルの選択を強制するオプション（カテゴリの末端タームのみ選択可能）
- Backbone.jsによるAjax駆動で大量のタームでも軽快動作
- タームデータの自動キャッシュによるパフォーマンス最適化
- 多言語サイト対応（content_translationモジュールとの統合）
- 未公開タームの表示制御（権限に基づく）
- Search APIモジュールとの統合
- Chosenライブラリとの統合（サブモジュール shs_chosen）
- 豊富なフックによるカスタマイズ対応
Use Cases
製品カテゴリの階層選択
ECサイトで「電化製品 > スマートフォン > Android」のような多階層の製品カテゴリを持つ場合、SHSウィジェットを使用することで、ユーザーは親カテゴリから順に選択していくことができます。「Force selection of deepest level」オプションを有効にすれば、最も詳細なカテゴリレベルでの選択を強制できます。
地域の階層フィルター
不動産サイトや店舗検索サイトで「国 > 都道府県 > 市区町村」のような地域階層でコンテンツをフィルタリングする場合、ViewsにSHS公開フィルターを設定することで、ユーザーは直感的に地域を絞り込むことができます。
組織階層の選択
社内ポータルで「本社 > 部門 > チーム」のような組織階層を選択する場合、SHSウィジェットにより複雑な階層構造でも分かりやすいUIを提供できます。hook_shs_FIELDNAME_js_settings_alterを使用して各レベルに「会社」「部門」「チーム」などのカスタムラベルを設定できます。
タクソノミーの階層パス表示
選択されたカテゴリをノード表示時に階層パス（パンくずリスト形式）で表示したい場合、SHSフォーマッターを使用します。「電化製品 > スマートフォン > Android」のような形式で表示され、各タームをタームページへのリンクにすることも可能です。
大量タームを持つボキャブラリでの使用
数千件のタームを持つ大規模なタクソノミーでは、標準のセレクトボックスは表示が重くなります。SHSはAjaxで必要なタームのみを非同期に読み込むため、初期ロードが軽量で、大量データでも快適に動作します。
検索可能な階層セレクト
各階層レベルでタームを検索したい場合は、shs_chosenサブモジュールを有効化します。Chosenライブラリの検索機能により、長いタームリストでも目的のタームを素早く見つけることができます。
Tips
- フォームの見た目をカスタマイズしたい場合は、css/shs.form.css と css/shs.formatter.css を参考に、テーマでCSSをオーバーライドしてください
- 各階層レベルにカスタムラベルを設定するには、hook_shs_FIELDNAME_js_settings_alter() を実装し、$settings_shs['labels'] 配列を設定します
- セレクトボックスのアニメーション速度を変更するには、hook_shs_js_settings_alter() で $settings_shs['display']['animationSpeed'] を設定します（デフォルト400ms）
- タームの表示名をカスタマイズしたい場合は、hook_shs_term_data_alter() を使用してタームデータを変更できます
- ウィジェットの動作を大幅にカスタマイズしたい場合は、hook_shs_class_definitions_alter() でカスタムBackbone.jsクラスを指定できます
- Viewsフィルターで「Has taxonomy terms (with depth)」を使用すると、選択したタームの子タームを持つコンテンツも含めてフィルタリングできます
- パフォーマンスを考慮する場合、hook_shs_term_data_alter()（キャッシュ前）よりもhook_shs_term_data_response_alter()（キャッシュ後）の方が呼び出し回数が多いことに注意してください
Technical Details
Hooks 10
hook_shs_class_definitions_alter
SHSウィジェットで使用されるJavaScriptのモデル・ビュークラスを変更する。カスタムのBackbone.jsクラスを使用してウィジェットの動作をカスタマイズできる。
hook_shs_FIELDNAME_class_definitions_alter
特定のフィールド名に対してのみJavaScriptクラス定義を変更する。フィールド固有のカスタマイズに使用。
hook_shs_js_settings_alter
エンティティフォームやViewsでのSHSウィジェットのJavaScript設定を変更する。ラベル、アニメーション速度などをカスタマイズ可能。
hook_shs_FIELDNAME_js_settings_alter
特定のフィールドに対するJavaScript設定を変更する。階層レベルごとのラベル設定やアニメーション速度の調整に使用。
hook_shs_term_data_alter
キャッシュ前のタームデータを変更する。タームの表示名やプロパティをカスタマイズ可能。
hook_shs__bundle_BUNDLE_NAME__term_data_alter
特定のボキャブラリに対するキャッシュ前のタームデータを変更する。
hook_shs__field_IDENTIFIER__term_data_alter
特定のフィールドに対するキャッシュ前のタームデータを変更する。
hook_shs_term_data_response_alter
ブラウザに送信されるキャッシュ済みJSONレスポンスを変更する。リクエストごとに呼び出されるため、パフォーマンスに注意。
hook_shs__bundle_BUNDLE_NAME__term_data_response_alter
特定のボキャブラリに対するJSONレスポンスを変更する。
hook_shs__field_IDENTIFIER__term_data_response_alter
特定のフィールドに対するJSONレスポンスを変更する。
Troubleshooting 6
フィールドが単一のボキャブラリのみをターゲットにしているか確認してください。SHSウィジェットは、ハンドラー設定で1つのボキャブラリのみが選択されているフィールドでのみ動作します。複数のボキャブラリをターゲットにしているフィールドでは、SHSウィジェットオプションは表示されません。
ブラウザの開発者ツールでネットワークタブを確認し、/shs-term-data/へのAjaxリクエストが正常に返っているか確認してください。また、タームが公開状態であるか、ユーザーに未公開タームを表示する権限があるか確認してください。
SHSはタームデータをキャッシュします。タームを追加・編集した後にウィジェットに反映されない場合は、Drupalのキャッシュをクリアしてください。キャッシュはtaxonomy_term_valuesタグと各タームのIDに基づいて無効化されます。
このオプションは、選択されたタームに子タームがあるかどうかをチェックします。必須フィールドでない場合、空の選択（- None -）は許可されます。また、選択可能なオプションが1つしかない場合はエラーは表示されません。
公開フィルターの「Remember」オプションが有効になっているか確認してください。また、フィルターの識別子（Identifier）が他のフィールドと重複していないか確認してください。
Content Translationモジュールが有効で、ボキャブラリに対して翻訳が有効になっているか確認してください。SHSは自動的にContent Translationの設定を検出し、対応した言語の翻訳を表示します。
Security Notes 3
- SHSのタームデータエンドポイント（/shs-term-data/）は「access content」パーミッションで保護されています
- 未公開タームは「administer taxonomy」または「view unpublished terms in [vocabulary]」パーミッションを持つユーザーにのみ表示されます
- タームデータのキャッシュはユーザーロールに基づいて分離されるため、権限の異なるユーザー間でデータが漏洩することはありません