Better Field Descriptions
Allows users to add customizable, themeable descriptions to form fields across all entity types without requiring field management permissions.
better_field_descriptions
インストール
composer require 'drupal/better_field_descriptions:^2.0'
composer require 'drupal/better_field_descriptions:8.x-1.7'
概要
Better Field Descriptionsは、Drupalのフォームフィールドにカスタムでテーマ対応のヘルプテキストを追加するための強力なソリューションを提供します。編集にフィールド管理権限が必要な標準のフィールド説明とは異なり、このモジュールは役割を分離します。サイト管理者はどのフィールドにbetter descriptionsを適用するかを選択し、コンテンツマネージャーや編集者が説明テキストを自分で作成・管理できます。
このモジュールはすべてのEntityタイプ（Node、Taxonomy Term、Userなど）をサポートし、あらゆるフィールドタイプで動作します。説明はフィールドの上、フィールドの下、またはフィールドラベルと入力要素の間に配置できます。各説明には独自のラベルを設定するか、サイト全体のデフォルトラベルを使用できます。
説明はTwigテンプレートを通じてレンダリングされ、完全なテーマのカスタマイズが可能です。モジュールには2つの組み込みテンプレート（シンプルなテキスト表示と折りたたみ可能なfieldsetラッパー）が含まれています。開発者はカスタムテンプレートを作成でき、自動的に検出されて設定で利用可能になります。
Features
- あらゆるEntityタイプ（Node、Taxonomy Term、User、Mediaなど）の任意のフィールドにカスタム説明を追加
- 説明をフィールドの上、フィールドの下、またはタイトルと入力要素の間に配置
- 各説明にカスタムラベルを割り当てるか、グローバルなデフォルトラベルを使用
- Twigテンプレートによる完全にテーマ対応の出力。2つの組み込みオプション：プレーンテキストと折りたたみ可能なfieldset
- フィールド選択（管理者）と説明作成（コンテンツマネージャー）の権限を分離
- ファイルアップロード、テキストエリア、Entity参照など、すべてのフィールドタイプで動作
- タイトルフィールドなどの疑似フィールドも自動的に処理
- テンプレート自動検出：テーマフォルダに配置したカスタムテンプレートが自動的に利用可能に
- 説明テンプレートでの必須フィールドインジケーターのサポート
Use Cases
Client-Friendly Field Help Text
A web agency builds a Drupal site for a client. The client wants to customize field descriptions to match their editorial guidelines, but the agency doesn't want to give them access to field configuration. With Better Field Descriptions, the agency selects the fields on the Settings tab, then gives the client the 'Add Better Descriptions To Selected Fields' permission. The client can now write their own help text without risking accidental field configuration changes.
Contextual Help in Complex Content Types
A site has content types with many fields where content authors need guidance. Using the 'Between title and input' position option, administrators can place detailed instructions directly beneath each field label but above the input, making the help text more prominent than standard Drupal field descriptions which appear below the input.
Collapsible Help Documentation
For fields requiring extensive documentation (acceptable formats, guidelines, examples), use the fieldset template to wrap descriptions in a collapsible element. This keeps forms clean while making detailed help available on demand.
Consistent Labeling Across Forms
Set a default label like 'Guidelines' or 'Help' that applies to all descriptions, creating a consistent UI pattern across the site. Override with custom labels for specific fields when needed.
Moving Existing Descriptions
Sometimes the default description position (below the input) is not ideal. By enabling a field for better descriptions but leaving the description text empty, the module will use the original field description but allow you to reposition it above the field or between the label and input.
Custom Template for Branding
Create a custom template file (e.g., better-field-descriptions-branded.html.twig) in your theme's templates folder. The module auto-discovers it and makes it available in the template dropdown. Use this to style descriptions with your site's design system, icons, or specific markup requirements.
Tips
- Always enable entity types on the Entities tab first, then select fields on Settings, then add descriptions on Bundles - the tabs must be used in this order
- The 'Between title and input' position can cause duplicate labels with some field types - always review your forms after saving
- Leave the description field empty to reposition the original field description without changing its text
- Custom templates in your theme's templates folder are auto-discovered - name them better-field-descriptions-*.html.twig
- Users need both the module permission AND 'Use the administration pages and help' permission to access the configuration pages
- Template changes trigger a theme registry rebuild which may briefly impact site performance
- For file/image fields, the module automatically adjusts prefix/suffix positions to work correctly with the managed_file widget
Technical Details
Admin Pages 3
/admin/config/content/better_field_descriptions
The main settings page where administrators select which fields across all configured entity types and bundles should have better descriptions enabled. Fields are organized by entity type and bundle in collapsible sections. Checking a field here makes it available for description editing on the Bundles tab.
/admin/config/content/better_field_descriptions/bundles
The description editing page where users with the appropriate permission can write and configure the actual description text for each enabled field. This is where content managers add helpful guidance for content authors.
/admin/config/content/better_field_descriptions/entities
Configuration page to select which entity types should be available for better field descriptions. Only entity types enabled here will appear on the main Settings page for field selection.
権限 2
Hooks 3
hook_field_widget_form_alter
The module implements this hook to inject better descriptions into field widgets during form rendering. It checks if the current field has a better description configured, then adds the rendered description to the appropriate position in the form element.
hook_theme
Registers the better_field_descriptions theme hook with configurable template file and path. Allows custom templates to be discovered from the active theme.
hook_help
Provides help text for the module's help page at /admin/help/better_field_descriptions.