Drupal 7 でオリジナルテーマに設定項目を追加する方法

今回の記事のテーマは「 Drupal のテーマに設定項目を追加する方法 」です。

Drupal （ドルーパル）で作成したオリジナルテーマにかんたんな設定項目を追加する方法をご紹介してみたいと思います。 テーマに設定項目を追加するのは一見大変そうに思えますが、豊富な API と規約のおかげで、お作法だけ覚えてしまえば実際はとてもかんたんです。 ここぞというときに便利なのでぜひ使えるようにしておきましょう！

尚、今回対象となる Drupal のバージョンは 7.x 、想定読者は Drupal に馴染みの薄い開発者の方を想定しています。

テーマに設定項目を追加する方法

例をあげながらテーマへの設定項目の追加方法を見ていきたいと思います。 今回は、「ブラウザのコンソール内に現在のウィンドウサイズが常時表示する開発用の機能」をテーマに持たせ、その機能をテーマの管理画面からオン/オフ切り替えられるようにしてみます。

作業の大きな流れは次のとおりです。

1. コードを置くファイルを作成
2. フォームフィールドを追加
3. 機能を追加

早速順番に見ていきましょう。

1. コードを置くファイルを作成

まずは設定項目を追加するためのコードを書くためのファイルを作成します。 対象となるテーマのディレクトリの直下に theme-settings.php を作成しましょう。 今回は説明をわかりやすくするため mytheme という名前のカスタムテーマをすでに作成しているものとします。

$ # 対象のテーマのディレクトリに移動して theme-settings.php を作成
$ cd /drupal_root/sites/all/theme/mytheme
$ touch theme-settings.php

2. フォームフィールドを追加

つづいて、フォームフィールドを追加します。 テーマの管理画面にフィールドを追加するには hook_form_system_theme_settings_alter() という長い名前のフックを利用すれば OK です。 書いてみましょう！

theme-settings.php:

<?php

/**
 * Implements hook_form_system_theme_settings_alter().
 */
function mytheme_form_system_theme_settings_alter(&$form, &$form_state) {

  // ウィンドウサイズを表示するオプションを追加
  $form['theme_development'] = array(
    '#type' => 'fieldset',
    '#title' => 'Theme development settings',
    'window_size_log_enabled' => array(
      '#type' => 'checkbox',
      '#title' => t('Show the current window size in window console.'),
      '#default_value' => theme_get_setting('window_size_log_enabled'),
    ),
  );
}

間に fieldset を挟んでいますがこちらはあまり重要ではありません。 重要なのは '#type' => 'checkbox', と '#default_value' => theme_get_setting('window_size_log_enabled'), の 2 行だけです。

これで新たにチェックボックスフィールドがテーマの管理画面に追加されるはずです。 Drupal のキャッシュをクリアして、テーマの管理画面を開いてみてください。 ちなみに mytheme という名前のテーマだと管理画面のパスは次のとおりになるかと思います。

/admin/appearance/settings/mytheme

チェックボックスにチェックを入れて「設定を保存」をクリックするとチェックボックスの状態が保存されることがご確認いただけるかと思います。

今回は単純なオン/オフのチェックボックスを用いましたが、その他のフィールドタイプも利用することができます。 利用可能なフィールドタイプとその設定方法については Form API リファレンスをご参照ください。

• Form API Reference | Drupal 7 | Drupal API

3. 機能を追加

これで設定値が保存できるようになったので機能の中身の方を作成していきましょう。 今回はシンプルな仕様なのでパッと作ってしまいます。

まずはテーマの template.php の方で設定値を読み込んで、設定が有効になっていれば JS コードを読み込むような処理を追加します。 まずは template.php を作成します。

$ # 対象のテーマのディレクトリに移動して theme-settings.php を作成
$ cd /drupal_root/sites/all/theme/mytheme
$ touch template.php

中に次のコードを追加しましょう。

template.php:

<?php

/**
 * Implements theme_preprocess_html()
 */
function mytheme_preprocess_html(&$variables) {

  // ウィンドウサイズをコンソールに表示するためのスクリプトを追加する
  $window_size_log_enabled = theme_get_setting('window_size_log_enabled');
  if ($window_size_log_enabled) {
    drupal_add_js(path_to_theme() . '/js/show_window_size.js', 'file');
  }
}

ここでは window_size_log_enabled という設定を読み込んでそれが TRUE になっていればテーマディレクトリの下の js/show_window_size.js というスクリプトファイルを読み込む処理を行っています。

続いて show_window_size.js を作成しましょう。

$ # 対象のテーマのディレクトリに移動して show_window_size.js を作成
$ cd /drupal_root/sites/all/theme/mytheme
$ mkdir js
$ touch js/show_window_size.js

中には以下の内容を入れてください。

show_window_size.js:

/**
 * @file
 * ウィンドウサイズをコンソールに表示する
 */

(function($) {

Drupal.behaviors.mythemeShowWindowSize = {};
Drupal.behaviors.mythemeShowWindowSize.attach = function(context, settings) {

  var $window;

  $window = $(window);

  // 最初のウィンドウサイズを表示
  showWindowSize($window);

  // リサイズが発生したときも最新のウィンドウサイズを表示
  $window.resize(function(event) {
    showWindowSize($window);
  });

  /**
   * ウィンドウサイズを表示する
   */
  function showWindowSize($window) {
    console.log({
      width: $window.width(),
      height: $window.height()
    });
  }

};

})(jQuery);

Drupal のお作法に従うためにちょっと眺めのコードになっていますが、肝心なのは showWindowSize() の部分だけなので今回はそこだけに注目していただき他は読み飛ばしていただいて大丈夫です。

ここまで来たらもう一度キャッシュをクリアしておきましょう。 設定のチェックが入っているときには JS のコードが読み込まれる形になっているはずです。いかがでしょうか？

その状態でブラウザのコンソールを開くと、ページの読み込み時とリサイズの際にウィンドウサイズがコンソールに表示されるはずです。 リサイズをしたときにはラグなしでどんどん値が出てくるのでちょっとわずらわしいかもしれません。

...

以上です。 いかがだったでしょうか？

今回は Drupal 7 のテーマに設定項目を追加する方法をご紹介しました。 ご覧いただきましたとおり、基本的には hook_form_FORM_ID_alter() を system_theme_settings というフォームに対して書けばただそれだけで OK です。 Form API で提供されるあらゆる機能が使える上に、設定値の保存については Drupal が裏側でよきようにやってくれるのでカスタムコードを書く必要はありません。 このあたりは規約に則ると大いにラクができる Drupal ならではな部分ですので、ぜひ活用していきたいところです。

今回の記事の範囲外のお話にはなりますが、 Drupal 8 の場合は drupal_add_js() 関数が廃止されたため JS ファイルを追加するにはレンダーアレイの #attached プロパティを使わないといけないなどのお作法のちがいがございます。 こちらを参考に D8 に応用する場合にはご留意いただければと思います。