Block Class
テーマテンプレートを変更することなく、ユーザーインターフェースを通じてブロックにカスタムCSSクラス、HTML属性、IDを割り当てることができます。
block_class
インストール
composer require 'drupal/block_class:^4.0'
概要
Block Classは、DrupalのBlock標準設定インターフェースを通じて、任意のブロックにカスタムCSSクラス、HTML属性、IDを追加するための包括的なソリューションを提供します。これにより、ブロックのHTML出力を制御するためにテーマテンプレートの変更や技術的な知識が不要になります。
このモジュールはthird_party_settingsを使用してDrupalの設定システムにブロックスタイリング設定を保存するため、環境間での変更のエクスポートとデプロイが容易です。すべてのDrupal Core APIモジュールとシームレスに統合され、ブロック属性を適切にレンダリングする任意のテーマで動作します。
バージョン4.xでは、クラス用の複数テキストフィールド、オートコンプリート機能、全ブロックにわたるクラス管理のための一括操作、フィールド動作を制御するための包括的な設定など、高度な機能が提供されています。このモジュールは大文字/小文字の強制、特殊文字の処理、カスタムCSS識別子フィルタリングをサポートしています。
Features
- ブロック設定フォームから任意のブロックにカスタムCSSクラスを追加
- ブロックのHTML IDを上書きまたは削除（<none>を使用してIDを完全に削除）
- キー|値形式でブロックにカスタムHTML属性を追加（例：data-block-type|info）
- 以前使用したクラスと属性のオートコンプリート機能
- 追加/削除ボタン付きで1フィールドにつき1クラスを入力できる複数テキストフィールドモード
- 全ブロックにわたってクラスと属性の挿入、更新、大文字小文字変換、削除を行う一括操作
- 設定済みのすべてのクラスと属性を編集/削除リンク付きで表示するブロック一覧
- 定義済みのすべての値を表示するクラス一覧と属性一覧
- クラス、属性、IDフィールドの最大文字数を設定可能
- ブロックフォーム上のフィールド順序を制御する重み設定
- 大文字小文字の強制（大文字、小文字、または標準）
- カスタマイズ可能なHtml::cleanCssIdentifier設定による特殊文字フィルタリング
- 設定がブロック設定とともにエクスポートされ、デプロイが容易
Use Cases
レイアウトスタイリング用のCSSクラスを追加
テーマテンプレートを変更せずに、ターゲットを絞ったCSSスタイリングを可能にするために、'footer-left'、'sidebar-promo'、'hero-section'などのCSSクラスをブロックに追加します。ブロック設定に移動し、CSSクラスフィールドにクラスを入力（複数モードでは1行に1つ、テキストフィールドモードではスペース区切り）して保存します。クラスはブロックのラッパーdivに追加されます。
JavaScript機能用のdata属性を追加
JavaScriptインタラクション用にブロックにカスタムdata属性を追加します。モジュール設定で属性を有効にし、ブロック編集時に属性フィールドに'data-behavior|accordion'や'data-tracking|header-cta'などの属性を追加します。これらはブロックのHTMLでdata-behavior="accordion"としてレンダリングされます。
環境間でブロックIDを標準化
ID置換機能を使用して、Drupalが自動生成するブロックIDに関係なく一貫したブロックIDを設定します。IDフィールドにカスタムIDを入力します。'<none>'を使用すると、アクセシビリティやスタイリングのためにブロックからID属性を完全に削除できます。
リブランディング時にクラス名を一括更新
リブランディングで全ブロックのクラス名を更新する必要がある場合、一括操作ページを使用します。「クラスを更新」を選択し、現在のクラス名と新しいクラス名を入力すると、全ブロックでそのクラスが検索・置換されます。
CSSクラスの命名規則を強制
チームの一貫性のために小文字のみのクラス名を強制するようモジュールを設定します。設定でデフォルトの大文字小文字を「小文字」に設定し、特殊文字を無効にします。すべてのクラスは保存時に自動的に小文字に変換されます。
設定と一緒にブロックスタイリングをエクスポート
Block ClassはCSSクラス、属性、カスタムIDをthird_party_settingsに保存するため、すべてがブロック設定とともにエクスポートされます。Drupalの設定エクスポート/インポートを使用して、環境間でブロックスタイリングの変更をデプロイできます。
Tips
- 複数テキストフィールドモードを使用するとクラス管理がクリーンになります - タイプミスを防ぎ、個々のクラスの削除が容易になります
- オートコンプリート機能は以前使用したすべてのクラスを記憶し、ブロック間で一貫したスタイリングを素早く適用できます
- '<none>'をID値として使用すると、ブロックのID属性がHTML出力から完全に削除されます
- 特殊文字が有効でない限り、クラスはHtml::cleanCssIdentifierを使用して自動的にサニタイズされます
- 特定の命名規則がある場合は、詳細設定を使用して文字置換ルールを設定してください
- このモジュールはViewsブロック、カスタムブロック、コントリビュートモジュールのブロックを含むすべてのブロックタイプと統合されます
- 設定をバージョン管理にエクスポートして、ブロックスタイリングの変更を時間の経過とともに追跡できます
- サイト全体のスタイリング変更を実装する際に一括操作を使用して、共通のクラスをすべてのブロックに素早く適用できます
Technical Details
Admin Pages 6
/admin/config/content/block-class/settings
フィールドタイプ、最大文字数、重み、クラス・属性・ID置換の機能トグルなど、Block Classモジュールのグローバル設定を構成します。
/admin/config/content/block-class/list
Block Class設定（クラスまたは属性）を持つすべてのブロックを、編集または削除オプション付きで表示します。
/admin/config/content/block-class/bulk-operations
全ブロックにわたってクラスと属性の挿入、更新、大文字小文字変換、削除などの一括操作を実行します。
/admin/block-class/help
使用方法、設定オプション、管理ページへのリンクを含むBlock Classモジュールのヘルプ情報を表示します。
/admin/config/content/block-class/class-list
ブロック設定で使用されたすべてのCSSクラスを表示します。新しいブロックにクラスを追加する際の参照に便利です。
/admin/config/content/block-class/attribute-list
ブロック設定で使用されたすべての属性をインライン形式で表示します。
権限 1
Hooks 4
hook_block_presave
大文字小文字変換やオートコンプリート用のクラス/属性の保存を含む、保存前のBlock Class設定を処理します。
hook_form_block_form_alter
ブロック設定フォームにCSSクラス、属性、IDフィールドを追加します。
hook_preprocess_block
設定済みのCSSクラス、属性、IDをブロックのrender array変数に追加します。
hook_help
Block Classモジュールのヘルプページ用のヘルプテキストを提供します。
Troubleshooting 7
テーマのブロックテンプレートが属性変数を適切にレンダリングしていることを確認してください。block.html.twigに{{ attributes }}または同様の記述があることを確認します。クラスはプリプロセス中に$variables['attributes']['class']に追加されます。
モジュール設定で「オートコンプリートを有効化」がチェックされていることを確認してください。クラスはブロック保存時に保存されるため、オートコンプリートに表示されるには少なくとも1つのブロックをクラス付きで保存する必要があります。
デフォルトでは特殊文字は無効になっています。/admin/config/content/block-class/settingsに移動し、「特殊文字を有効化」をチェックして許可します。なお、有効なCSSクラス名には依然として制限があります。
デフォルトの大文字小文字設定が一括操作と競合する場合（例：小文字が強制されているときに大文字に変換しようとする）、操作はエラーを表示します。最初にデフォルトの大文字小文字設定を変更するか、「大文字と小文字」に設定して両方を許可してください。
クラスフィールドの数は設定の「ブロックあたりのクラス数」で制御されます。より多くのフィールドが必要な場合はこの値を増やしてください。ブロックにすでにこれ以上のクラスがある場合、モジュールは自動的にこの制限を超えて拡張します。
/admin/config/content/block-class/settingsのモジュール設定で「属性を有効化」がチェックされていることを確認してください。
これらは予約されています。CSSクラスには専用のクラスフィールドを使用してください。IDについては、属性の代わりにID置換機能を使用してください。
Security Notes 4
- 「administer block classes」権限は制限付きとしてマークされており、信頼できるロールにのみ付与する必要があります
- HTML属性値はXSS攻撃を防ぐためにHtml::escape()を使用してサニタイズされます
- CSS識別子は、特殊文字が明示的に有効化されていない限り、Html::cleanCssIdentifier()で処理されます
- 競合を防ぐため、モジュールは'id'と'class'を属性キーとして使用できないようバリデーションを行います