Layout Options
YAMLファイルとカスタムLayoutOptionプラグインを使用して、レイアウトに設定オプションを簡単に追加できるLayoutプラグインを提供します。
layout_options
インストール
composer require 'drupal/layout_options:8.x-1.7'
composer require 'drupal/layout_options:8.x-1.5'
概要
Layout Optionsは、レイアウトにスタイリングや設定オプションを追加する柔軟な方法を提供することで、DrupalのLayoutシステムを拡張する強力なモジュールです。サイトビルダーはPHPコードを書く代わりに、YAMLファイルを通じてレイアウトオプションを定義でき、レイアウトやリージョンにCSSクラス、ID属性、その他のカスタマイズを簡単に追加できます。
このモジュールは、デフォルトのレイアウトクラスを置き換えるカスタムLayoutプラグインクラス（LayoutOptions）を提供することで動作します。このプラグインはモジュールやテーマで検出された*.layout_options.ymlファイルから設定を読み取り、Layout BuilderやEntity Reference Layoutsでレイアウトを設定するための適切なフォーム要素を生成します。設定された値はレンダリング時にHTML属性として適用されます。
このモジュールはテーマの継承をサポートしており、ベーステーマで定義されたオプションをサブテーマで拡張またはオーバーライドできます。オプションはすべてのレイアウトにグローバルに適用することも、IDで特定のレイアウトに適用することも、Entity Reference Layoutsと併用する場合は特定のフィールドコンテキストに適用することもできます。
Features
- PHPコードを書かずにYAMLファイルでレイアウト設定オプションを定義
- layout_options_idプラグインを使用してレイアウトとレイアウトリージョンにID属性を追加
- layout_options_class_stringプラグインを使用してテキスト入力でCSSクラスを追加
- 単一選択または複数選択に対応したlayout_options_class_selectプラグインを使用してセレクトドロップダウンでCSSクラスを追加
- layout_options_class_checkboxesプラグインを使用してチェックボックスでCSSクラスを追加
- layout_options_class_radiosプラグインを使用してラジオボタンでCSSクラスを追加
- メインレイアウトのみ、リージョンのみ、または両方にオプションを適用するよう設定可能
- allowed_regions設定を使用して特定のリージョンにオプションを制限
- すべてのレイアウトにグローバルに適用、または特定のレイアウトIDをターゲットに設定
- Entity Reference Layoutsと併用時のフィールド固有オプションをサポート
- サブテーマがベーステーマのオプションを拡張またはオーバーライドできるテーマ継承をサポート
- 有効なクラス名とIDを保証するための自動CSS識別子バリデーション
- フォーム要素の順序を制御するためのウェイトベースのソート
- カスタムレイアウトオプションタイプを作成するための拡張可能なプラグインシステム
Use Cases
レイアウトへのBootstrap背景色の追加
コンテンツ編集者がレイアウトとリージョンにBootstrapの背景色クラス（bg-primary、bg-secondaryなど）を選択できるYAML定義を作成します。オプションをセレクトドロップダウンとして定義し、すべてのレイアウトに表示されるようにグローバルに適用します。
テーマ固有のデザインクラス
テーマに固有のCSSクラスのセット（例：layout--narrow、layout--wide、layout--centered）をチェックボックスとして定義します。サイトビルダーはコードを編集せずにこれらのデザインバリエーションを素早く適用できます。
アンカーリンク用のカスタムIDの追加
layout_options_idプラグインを使用して、コンテンツ編集者がレイアウトとリージョンにカスタムHTML IDを追加できるようにします。これにより、ページ内ナビゲーション用のアンカーリンクを作成できます。
Entity Reference Layoutsのフィールド固有オプション
Entity Reference Layoutsモジュールを使用する場合、特定のフィールドにのみ表示されるオプションを定義します。例えば、hero_sectionフィールドにはcontent_blocksフィールドとは異なるスタイリングオプションを持たせることができます。
レイアウト固有のカスタマイズ
特定のレイアウトにのみ適用されるオプションを定義します。例えば、2カラムレイアウトにはカラム比率を制御するオプションがあり、1カラムレイアウトには異なるマージンオプションがあるようにできます。
サブテーマでのオプション拡張
コアのレイアウトオプションを持つベーステーマを作成し、サブテーマでこれらを拡張してクライアント固有のスタイリングオプションを追加します。サブテーマは新しいオプションを追加したり、既存のオプションをオーバーライドしたりできます。
リージョン専用のスペーシング制御
メインレイアウトラッパーではなくリージョンにのみ適用されるパディングとマージンクラスを定義します。allowed_regionsを使用して、サイドバーなどの特定のリージョンに特定のオプションをさらに制限します。
Tips
- レイアウトオプションをテーマに追加するのではなく、サイト用のカスタムモジュールを作成してください。これにより、テーマが変更されてもオプションが利用可能なままになります
- 保守性を高めるため、目的を説明する意味のあるオプションID（例：layout_bg_color、layout_spacing）を使用してください
- 関連する設定を設定フォームでグループ化するため、オプションに適切なウェイトを設定してください
- 一般的に使用されるオプションにはglobalセクションを使用し、レイアウト固有のセクションは必要な場合にのみ使用してください
- カスタムLayoutOptionプラグインを作成する際は、組み込みのバリデーションとフォーム構築ユーティリティを活用するためにOptionBaseクラスを拡張してください
- 異なるデザインシステム間でCSSクラスが期待通りに動作することを確認するため、異なるテーマでレイアウトオプションをテストしてください
- 特定のリージョンに無関係なオプションが表示されないようにするため、allowed_regions設定を使用してください
- サブモジュールLayout Options UIは、デフォルトのLayoutDefaultクラスを使用するレイアウトのみを表示します。カスタムレイアウトプラグインはオーバーライドリストに表示されません
Technical Details
Admin Pages 1
/admin/config/system/layout_options/config
このページでは、管理者がデフォルトのLayoutクラスの代わりにLayout Optionsクラスを使用するようにオーバーライドすべきレイアウトを選択できます。これにより、元々設定オプションをサポートするように設計されていないレイアウトに設定オプションを追加できます。
Hooks 2
hook_layout_option_info_alter
モジュールが検出後にレイアウトオプションプラグイン定義を変更できるようにします。既存のオプションタイプを変更したり、機能を追加/削除したりするために使用できます。
hook_layout_alter
Layout Options UIサブモジュールがレイアウトクラスをオーバーライドするために使用します。プログラム的にレイアウトをLayoutOptionsクラスを使用するように設定するために使用できます。
Troubleshooting 6
レイアウトがLayoutOptionsクラスを使用していることを確認してください。class: '\Drupal\layout_options\Plugin\Layout\LayoutOptions'を持つカスタムレイアウトを定義するか、Layout Options UIを有効にしてオーバーライドするレイアウトを選択してください。また、YAMLファイルが正しく命名され、モジュール/テーマのルートディレクトリに配置されていることを確認してください。
*.layout_options.ymlファイルを変更した後、すべてのDrupalキャッシュをクリア（drush cr）してください。YAML検出はファイルの内容をキャッシュします。
テーマがデフォルトテーマとして設定されていることを確認してください。テーマ階層ではデフォルトテーマとそのベーステーマのみが考慮されます。インストールされているが有効でない他のテーマはフィルタリングされます。
YAMLのプラグインIDが利用可能なLayoutOptionプラグイン（layout_options_id、layout_options_class_string、layout_options_class_select、layout_options_class_checkboxes、layout_options_class_radios）と正確に一致していることを確認してください。プラグインIDは大文字と小文字を区別します。
レイアウトテンプレートがattributes変数を使用していることを確認してください。クラスが有効なCSS識別子であることを確認してください。モジュールは無効な識別子を検証して拒否します。
CSS識別子は数字で始めることができず、文字、数字、ハイフン、アンダースコアのみを含めることができます。モジュールはバリデーションにHtml::cleanCssIdentifierを使用しています。
Security Notes 3
- すべてのユーザー入力値は、保存またはレンダリング前にHtml::escape()を使用してサニタイズされます
- CSS識別子は無効または悪意のあるクラス名を防ぐためにHtml::cleanCssIdentifier()を使用して検証されます
- Layout Options UI管理ページには「administer site configuration」権限が必要です