Drupal:Colorbox を GLightbox に置き換える

1 はじめに

Lightbox プラグインは、10 年以上にわたって Drupal ベースのウェブサイトの定番でした。現在のページから離れることなく、オーバーレイで画像・動画・その他のメディアを表示できるようにするもので、これはモダンでメディアの多いサイトで訪問者が期待するパターンです。

Colorbox は歴史的に、Drupal エコシステムで定番のソリューションでした。コントリビュートモジュール colorbox は Drupal の画像フィールドフォーマッターと密に連携し、成熟した API を持ち、コミュニティに広く知られています。しかし、ウェブの進化とともに Colorbox はその古さを見せています。jQuery に依存し、より重いペイロードを配信し、現代のアクセシビリティの期待に後れをとっています。

そこで登場するのが GLightbox です。純粋な vanilla JavaScript の lightbox ライブラリ(依存関係ゼロ)で、洗練された UI、堅牢なアクセシビリティサポート、そして軽量なフットプリントを備えています。対応する Drupal モジュールは、かつて Colorbox が扱っていたのと同じ画像フィールドやメディアエンティティときれいに統合します。

この記事では、移行の全体を案内します。現在の Colorbox 構成の監査から、GLightbox のインストール、フィールドフォーマッターの再マッピング、古いモジュールの安全な削除、そしてテーマ向けの新しい体験の微調整まで。

2 Colorbox 対 GLightbox:なぜ移行するのか?

2.1 Colorbox の限界

Colorbox は、ウェブの別の時代に作られました。そのアーキテクチャは、モダンな Drupal 開発ではもはや成り立たない前提を反映しています。

• jQuery への依存。 Colorbox は jQuery プラグインであり、それなしでは動作できません。Drupal コアは、jQuery への依存を段階的に減らしてきており、パフォーマンスを重視する多くのテーマは jQuery を遅延読み込みするか、まったく使いません。jQuery への強い依存は、その目標に反します。
• 古びた UI とアニメーション。 Colorbox の標準スタイルは、2024〜2026 年のデザイン基準に比べて古く感じられます。最低限モダンな見た目に到達するだけでも、CSS の大幅なカスタマイズがしばしば必要になります。
• アクセシビリティのギャップ。 Colorbox は長年いくつかのアクセシビリティパッチを受けてきましたが、WCAG 2.1 AA を主目的として設計されてはいませんでした。フォーカストラップ、ARIA ロール、スクリーンリーダーへのアナウンスには、多大な追加作業が必要になり得ます。
• 保守のペース。 アップストリームの jQuery Colorbox ライブラリは更新頻度が低いです。長く続く Drupal プロジェクトにとって、ゆっくりとしか保守されない依存関係に賭けることはリスクをもたらします。

2.2 GLightbox の利点

GLightbox は、上記の各痛点に直接対処します。

• 依存関係ゼロ。 純粋な ES6+ JavaScript で、jQuery は不要です。
• モダンな UX。 なめらかな CSS トランジション、スワイプジェスチャー、キーボードナビゲーション、そして現代のデザインとよく統合するクリーンな標準テーマ。
• 一級のアクセシビリティ。 フォーカスは lightbox 内にトラップされ、キーボードの矢印キーによるナビゲーションが標準で機能し、適切な ARIA の role="dialog" セマンティクスが自動的に適用されます。
• 軽量。 minify + gzip のバンドルは 15 KB 未満で、典型的な Colorbox 構成の約 3 分の 1 の軽さです。
• ギャラリーのグループ化。 追加プラグインを必要とせず、data-gallery 属性を使ったグループ化ギャラリーをネイティブにサポートします。
• 活発な開発。 GitHub 上の GLightbox プロジェクトは、定期的なリリースとバグ修正が行われています。

3 Drupal エコシステムの概観

Drupal コアは、jQuery のフットプリントを減らし、vanilla JS と最新のブラウザ API へ向かう複数年の旅を続けてきました。これは、Drupal 10 以降での多くの jQuery ベースのビヘイビアの非推奨化や、テーマがより軽量な JavaScript 戦略を採用する動きに反映されています。

コントリビュート側では、Colorbox と GLightbox の両方が Drupal.org に専用の Drupal モジュールを持っています。

• colorbox — 画像フィールドフォーマッター、Views、メディアシステムに深く統合された古典的な選択肢。今なお広くインストールされていますが、更新は少なくなっています。
• glightbox — GLightbox JS ライブラリをラップする、より新しいコントリビュートモジュール。Image と Media のフィールドフォーマッター、Views のサポート、そして一般的な GLightbox オプションの設定フォームを提供します。

4 移行の準備

4.1 現在の Colorbox 利用状況の監査

いかなる設定にも触れる前に、サイト内で Colorbox がどこでどのように使われているかの完全な全体像を作ってください。

1. 画像フィールド。 すべてのコンテンツタイプについて Structure → Content Types → [Type] → Manage display にアクセスし、いずれかの画像フィールドが Colorbox フォーマッターを使っているか確認します。画像スタイルとキャプション設定を控えておきます。
2. メディアエンティティ。 Structure → Media types でメディアタイプの表示モードを確認します。画像や動画を伴う各メディアタイプについて繰り返します。
3. Views。 画像フィールドを含む Views を探し、使われているフィールドフォーマッターを確認します。Colorbox は Views の「Colorbox」フォーマットプラグインを通じて適用されていることもあります。
4. カスタムコード。 カスタムモジュールとテーマで、colorbox、.colorbox、Drupal.behaviors.colorbox、そしてライブラリキー colorbox/colorbox への参照を検索します。

# コードベース全体を素早く検索(Drupal のルートから実行)
grep -r "colorbox" web/modules/custom web/themes/custom \
  --include="*.php" --include="*.js" --include="*.twig" \
  --include="*.yml" -l

見つかったすべての場所を控えておいてください。置き換えの段階で、それぞれを再訪することになります。

4.2 バックアップと環境上の考慮

• アクティブな設定をエクスポート: drush config:export
• 開始前にエクスポートをバージョン管理へコミット
• 移行中は CSS/JS 集約を無効化(Admin → Performance)
• データベースのダンプを取得: drush sql:dump > pre-migration.sql
• デプロイパイプラインが設定変更をステージング/本番へ反映できることを確認

5 Drupal での GLightbox のインストールと有効化

5.1 GLightbox JavaScript ライブラリのインストール

Drupal の GLightbox モジュールは、アップストリームの GLightbox JS ライブラリに依存します。それを提供する方法は 2 つサポートされています。

オプション A — Composer + Asset Packagist(推奨)

# Asset Packagist をリポジトリとして追加(プロジェクトごとに一度)
composer config repositories.asset-packagist \
  composer https://asset-packagist.org

# ライブラリを require
composer require oomphinc/composer-installers-extender
composer require npm-asset/glightbox

composer.json の extra.installer-paths セクションに、npm-asset 用のインストールパスを追加、または存在を確認します。

"extra": {
  "installer-types": ["npm-asset", "bower-asset"],
  "installer-paths": {
    "web/libraries/{$name}": [
      "type:drupal-library",
      "type:npm-asset",
      "type:bower-asset"
    ]
  }
}

composer install を実行すると、ライブラリは web/libraries/glightbox/ に配置されます。

オプション B — 手動での配置

GLightbox の GitHub リリースページから最新版をダウンロードし、次のパスが存在するように中身を配置します。

web/libraries/glightbox/dist/js/glightbox.min.js
web/libraries/glightbox/dist/css/glightbox.min.css

5.2 GLightbox Drupal モジュールのインストールと有効化

# モジュールをダウンロード
composer require drupal/glightbox

# 有効化
drush en glightbox -y

# キャッシュをクリア
drush cr

Admin → Configuration → Media → GLightbox に移動して、ライブラリが検出されていることを確認し、グローバルな設定オプションを確認します。

6 Colorbox 機能の置き換え

6.1 画像フィールド

これは最も一般的な Colorbox のユースケースです。コンテンツタイプ上の画像フィールドがサムネイルを表示し、それをクリックするとフルサイズの画像が lightbox で開きます。

1. Structure → Content Types → [あなたのタイプ] → Manage display に移動します。
2. 画像フィールドを見つけます。Format のドロップダウンをクリックし、Colorbox から GLightbox に変更します。
3. 設定の歯車(⚙)をクリックしてフォーマッターを設定します。Image style(ページに表示されるサムネイル)と Linked image style(lightbox 内で読み込まれる画像)を設定します。必要ならキャプションを有効化します。
4. 表示設定を保存し、キャッシュをクリアします: drush cr。

この設定をエクスポートして YAML 経由で適用することもできます。コンテンツタイプの表示 YAML におけるフィールドフォーマッター設定の例:

# core.entity_view_display.node.article.default.yml(抜粋)
dependencies:
  module:
    - glightbox
    - image
content:
  field_image:
    type: glightbox
    label: hidden
    settings:
      image_style: medium
      image_link: ''
      glightbox_image_style: large
      glightbox_gallery: ''
      glightbox_caption: title
      glightbox_caption_custom: ''
    third_party_settings: {  }

6.2 メディアとギャラリー

Drupal のメディアシステムを使うサイトでは、移行の手順は似ていますが、メディアタイプの表示モードに適用されます。

• Structure → Media types → [タイプ] → Manage display にアクセスします。
• 画像ソースフィールドのフォーマッターを Colorbox から GLightbox に切り替えます。
• ギャラリーのグループ化には、GLightbox フォーマッター設定の Gallery ID フィールドを設定します。同じギャラリー ID を共有するすべての項目が、lightbox 内でグループとしてナビゲート可能になります。これは GLightbox のネイティブな data-gallery 属性に直接対応します。

キャプションのマッピングは単純です。GLightbox は data-description 属性を読み取ります。Drupal モジュールでは、これを画像の title または alt 属性、あるいはカスタムフィールドの値にマッピングできます。

6.3 Views との統合

Colorbox のフォーマットで画像を表示している Views がある場合、各 View を次のように更新します。

1. Structure → Views → [View 名] → Edit で View を開きます。
2. Fields で画像フィールドをクリックします。Formatter のドロップダウンで、Colorbox から GLightbox に切り替えます。
3. Colorbox の統合が Format レベルで扱われていた場合(例:「Colorbox」フォーマットプラグイン)、Unformatted list や Grid のような標準フォーマットに切り替え、代わりにフィールドレベルで GLightbox フォーマッターを適用します。
4. 保存してキャッシュをクリアします。

7 Colorbox の安全な削除

すべてのフォーマッターとカスタムコードを移行したら、Colorbox を安全に削除できます。依存関係のエラーを避けるため、次の順序に従ってください。

1. Colorbox モジュールをアンインストールします。 削除前にアンインストールすることで、Drupal が hook_uninstall() のクリーンアップを実行できます。

   drush pm:uninstall colorbox -y

2. composer.json から削除します。

   composer remove drupal/colorbox

3. 手動で配置していた場合は、web/libraries/colorbox/ から Colorbox JS ライブラリを削除します。
4. カスタムコードを整理します。 Colorbox の CSS クラス(.colorbox、.colorbox-load)、JavaScript ビヘイビア(Drupal.behaviors.colorbox)、あるいはライブラリの読み込み(colorbox/colorbox)への残った参照を検索して削除します。

5. すべてのキャッシュをクリアし、設定をエクスポートします。

   drush cr
   drush config:export

8 カスタマイズと拡張

8.1 GLightbox の設定オプション

GLightbox のグローバル設定ページ(Admin → Configuration → Media → GLightbox)は、最もよく必要となるオプションを公開します。これらは GLightbox の JavaScript API に直接対応します。

8.2 テーマ化とスタイリング

GLightbox には、クリーンなダークオーバーレイのデザインを提供する標準スタイルシート(glightbox.min.css)が付属します。ライブラリファイルを変更せずに、テーマ内で上書きします。

/* mytheme/css/glightbox-overrides.css */

/* オーバーレイの背景を変更 */
.glightbox-clean .goverlay {
  background: rgba(0, 0, 0, 0.92);
}

/* キャプション領域をスタイリング */
.glightbox-clean .gdesc-inner {
  font-family: inherit;
  font-size: 0.9rem;
  color: #f0f0f0;
  padding: 12px 16px;
}

/* ナビゲーション矢印を大きくする */
.glightbox-clean .gnext,
.glightbox-clean .gprev {
  width: 48px;
  height: 48px;
}

/* ライトモードのバリアント */
@media (prefers-color-scheme: light) {
  .glightbox-clean .goverlay {
    background: rgba(255, 255, 255, 0.95);
  }
  .glightbox-clean .gdesc-inner {
    color: #1a1a1a;
  }
}

上書きスタイルシートを、テーマの .libraries.yml で読み込みます。

# mytheme.libraries.yml
glightbox-overrides:
  version: VERSION
  css:
    theme:
      css/glightbox-overrides.css: {}
  dependencies:
    - glightbox/glightbox

次に、mytheme.info.yml でグローバルに読み込みます。

# mytheme.info.yml(抜粋)
libraries:
  - mytheme/glightbox-overrides

8.3 高度なユースケース

#attached によるプログラム的な読み込み

カスタムモジュールや preprocess フックで、任意のレンダー配列に GLightbox ライブラリを読み込めます。

// preprocess 関数、またはカスタムブロックの build() 内
$build['#attached']['library'][] = 'glightbox/glightbox';

// 設定の上書きを JS settings に渡す
$build['#attached']['drupalSettings']['glightbox'] = [
  'animation'  => 'fade',
  'loop'       => TRUE,
  'touchNavigation' => TRUE,
];

Twig テンプレートでのカスタムトリガー

Twig テンプレートで GLightbox トリガーを手動で作成するには、正しい属性を追加します。GLightbox は class="glightbox"(または設定した selector)を持つ任意の要素を拾います。

{# 単一の画像を開く #}
<a href="{{ file_url(node.field_hero_image.entity.uri.value) }}"
   class="glightbox"
   data-title="{{ node.label }}"
   data-description="{{ node.field_caption.value }}">
  {{ content.field_hero_image }}
</a>

{# ギャラリーグループ — 同じ data-gallery を持つすべての項目が一緒に開く #}
{% for item in node.field_gallery %}
  <a href="{{ file_url(item.entity.uri.value) }}"
     class="glightbox"
     data-gallery="gallery-{{ node.id }}"
     data-description="{{ item.alt }}">
    <img src="{{ file_url(item.entity.uri.value) | image_style('thumbnail') }}"
         alt="{{ item.alt }}" />
  </a>
{% endfor %}

カスタム初期化のための Drupal ビヘイビア

モジュールの管理 UI で公開されていないオプションで GLightbox を初期化する必要がある場合は、カスタムの Drupal ビヘイビアを使います。

// mytheme/js/glightbox-init.js
(function (Drupal, drupalSettings) {
  'use strict';

  Drupal.behaviors.mythemeGlightbox = {
    attach(context, settings) {
      // コンテキストごとに一度だけ初期化する
      const elements = context.querySelectorAll('.glightbox-custom:not(.glightbox-processed)');
      if (!elements.length) return;

      elements.forEach(el => el.classList.add('glightbox-processed'));

      const lightbox = GLightbox({
        selector: '.glightbox-custom',
        touchNavigation: true,
        loop: true,
        animation: 'fade',
        autoplayVideos: settings.glightbox?.autoplayVideos ?? true,
      });
    },
  };

}(Drupal, drupalSettings));

9 テストと品質保証

移行を完了したら、本番へデプロイする前に次の QA チェックリストを一通り確認してください。

機能テスト

• 影響を受けるすべてのコンテンツタイプで、クリック時に画像が lightbox で開く
• ギャラリーのナビゲーション(前/次の矢印、キーボードの矢印)が正しく機能する
• キャプションが表示され、期待されるフィールド値と一致する
• 動画項目(YouTube、Vimeo、ローカル)が自動再生され、正しく閉じる
• lightbox を閉じる(✕ ボタン、Escape キー、外側クリック)とフォーカスが復元される

クロスブラウザテスト

• Chrome/Edge(Chromium)、Firefox、Safari(macOS と iOS)
• テストしたすべてのブラウザで CSS トランジションが正しく描画されることを確認

モバイル・タッチテスト

• 左右にスワイプしてギャラリー項目をナビゲート
• 画像でピンチによるズーム(有効な場合)
• 小さな画面でオーバーレイがビューポートを正しく覆う

アクセシビリティのチェック

• Tab キーで lightbox のコントロール(閉じる、前、次)を巡回する
• 閉じたあと、フォーカスがトリガー要素に戻る
• スクリーンリーダーがダイアログとその内容をアナウンスする(NVDA または VoiceOver でテスト)
• axe DevTools または Lighthouse のアクセシビリティ監査を実行 — 重大なエラーゼロを目標に

パフォーマンス

• CSS/JS 集約を再度有効化し、GLightbox がなお初期化されることを確認
• Lighthouse のパフォーマンス監査を実行し、Colorbox のベースラインと比較
• テストしたすべてのページで JavaScript コンソールエラーがないことを確認

10 よくある問題とトラブルシューティング

画像が Lightbox で開かない

症状: 画像をクリックすると、GLightbox が開く代わりにリンク先の URL に遷移する。

• GLightbox ライブラリが読み込まれているか確認します。ブラウザの DevTools → Network タブを開き、glightbox でフィルターします。見当たらない場合は、ライブラリファイルが web/libraries/glightbox/dist/ に存在するか確認します。
• CSS/JS 集約が正しく機能していることを確認します。集約に関連する問題を切り分けるため、一時的に無効化してみます。
• 描画された HTML を確認し、トリガー要素に class="glightbox" 属性(または設定したカスタムセレクター)があることを確かめます。

キャプションが欠けている、またはギャラリーが壊れている

症状: キャプションが空、またはギャラリーのナビゲーションが項目を飛ばす。

• 描画された anchor タグを調べます。data-description が入力されており、グループ化された項目間で data-gallery の値が一致していることを確認します。
• Caption source フィールドフォーマッター設定が、空でないフィールドを指していることを確認します。
• ギャラリーのグループ化については、ギャラリー ID が一貫していることを確認します。Token モジュールがインストールされていないと、トークンで生成された ID が空文字列に解決されることがあります。

他の JS ライブラリとの競合

症状: GLightbox が部分的にしか初期化されない、またはコンソールエラーを出す。

• GLightbox ライブラリの重複読み込み(モジュール + テーマでの手動読み込み)を確認します。
• 他のライブラリが window.GLightbox を上書きしていないことを確認します。
• テーマが JS バンドラーを使っている場合、GLightbox が Drupal のアセットシステムで読み込まれるのに加えて、別途バンドルされていないことを確認します。

キャッシュと集約の問題

症状: 開発環境では GLightbox が動作するが、本番で壊れる。

• 設定変更をデプロイした後、本番で drush cr を実行します。
• web/libraries/glightbox/ が正しくコミット/デプロイされていることを確認します。libraries/ ディレクトリを対象とする .gitignore ルールによって除外されていることがあります。ライブラリが配置されるよう、CI/CD パイプラインで composer install --no-dev を使うことを検討してください。
• CSS 集約が GLightbox のスタイルシートをセレクターの詳細度を壊す形で圧縮する場合は、上書きファイルをアセット読み込み順の後方に追加します。

# 本番ですべてのキャッシュをクリア(Drush が利用可能な場合)
drush @prod cr

# ライブラリファイルが配置されているか確認
ls web/libraries/glightbox/dist/js/glightbox.min.js

11 結論

Colorbox から GLightbox への移行は、あらゆる Drupal プロジェクトにとって意味のあるフロントエンド近代化のステップです。その利点は具体的です。

• lightbox の経路から jQuery ランタイム依存を排除する
• 訪問者により速く軽い体験を届ける
• カスタムパッチなしで、標準でアクセシビリティ準拠を得る
• vanilla JavaScript へ向かう Drupal コアの方向性に沿う
• 活発に開発されるライブラリで、長期的な保守負担を減らす

移行そのものは、体系的に取り組めば低リスクです。まず監査し、フィールドフォーマッターを1つずつ移行し、レガシーコードを整理し、デプロイ前に十分にテストします。glightbox Drupal モジュールは、この大部分を宣言的にします。カスタムコードではなく、管理 UI での設定変更で済むのです。

より広範なフロントエンドの近代化を行うサイト — デカップルドやヘッドレスアーキテクチャへの移行、モダンなテーマ(Olivero、Gin、あるいはカスタムのデザインシステム)の採用、JavaScript の重量削減 — にとって、Colorbox を GLightbox に置き換えることは、最小のリスクで目に見える成果をもたらす、優れた限定的な出発点です。