drupal-frontend

Drupal フロントエンド開発

概要

Drupal 8、9、10、11 以降に対応した、エキスパートレベルの Drupal フロントエンド開発機能を利用できます。テーマ開発、Twig テンプレート、プリプロセス、レスポンシブデザイン、アセット管理について、包括的なガイダンスを提供します。

このスキルを使う場面

次の作業でこのスキルを呼び出します：

• テーマ開発：Drupal テーマの作成やカスタマイズ
• Twig テンプレート：.twig テンプレートファイルの作成や変更
• プリプロセス：テンプレート用プリプロセス関数の実装
• テンプレート候補：カスタムのテンプレート命名パターンの追加
• CSS/JS ライブラリ：テーマのアセットと依存関係の管理
• レスポンシブデザイン：ブレークポイントやモバイルファーストデザインの実装
• レンダリングシステム：Drupal のレンダリングパイプラインの理解
• テーマフック：テーマ関連フックや変更処理の実装

主な機能

1. テーマ開発

適切な構成で、標準に準拠した Drupal テーマを構築します。

クイックスタートのワークフロー：

1. assets/theme-template/ のテーマテンプレートを出発点として使用します
2. THEMENAME をテーマのマシン名に置き換えます
3. THEMELABEL を人が読みやすい名前に置き換えます
4. テンプレート、CSS、JS、ライブラリをカスタマイズします
5. テーマを有効にし、外観 UI で設定します

テーマの構成要素：

• .info.yml - テーマのメタデータと設定
• .libraries.yml - CSS/JS ライブラリの定義
• .theme - プリプロセス関数とテーマロジック
• .breakpoints.yml - レスポンシブデザインのブレークポイント
• templates/ - Twig テンプレートファイル
• css/ - スタイルシート
• js/ - JavaScript ファイル

参考ドキュメント：

• references/theming.md - 例を含むテーマ設定の完全ガイド

2. Twig テンプレートシステム

Twig の構文と Drupal 固有の拡張機能を習得します。

Twig の基本：

• {{ variable }} - 変数を出力
• {% if/for/set %} - 制御構造とロジック
• {# comment #} - コメントとドキュメント
• {{ var|filter }} - 変数にフィルターを適用
• {% extends %} - テンプレートの継承
• {% block %} - オーバーライド可能なセクションを定義

Drupal 固有の Twig：

• {{ 'Text'|t }} - 文字列を翻訳
• {{ attach_library('theme/library') }} - CSS/JS を読み込み
• {{ url('route.name') }} - URL を生成
• {{ path('route.name') }} - パスを生成
• {{ file_url('public://image.jpg') }} - ファイル URL
• {{ content|without('field') }} - フィールドを除外

一般的なテンプレート：

• page.html.twig - ページレイアウトの構造
• node.html.twig - ノードの表示
• block.html.twig - ブロックのレンダリング
• field.html.twig - フィールドの出力
• views-view.html.twig - Views の出力

3. プリプロセス関数

レンダリング前にテンプレート変数を変更します。

プリプロセスのパターン：

function THEMENAME_preprocess_HOOK(&$variables) {
  // Add or modify variables
  // Access entities, services, configuration
  // Prepare data for templates
}

一般的なプリプロセスフック：

• hook_preprocess_page() - ページレベルの変数
• hook_preprocess_node() - ノード固有のデータ
• hook_preprocess_block() - ブロックの変更
• hook_preprocess_field() - フィールドの変更
• hook_preprocess_html() - HTML ドキュメント

ベストプラクティス：

• ロジックはプリプロセスに、マークアップはテンプレートに記述します
• 可能な場合は依存性注入を使用します
• キャッシュコンテキストやタグを適切に設定します
• 複雑なプリプロセス処理にはドキュメントを付けます

4. テンプレート候補

コンテキストに応じた特定のテンプレートを用意します。

候補のパターン：

page--front.html.twig                  # Homepage
page--node--{nid}.html.twig            # Specific node
page--node--{type}.html.twig           # Content type
node--{type}--{viewmode}.html.twig     # Type + view mode
block--{plugin-id}.html.twig           # Specific block
field--{entity}--{field}.html.twig     # Specific field

候補の追加：

function THEMENAME_theme_suggestions_HOOK_alter(array &$suggestions, array $variables) {
  // Add custom suggestions
  $suggestions[] = 'custom__suggestion';
}

5. CSS と JavaScript の管理

テーマのアセットを効率よく整理して読み込みます。

ライブラリ定義：

# THEMENAME.libraries.yml
global-styling:
  version: 1.0
  css:
    base:
      css/base/reset.css: {}
    theme:
      css/theme/styles.css: {}
  js:
    js/custom.js: {}
  dependencies:
    - core/drupal

ライブラリの読み込み：

• グローバル：.info.yml で定義します
• 条件付き：テンプレートで attach_library() を使用します
• プリプロセス：プリプロセス関数でアタッチします

ベストプラクティス：

• CSS をレイヤー（ベース、レイアウト、コンポーネント、テーマ）に分けます
• 本番環境では CSS の集約を使用します
• JavaScript の依存関係を最小限にします
• Drupal のアセットライブラリシステムを活用します

6. レスポンシブデザイン

モバイルファーストでアクセシブルなデザインを実装します。

ブレークポイントの定義:

# THEMENAME.breakpoints.yml
THEMENAME.mobile:
  label: Mobile
  mediaQuery: 'screen and (min-width: 0px)'
  weight: 0

THEMENAME.tablet:
  label: Tablet
  mediaQuery: 'screen and (min-width: 768px)'
  weight: 1

THEMENAME.desktop:
  label: Desktop
  mediaQuery: 'screen and (min-width: 1024px)'
  weight: 2

モバイルファーストのアプローチ:

1. まず最も小さい画面向けにデザインする
2. より大きなビューポート向けに拡張する
3. レスポンシブ画像を使用する
4. さまざまなデバイスでテストする
5. アクセシビリティ基準（WCAG）に従う

開発ワークフロー

新しいテーマの作成

1. テーマをスキャフォールドする:

   cp -r assets/theme-template/ /path/to/drupal/themes/custom/mytheme/
   cd /path/to/drupal/themes/custom/mytheme/
   
   # Rename files
   mv THEMENAME.info.yml mytheme.info.yml
   mv THEMENAME.libraries.yml mytheme.libraries.yml
   mv THEMENAME.theme mytheme.theme
   

2. テーマ設定を更新する:

   • mytheme.info.yml を編集する - 名前、リージョン、ベーステーマを設定します
   • mytheme.libraries.yml を編集する - CSS/JS ライブラリを定義します
   • THEMENAME をマシン名に置き換えます
   • THEMELABEL をラベルに置き換えます

3. テーマを有効化する:

   ddev drush cr
   # Enable via UI at /admin/appearance or:
   ddev drush config:set system.theme default mytheme -y
   

4. Twig デバッグを有効化する:

   • sites/default/default.services.yml を sites/default/services.yml にコピーします
   • twig.config.debug: true を設定します
   • twig.config.auto_reload: true を設定します
   • twig.config.cache: false を設定します
   • ddev drush cr を実行します

5. 開発と反復:

   • templates/ 内のテンプレートを変更します
   • css/ 内の CSS を更新します
   • 頻繁にキャッシュをクリアします: ddev drush cr
   • ブラウザコンソールでエラーを確認します

標準的な開発ワークフロー

1. 開発設定を有効化する（Twig デバッグ、CSS/JS 集約の無効化）
2. Twig デバッグからの候補を基にテンプレートを作成・変更する
3. 複雑なデータ操作のために .theme ファイルで前処理を実装する
4. ライブラリシステムを通じて CSS/JS を追加する
5. さまざまなブラウザとデバイスでテストする
6. 変更後にキャッシュをクリアする: ddev drush cr

テンプレート名の見つけ方

Twig デバッグを有効にした状態で、HTML ソースを検査します:

x は現在有効なテンプレートを示します。それ以外は作成できる候補です。

一般的なパターン

前処理でのカスタム変数の追加

function mytheme_preprocess_page(&$variables) {
  // Add site slogan
  $variables['site_slogan'] = \Drupal::config('system.site')->get('slogan');

  // Add current user
  $variables['is_logged_in'] = \Drupal::currentUser()->isAuthenticated();

  // Add custom class
  $variables['attributes']['class'][] = 'custom-page-class';
}

テンプレートの継承

{# templates/page--article.html.twig #}
{% extends "page.html.twig" %}

{% block content %}
  <div class="article-wrapper">
    {{ parent() }}
  </div>
{% endblock %}

条件付きライブラリの読み込み

function mytheme_preprocess_node(&$variables) {
  if ($variables['node']->bundle() == 'article') {
    $variables['#attached']['library'][] = 'mytheme/article-styles';
  }
}

Twig でのフィールド値へのアクセス

{# Get field value #}
{{ node.field_custom.value }}

{# Check if field has value #}
{% if node.field_image|render %}
  {{ content.field_image }}
{% endif %}

{# Loop through multi-value field #}
{% for item in node.field_tags %}
  {{ item.entity.label }}
{% endfor %}

ベストプラクティス

テーマ開発

1. ベーステーマ: 適切なベースを選択する（Olivero、Claro、またはなし）
2. 構造: CSS を論理的に整理する（ベース、レイアウト、コンポーネント、テーマ）
3. 命名: BEM または同様の CSS 手法を使用する
4. コメント: 複雑な Twig ロジックと前処理を文書化する
5. パフォーマンス: 画像を最適化し、CSS/JS を最小化し、可能な場合は遅延読み込みする

Twig テンプレート

1. ロジック: 複雑なロジックはテンプレートではなく前処理に保つ
2. フィルター: 適切なフィルターを使用する（|t、|clean_class、|safe_join）
3. 空白: {% spaceless %} を使用して出力を制御する
4. デバッグ: Twig デバッグは開発中のみ有効にする
5. 候補: 必要な場合にのみ特定のテンプレートを使用する

前処理

1. サービス: テーマのサービスサブスクライバーで依存性注入を使用する
2. キャッシュ: 適切なキャッシュコンテキストとタグを追加する
3. パフォーマンス: 頻繁に呼び出されるプリプロセッサで重い処理を避ける
4. 整理: 関連する前処理を論理的にグループ化する

CSS と JavaScript

1. ライブラリ: 関連するアセットを論理的なライブラリにグループ化する
2. 依存関係: すべてのライブラリ依存関係を宣言する
3. 読み込み: 必要な場合にのみグローバルに読み込む
4. 集約: パフォーマンスのために本番環境で有効にする

アクセシビリティ

1. セマンティック HTML: 適切な要素を使用する（header、nav、main など）
2. ARIA: 必要に応じてラベルとロールを追加する
3. キーボード: キーボードナビゲーションが機能することを確認する
4. コントラスト: WCAG の色コントラスト要件を満たす
5. 代替テキスト: すべての画像に提供する

レスポンシブデザイン

1. モバイルファースト: 小さい画面向けにデザインし、大きい画面向けに拡張する
2. ブレークポイント: 論理的なブレークポイントを定義する
3. 画像: レスポンシブ画像スタイルを使用する
4. テスト: さまざまなデバイスと画面サイズでテストする
5. パフォーマンス: モバイルネットワーク向けに最適化する

トラブルシューティング

テンプレートの変更が表示されない

• キャッシュをクリアする: ddev drush cr
• ファイルの場所と命名を確認する
• 有効なテンプレートについて Twig デバッグを確認する
• ライブラリが適切に定義されていることを確認する

CSS/JS が読み込まれない

• .libraries.yml のライブラリ定義を確認します
• ファイルパスが正しいことを確認します
• ライブラリが（グローバルまたは条件付きで）アタッチされていることを確認します
• キャッシュをクリアし、ブラウザーのコンソールを確認します

テンプレートで変数を使用できない

• プリプロセス関数の命名を確認します
• 変数が正しく設定されていることを確認します
• Twig のデバッグ機能を使用します：{{ dump() }}
• プリプロセスの変更後にキャッシュをクリアします

Twig のデバッグが機能しない

• sites/default/services.yml が存在することを確認します
• twig.config.debug: true が設定されていることを確認します
• キャッシュをクリアします：ddev drush cr
• ファイルのアクセス権を確認します

リソース

リファレンスドキュメント

• references/theming.md - 包括的なテーマ設定ガイド
  • Twig の構文とフィルター
  • テンプレート候補
  • プリプロセスのパターン
  • ライブラリ管理
  • レスポンシブデザイン
  • ベストプラクティス

アセットテンプレート

• assets/theme-template/ - 完全なテーマのひな形
  • リージョンと設定を含む .info.yml
  • CSS/JS の例を含む .libraries.yml
  • プリプロセスの例を含む .theme
  • ページテンプレート
  • CSS と JS のスターターファイル

リファレンスの検索

# Find specific Twig filter
grep -r "clean_class" references/

# Find preprocessing examples
grep -r "preprocess_node" references/

# Find library patterns
grep -r "libraries.yml" references/

バージョン互換性

Drupal 8、9、10、11 の比較

• Twig の構文：すべてのバージョンで一貫しています
• ベーステーマ：一部のレガシーテーマは 10 以降で削除されています
• ライブラリ：すべてのバージョンで同じ構造です
• jQuery：Drupal 9 以降では jQuery はデフォルトで読み込まれません
• Claro：9 以降の標準管理テーマです
• Olivero：10 以降の標準フロントエンドテーマです

移行に関する注意事項

• アップグレード時は、非推奨のベーステーマを確認します
• jQuery の依存関係を確認します
• 現行の Twig バージョンでテストします
• 削除されたコアテンプレートがないか確認します

関連項目

• drupal-backend - モジュール開発、フック、API
• drupal-tooling - DDEV と Drush の開発ツール
• Drupal テーマ設定ガイド - 公式ドキュメント
• Twig ドキュメント - Twig 構文のリファレンス