Drupal で JavaScript をテーマやモジュールに追加する方法 日本語訳

本日は Drupal で JavaScript ファイルをページに追加する方法に関する Drupal.org の記事を日本語に翻訳してご紹介できればと思います。

このあたりが Drupal で JavaScript を使う上での最初の一歩となるかと思いますので、まだ Drupal を使い始めたてだけど Drupal で JS を使ってみたい、 jQuery を使ってみたい、という方はぜひご参考にしていただければと思います。

原文はこちらです。

• 4. Adding JavaScript to your theme or module | Drupal.org

以下、翻訳文です。 バージョンは 2014 年 01 月 25 日最終更新のものをもとにしています。 いつものごとく、日本語としてのわかりやすさを心がけ、ところによっては直訳、ところによっては意訳とていますので、原文のニュアンスが少し変わっている部分があるかもしれません。厳密なニュアンスが見たい方は原文の方にあたってみてください。

テーマやモジュールへの JavaScript への追加

PHP 関数 drupal_add_js() を使うと、 JavaScript のファイルや設定、インラインコードをページに追加することができます。 この関数は 5 つの引数を受け付けます。

ひとつめの引数は必ず js ファイルのパスか配列、 JavaScript コードになります。 ふたつめの引数が 'module' （デフォルト）や 'theme' 、 'core' の場合、ひとつめの引数はパスにしなくてはなりません。 これら 3 つの間のちがいは script タグがどの順番で読み込まれるかという他のスクリプトとの相対的な位置関係です。 まず最初にコアスクリプトが読み込まれ、次にモジュール、そして最後にテーマスクリプトが読み込まれるという順番になっています。

ふたつめの引数が 'setting' の場合は、ひとつめの引数は設定の配列でなくてはなりません。 これはモジュールの設定を JavaScript に伝えるとても便利な方法です。 詳しい解説は次のセクションに載っています。

ふたつめの引数のもうひとつのオプションは "inline" です。 これを与えると、ひとつめの引数に JavaScript コードを直接渡すという意味になります。 この場合、ひとつめの引数に与えられたコードはページ内の script タグの間に直接書き込まれ、スクリプトファイルの呼び出しは発生しません。

これらふたつがこの関数のもっとも重要な引数です。 あなたのやりたいことが js ファイルのモジュールへの追加だけあれば、ふたつめの引数を実際に使うことはないかもしれません。 しかし、 api.drupal.org のこの関数のドキュメントを読めばこの他の引数についても学ぶことができます。

モジュール内での JavaScript の追加

では、あなたのモジュールやテーマの出力要素をターゲットとする jQuery コードがすでにあるものとしましょう。 まずはシンプルに jQuery コードを JavaScript ファイルとして（つまり .js 拡張子で）保存しましょう。 次にそのファイルをあなたのモジュールやテーマのディレクトリに移動します。 モジュールの場合は上述のようにモジュールがコンテンツを出力すべきところで drupal_add_js() の呼び出しを行う必要があります（つまり、 hook_block や hook_nodeapi （訳注： hook_nodeapi は Drupal 6 の関数で Drupal 7 には存在しません）の中で呼び出します）。 JS がコンテンツ出力に作用しない場合には hook_menu や hook_init の中で呼び出すこともできます。 このファイルを hook_init で読み込むということは、必要かどうかにかかわらずすべてのページリクエストで処理されるということに注意しておきましょう。 ファイルの追加は次のように行います：

drupal_add_js(drupal_get_path('module', 'mymodule') .'/mymodule.js');

jquery.js ファイルは自動で読み込まれるので追加しようかどうかと心配する必要はありません。

フォームビルダ関数から JS （や CSS ）ファイルを追加するときのおすすめの方法は、次のような形でフォーム API の #attached プロパティを使うやり方です。

$form['#attached']['js'] = array(
  drupal_get_path('module', 'ajax_example') . '/ajax_example.js',
);

さらに詳しくはフォーム API リファレンスをご覧ください。

テーマ内での JavaScript の追加

drupal_add_js を使う （ Drupal 6 / 7 ）

（ drupal_add_js は Drupal 8 では非推奨となります。かわりに '#attached' を使ってください。） .js ファイルをテーマ内で追加したい場合は、シンプルに template.php の中で呼び出せば OK です。 この場合ふたつめの引数は 'theme' にしましょう。 すると、 Drupal はこのスクリプトがコアとモジュールのスクリプトがすべて読み込まれた後に読み込まれるべきだということがわかります。

drupal_add_js(drupal_get_path('theme', 'mytheme') .'/mytheme.js');

テーマの .info ファイルを使う

テーマの .info ファイル内でスクリプトパスを追加することができます。 追加すると Drupal は自動的にそれを読み込んでくれます。

name = My theme
description = Theme developed by me.
core = 7.x
engine = phptemplate
scripts[] = mytheme.js

preprocess_page 関数を使う

特定の条件をつけて js をテーマに追加したい場合は process_page 関数を使うとよいでしょう：

function mytheme_preprocess_page(&$vars, $hook) {
  if (true) {
    drupal_add_js(drupal_get_path('theme', 'mytheme') . '/mytheme.js');
    $vars['scripts'] = drupal_get_js(); // D7 の場合は必要？
  }
}

以上です。

いかがだったでしょうか？

Drupal 開発でふだん JS を使っている方も、改めて見ると発見になる部分があったりしたのではないでしょうか。 Drupal 7 では、モジュールで JavaScript といえばとにかく「 drupal_add_js 」でしたが、 Drupal 8 ではこれが非推奨となるとのことですので、また新たな方法も調べて身につけていきたいと思います。

Drupal で JS といえば、 JavaScript や jQuery のコーディングスタンダードを過去に翻訳していたりもしますので、よろしければこちらもご覧になってみてください。

• JavaScript コーディングスタンダード 日本語訳
• jQuery コーディングスタンダード 日本語訳