インストール
composer require 'drupal/label_help:8.x-1.0'
概要
Label Helpモジュールは、Drupalのフォームフィールドにヘルプテキストを追加する方法を提供します。このヘルプテキストはフォームラベルの下、かつフォーム入力要素の上に表示されます。これはフォーム要素の下に表示されるDrupal標準のフィールド説明とは異なります。
この配置は、ユーザーがデータを入力し始める前ではなく、フォームフィールドを操作する前に見るべき即座のコンテキストや説明を提供するのに特に便利です。このモジュールは、コンテナ、fieldset、details要素、チェックボックス、ラジオボタン、複数値フィールドなど、さまざまなウィジェット設定を処理するインテリジェントな配置ロジックにより、すべてのField APIフィールドタイプで動作します。
Label HelpはField UIとシームレスに統合され、管理者がヘルプテキストを入力できるシンプルなテキストエリアをフィールド設定に追加します。開発者向けには、プログラムによる使用のためのカスタム#label_help Form APIプロパティも提供し、既存フォームを変更するためのhook_form_alter()でも動作します。
このモジュールには、Drupalの主要な管理テーマ（Seven、Claro、Gin）用の専用テンプレートとCSSが含まれており、異なる管理インターフェース間で一貫した適切なスタイルの表示を保証します。
Features
- Field UIのフィールド設定に「ラベルヘルプメッセージ」テキストエリアを追加し、管理者がWebインターフェースからヘルプテキストを入力可能
- フィールドラベルとフォーム入力要素の間にヘルプテキストを配置し、ユーザーがフィールドを操作する前にコンテキストを提供
- テキストフィールド、チェックボックス、ラジオボタン、セレクトリスト、エンティティ参照、日付、リンク、ファイル、画像など、すべてのField APIフィールドタイプをサポート
- コンテナ、fieldset、details要素、複数値フィールドを含む18種類以上のウィジェット設定を処理する専用の配置ロジックを提供
- Seven、Claro、Gin管理テーマ用のテーマ別テンプレートとCSSを含み、適切なスタイル継承を実現
- カスタムモジュールやテーマでプログラム的にヘルプテキストを追加するための#label_help Form APIプロパティを提供
- 既存のフォームフィールドを変更するためのhook_form_alter()およびhook_FORM_ID_alter()で動作
- 配置の問題をトラブルシューティングするためのデバッグモードを含み、ユースケースのマッチングとForm API要素のダンプを表示
- Drupalの既存のフィールド説明を置き換えるのではなく補完する形で機能し、両方を一緒に使用可能
Use Cases
フィールドの即座のコンテキスト提供
ユーザーがデータ入力を開始する前に見る必要がある重要な説明を提供するためにラベルヘルプを使用します。たとえば、「電話番号」フィールドで「国番号を含めて入力してください（例：+81 3-1234-5678）」というラベルヘルプテキストを追加すると、ユーザーは期待されるフォーマットをすぐに把握できます。
フィールド要件の説明
ユーザーが最初に理解すべきフィールドの特定の要件や制限を説明するためにラベルヘルプを追加します。たとえば、「ユーザー名」フィールドで「3〜20文字、英数字のみ使用可能」というラベルヘルプを追加すると、入力前に要件が見えるようになります。
複雑なフィールドの補足
エンティティ参照や住所フィールドなどの複数値または複雑なフィールドウィジェットでは、ラベルヘルプを使用してフィールドが収集する内容の概要を提供し、詳細な説明や例には下部の標準説明を使用します。
プログラムによるフォーム拡張
カスタムモジュールやテーマで、#label_help Form APIプロパティまたはhook_form_alter()を使用して、フォームにコンテキスト固有のヘルプテキストを追加します。これはユーザーロール、現在のコンテンツ、その他の条件に基づいて動的なヘルプテキストを追加するのに便利です。
コンテンツ編集者へのガイダンス
コンテンツ編集者が各フィールドの目的とベストプラクティスを理解できるようにします。たとえば、「メタ説明」フィールドで「検索エンジン向けにページ内容を155〜160文字で要約」というラベルヘルプを追加すると、必要な場所でSEOガイダンスを提供できます。
Tips
- ラベルヘルプテキストは簡潔に保つ - 素早いコンテキストを提供するものであり、長いドキュメントではない
- 「入力前に知っておくべき」情報にはラベルヘルプを、「知っておくと良い」詳細には標準説明を使用
- ラベルヘルプと標準フィールド説明は両方一緒に使用可能 - 相互に補完する目的を持つ
- モジュールはアクティブな管理テーマを自動検出し、適切なスタイルを適用
- デバッグモードでは、正常に配置されたメッセージにはチェックマーク（✅）が表示され、トラブルシューティング用にユースケース番号が表示される
Technical Details
Hooks 2
#label_help
フィールドラベルの下にヘルプテキストを表示するためにフォーム要素に追加できるカスタムForm APIプロパティ。これはラベルヘルプテキストをプログラム的に追加する方法です。
hook_form_alter() / hook_FORM_ID_alter()
標準のDrupal form alter hookを使用して、他のモジュールで定義された既存のフォームフィールドに#label_helpを追加できます。
Troubleshooting 3
settings.phpに$settings['label_help_debug'] = TRUE;を追加してデバッグモードを有効にします。フォームページをリロードすると、Label Helpの配置ロジックによって一致したフィールドウィジェットタイプとユースケースを識別するデバッグ出力が表示されます。ユースケースが検出されない場合は、警告メッセージが表示されます。
settings.phpに$settings['label_help_debug_dump'] = TRUE;を追加してForm API要素ダンプモードを有効にします。これはSymfonyのVariable Dumperを使用して、Form API要素配列のドリルダウン可能なダンプを提供します。注：これによりページのレンダリングが完了しなくなる場合がありますが、これは想定された動作です。
サポートされている管理テーマ（Seven、Claro、Gin）のいずれかを使用していることを確認してください。モジュールにはこれらのテーマ用の専用CSSが含まれています。カスタムテーマの場合、.description--label-helpまたは.form-item__description--label-helpクラスをターゲットにしたカスタムCSSの追加が必要な場合があります。