Style Options
CSSクラス、背景色、背景画像をレイアウト、Paragraphs、その他のDrupalコンポーネントに適用できる、拡張可能なプラグインシステムを備えた設定可能なスタイル管理API。
style_options
インストール
composer require 'drupal/style_options:^1.1'
概要
Style Optionsモジュールは、Drupalエコシステム全体で再利用可能なスタイルオプションを管理するための包括的なAPIを提供します。サイトビルダーや開発者がカスタムコードを記述することなく、CSSクラス、背景色、背景画像などの設定可能なスタイルをさまざまなDrupalコンポーネントに適用できるようになります。
このモジュールはYAMLベースの設定システムを使用しており、モジュールやテーマでスタイルオプションを定義できます。これらのオプションは、Layout APIのレイアウトやParagraphタイプなど、さまざまなコンテキストに適用できます。拡張可能なプラグインアーキテクチャにより、開発者は特殊なスタイリングニーズに対応するカスタムスタイルオプションプラグインを作成できます。
Style OptionsにはLayout APIおよびParagraphsモジュールとの組み込み統合が含まれており、シームレスな編集体験を提供します。編集者はカラーピッカーやファイルアップロードなどの機能を備えた直感的なフォームを通じてスタイルを設定できます。モジュールはレンダリングされたコンポーネントに自動的に添付される動的CSSを生成します。
Features
- CSSクラスプラグイン: 事前定義されたオプション（セレクト/ラジオボタン）または自由入力テキストをサポートし、オプションで複数選択機能を備えたカスタムCSSクラスをコンポーネントに適用
- 背景色プラグイン: 設定可能なパレット、アルファ透明度サポート、CSS生成方法（埋め込みスタイルタグまたはインラインスタイル）の選択を備えた統合カラーピッカー（Spectrum.js）を使用して背景色を追加
- 背景画像プラグイン: 管理されたファイル処理、設定可能なアップロード場所、ファイルサイズ制限、寸法検証、自動カバースタイルCSS生成を備えた背景画像のアップロードと適用
- Propertyプラグイン: 任意のプロパティ値をコンポーネントに適用するための汎用プラグイン、カスタム実装に便利
- Layout API統合: レイアウト全体と個別のリージョンにスタイルオプションを有効にするタブ付きインターフェースを備えた組み込みレイアウトプラグインクラス（StyleOptionLayoutPlugin）
- Paragraphs Behavior統合: バンドルごとの設定を持つParagraphタイプ編集フォームにスタイルオプションを追加するParagraphsBehaviorプラグイン
- YAMLベースの設定: デフォルト、オーバーライド、選択的無効化をサポートする[module].style_options.ymlまたは[theme].style_options.ymlファイルでスタイルオプションを定義
- コンテキスト対応設定: デフォルトからの継承を伴い、特定のレイアウト、Paragraphバンドル、その他のコンテキストに表示されるオプションを設定
- 拡張可能なプラグインシステム: StyleOptionPluginBaseを拡張しStyleOptionPluginInterfaceを実装することでカスタムスタイルオプションプラグインを作成
- 動的CSS生成: スタイルは競合のないスタイリングのための一意のクラス名を持つ埋め込み<style>タグとしてページヘッドにレンダリング
- AJAXサポート: AJAXコンテキストでスタイルがサフィックスとして適切に添付されるAJAXレンダリングコンテンツの完全サポート
- 移行ツール: 自動データ変換を備えたOption Pluginモジュールからの移行用組み込み移行ユーティリティ
Use Cases
レイアウトへのカスタムCSSクラスの追加
サイトビルダーは、テーマのstyle_options.ymlファイルで事前定義されたCSSクラスのセット（例：'container-wide'、'container-narrow'、'highlighted-section'）を定義できます。編集者はレイアウトを設定する際にこれらのクラスを選択でき、CSSを理解する必要なく一貫したスタイリングを適用できます。
コンテンツセクションの設定可能な背景色
設定でブランド承認済みのカラーパレットを定義します。コンテンツ編集者は、カラーピッカーを使用して「コールトゥアクション」や「注目コンテンツ」などのParagraphタイプに背景色を適用でき、創造的な柔軟性を許可しながらブランドの一貫性を維持できます。
背景画像付きヒーローセクション
ヒーローParagraphタイプでbackground_imageオプションを有効にします。編集者はカバープロパティで自動的にスタイリングされる背景画像をアップロードでき、開発者の介入なしに視覚的にインパクトのあるページセクションを作成できます。
コンポーネントタイプごとの異なるスタイリングオプション
コンテキストシステムを使用して、異なるコンポーネントに異なるスタイルオプションを提供します。例えば、レイアウトセクションには幅クラス、Paragraphsには背景色、特定のParagraphバンドルにはハイライトスタイルを提供します。
テーマ固有のブランドスタイリング
カスタムテーマのstyle_options.ymlですべてのスタイルオプションを定義します。これにより、ブランド固有のスタイリング設定がテーマと一緒に保持され、単一の設定ファイルを変更することでリブランディング時に簡単に更新できます。
カスタムプラグインによる拡張
開発者は、グラデーション背景、ボックスシャドウ、アニメーショントリガーなどの特殊なニーズに対応するカスタムスタイルオプションプラグインを作成できます。拡張可能なプラグインシステムにより、任意のスタイルプロパティを設定可能にできます。
Tips
- コンテキストの'_defaults'キーを使用して、すべてのレイアウトまたはParagraphタイプのベースラインオプションを設定し、個別のコンポーネントに対して特定のオプションをオーバーライドまたは無効化する
- コンテキスト定義の'_disable'キーを使用すると、すべてを再定義することなく、デフォルトから継承されたオプションを選択的に削除できます
- style_options.ymlはモジュールではなくカスタムテーマに保存して、ブランド固有のスタイリング設定をテーマアセットと一緒に保持する
- css_classプラグインの事前定義オプションを作成する際は、ユーザーがスタイリングを削除できるように空のクラス値を持つ'None'オプションを含める
- オプションの'description'設定を使用して、各スタイリングオプションをいつどのように使用するかについて編集者にガイダンスを提供する
- 背景色には、サイト全体の一貫性を確保するためにブランドカラーに一致するパレットを設定する
- カスタムプラグインでモジュールを拡張する際は、一貫したCSS生成動作のためにStyleOptionStyleTraitを実装する
- background_colorとbackground_imageプラグインの'method'設定はデフォルトでスタイルタグを生成する'css'です。スタイルタグが問題を引き起こす場合にのみ'inline'を使用してください
Technical Details
Admin Pages 1
/admin/config/style-options/migrate
Option Pluginモジュールからデータを移行するための移行ユーティリティ。このページでは、option_plugin形式からstyle_options形式にParagraph Behavior設定を変換するシンプルなワンクリック移行プロセスを提供します。
Hooks 2
hook_style_options_alter
モジュールがスタイルオプションプラグイン定義を変更できるようにします。プラグイン定義が収集されているときにプラグインマネージャーによって呼び出されます。
hook_theme
background_colorとbackground_imageスタイルテンプレートのテーマフックを登録するためにモジュールによって実装されます。
Troubleshooting 6
レイアウト定義がクラスとしてStyleOptionLayoutPluginを使用しているか、それを拡張していることを確認してください。style_options.ymlファイルが適切にフォーマットされ、モジュール/テーマのルートディレクトリに配置されていることを確認してください。レイアウトコンテキストが'contexts.layout'セクションで設定されていることを確認してください。
Paragraphタイプの設定で「Style Options」Behaviorを有効にしてください。Paragraphバンドルがstyle_options.ymlファイルの'contexts.paragraphs'セクションで設定されていることを確認してください。
Spectrum.jsライブラリを/libraries/spectrum/spectrum.jsおよび/libraries/spectrum/spectrum.cssにインストールしてください。インストール後にDrupalキャッシュをクリアしてください。
アップロードディレクトリが存在し、書き込み可能であることを確認してください。ファイルシステムの権限を確認してください。オプション定義でファイルスキーム（public/private）が正しく設定されていることを確認してください。
設定変更後にすべてのキャッシュをクリアしてください。Paragraph/レイアウトのBehavior設定を確認してオプション値が保存されていることを確認してください。buildメソッドがレンダー配列にスタイルを正しく追加していることを確認してください。
Paragraphタイプにはoption_pluginとstyle_optionsの両方のBehaviorが利用可能であることを確認してください。移行はoption_plugin Behaviorが有効になっているParagraphのみを処理します。Drupalログでエラーを確認してください。
Security Notes 4
- background_imageプラグインを通じたファイルアップロードは、ファイル拡張子（gif、png、jpg、jpegのみ）、ファイルサイズ、画像寸法が検証されます
- アップロードされたファイルは自動クリーンアップを防ぐために永続的としてマークされますが、Drupalのファイルシステムを通じて適切に管理されます
- CSS値は自動エスケープを提供するTwigテンプレートを通じてレンダリングされますが、カスタムプラグインはユーザー入力の適切なサニタイズを確保する必要があります
- 移行フォームは不正なデータ変更を防ぐために'administer site configuration'権限を必要とします