Client-side Hierarchical Select
タクソノミータームをクライアントサイドで階層的に選択できるフィールドウィジェットを提供するモジュール。
cshs
インストール
composer require 'drupal/cshs:^4.0'
概要
Client-side Hierarchical Select（CSHS）は、Drupalのタクソノミー（分類）タームを階層構造に沿って段階的に選択できるウィジェットを提供するモジュールです。従来の単一セレクトボックスではなく、階層の各レベルに対応した複数のセレクトボックスを動的に生成し、ユーザーが直感的に階層構造をナビゲートできます。
このモジュールの特徴は、タクソノミーツリー全体をページ読み込み時にクライアント（ブラウザ）に送信し、JavaScriptによって選択に応じた子セレクトボックスを動的に構築する点です。これにより、サーバーへの追加リクエストなしに高速な階層選択が実現されます。
SHSやHierarchical Selectなどの類似モジュールとは異なり、CSHSはすべての処理をクライアントサイドで行うため、レスポンスが高速でサーバー負荷が軽減されます。多言語対応、Views統合、開発者向けAPIなど、実用的な機能を備えています。
Features
- タクソノミータームの階層選択ウィジェット - 各階層レベルに対応したセレクトボックスを動的に生成し、ユーザーが段階的にタームを選択可能
- 多言語対応（Multilingual）- Drupalコアの国際化機能を尊重し、翻訳されたタクソノミーターム名を正しく表示
- Views統合 - タクソノミーターム参照フィールドの露出フィルターとしてCSHSウィジェットを使用可能
- 開発者向けForm API - カスタムフォームで「cshs」タイプの要素として使用可能、タクソノミー以外のカスタムオプションにも対応
- 複数のフィールドフォーマッター - 階層全体表示、ルートでグループ化、特定レベル表示、トークンベースの柔軟な表示形式
- 階層深さの制限 - 表示する階層レベル数を制限可能
- 必須深さの設定 - ユーザーに特定の深さまでの選択を強制
- 最深レベル選択の強制 - 子を持たないタームのみ選択可能にする機能
- 系統保存（Save Lineage）- 選択したタームだけでなく、ルートからの全親タームも保存
- 階層レベルごとのラベル設定 - 各セレクトボックスに個別のラベルを表示
- 未公開タームの表示オプション - 通常は非公開のタームも選択肢に含める設定
- Conditional Fields連携 - conditional_fieldsモジュールとの統合ハンドラー提供
- JavaScript API - 階層変更時のカスタムイベント（simplerSelectChildCreated、simplerSelectChildrenDeleted）をフック可能
Use Cases
地域・住所の階層選択
「国 → 都道府県 → 市区町村」のような地理的階層を持つタクソノミーで、ユーザーが段階的に地域を絞り込んで選択するフォームを構築できます。level_labelsで「国」「都道府県」「市区町村」のようなラベルを設定し、required_depthで最低限の選択レベルを強制できます。
製品カテゴリの階層選択
ECサイトで「大カテゴリ → 中カテゴリ → 小カテゴリ」のような製品分類を階層的に選択させることができます。force_deepestを有効にすることで、必ず末端カテゴリまで選択させることが可能です。
組織構造の選択
「会社 → 部門 → 課 → 係」のような組織階層をタクソノミーで管理し、所属部署を選択するフォームを構築できます。save_lineageを有効にすると、選択した係だけでなく、所属する課・部門・会社の情報もすべて保存されます。
Viewsの階層フィルター
コンテンツ一覧ページで、タクソノミーターム参照フィールドを露出フィルターとして設定し、CSHSウィジェットで階層的な絞り込みUIを提供できます。ユーザーは上位カテゴリから順に選択し、関連コンテンツを絞り込めます。
メニュー構造のナビゲーション
cshs_menu_linkサブモジュールを使用すると、ノード編集時のメニューリンク親選択で、深いメニュー階層をわかりやすく選択できます。フラットなリストではなく、階層構造を反映したUI で目的の位置を見つけやすくなります。
カスタムフォームでの階層選択
Form APIのcshs要素を使用して、タクソノミー以外のカスタムデータでも階層選択UIを構築できます。CshsOptionクラスでオプションと親子関係を定義し、独自の階層データを表示できます。
Tips
- 大規模なタクソノミーツリーでは、parent設定で開始タームを指定し、必要なサブツリーのみを表示することでパフォーマンスを改善できます
- level_labelsを設定すると、各セレクトボックスの用途が明確になり、ユーザビリティが向上します
- force_deepestを使用すると、必ず末端タームが選択されることが保証され、データの一貫性が保たれます
- Flexible Hierarchyフォーマッターは、Tokenモジュールと組み合わせて高度なカスタム表示を実現できます
- JavaScriptイベント（simplerSelectChildCreated等）を使用して、選択に連動したカスタムロジックを実装できます
- 複数のボキャブラリーを対象にする場合、optgroupで自動的にボキャブラリー別にグループ化されます
Technical Details
Hooks 1
hook_cshs_item_alter
CSHSオプションアイテムのレンダリング前に値を変更するためのフック。各オプションがレンダリングされる前に呼び出されます。
Troubleshooting 6
フィールドがエンティティ参照（タクソノミーターム）型であり、かつ「デフォルトエンティティ参照選択ハンドラー」を使用し、少なくとも1つのボキャブラリーが選択されていることを確認してください。これらの条件を満たさない場合、警告メッセージが表示されます。
この機能は無制限カーディナリティ（unlimited）のフィールドでのみ使用可能です。また、一度でもデータが保存されると変更できなくなります。新規フィールドを作成するか、既存データを削除してください。
hierarchy_depth設定を確認してください。0はすべてのレベルを表示します。また、force_deepestが有効な場合、hierarchy_depthとrequired_depthは無視されます。
タクソノミーツリーがページ読み込み時にすべてロードされているか確認してください。ブラウザのデベロッパーツールでJavaScriptエラーがないか確認し、drupalSettingsにcshs設定が含まれているか確認してください。
ウィジェット設定で「Allow unpublished terms」（未公開タームを許可）を有効にしてください。デフォルトでは公開ステータスのタームのみ表示されます。
フィルターの「Selection type」で「Client-side Hierarchical Select」が選択されていることを確認してください。また、フィルター設定でボキャブラリーが正しく選択されていることを確認してください。
Security Notes 3
- このモジュールはDrupal Security Teamによるセキュリティカバレッジ対象です
- allow_unpublished設定を有効にすると未公開タームが表示されるため、機密性の高いタクソノミーでは注意が必要です
- Form APIを使用したカスタム実装では、ユーザー入力の適切なサニタイズとバリデーションを行ってください