wp_localize_script()は登録済みscriptへPHPの値をJavaScript objectとして渡す

wp_localize_script()は登録済みscriptへPHPの値をJavaScript objectとして渡す

公開日：2014年5月4日執筆：佐藤

wp_enqueue_script()wp_localize_script()wp_register_script()

wp_localize_script()を使うときは、先にscriptを登録し、同じhandleへPHP配列を結び付けます。WordPressは、登録したscriptを出力するとき、その直前へJavaScript objectを出力します。

handle、object name、渡す値は別の識別です。三つを一つの名前で済ませず、どのscriptが、どのobjectから、何を読むかを決めてください。

handleは値を受け取るscriptを指定する

wp_localize_script( $handle, $object_name, $l10n )の第一引数は、値を結び付けるscriptのhandleです。WordPress 3.9の公式Coreでは、wp_localize_script()が同じhandleをWP_Scripts::localize()へ渡します。

handleに対応するscriptは、wp_register_script()またはwp_enqueue_script()で先に登録します。存在しないhandleへ値を渡しても、読み込むscriptとの対応を作れません。

次は、テーマ内の説明用scriptへ表示文とURLを渡す仮例です。実在するテーマのコードではありません。

function satolab_enqueue_map_script() {
    wp_register_script(
        'satolab-map',
        get_template_directory_uri() . '/js/map.js',
        array(),
        '1.0',
        true
    );

    wp_localize_script(
        'satolab-map',
        'satolabMap',
        array(
            'markerLabel' => __( 'Office', 'satolab' ),
            'ajaxUrl'     => admin_url( 'admin-ajax.php' )
        )
    );

    wp_enqueue_script( 'satolab-map' );
}

add_action( 'wp_enqueue_scripts', 'satolab_enqueue_map_script' );

この例では、satolab-mapがscriptのhandle、satolabMapがJavaScriptのobject nameです。PHP配列のmarkerLabelとajaxUrlは、JavaScriptから次のように読めます。

var label = satolabMap.markerLabel;
var endpoint = satolabMap.ajaxUrl;

object nameはJavaScriptで有効な固有名にする

第二引数は、出力されるJavaScript変数の名前です。WordPress 3.9のCoreは、この名前を使ってvar satolabMap = ...;というコードを作ります。

object nameには、テーマまたはプラグインを識別できる接頭語を付けます。ハイフンを含むhandleを、そのままobject nameへ使ってはいけません。satolab-mapはhandleとして使えますが、JavaScript変数には-を含められないため、satolabMapまたはsatolab_mapのようにします。

短いdataやsettingsだけでは、ほかのscriptが作る変数と衝突する可能性があります。handleとobject nameは同じ役割ではないので、それぞれに適した名前を付けます。

PHP配列はobjectまたはarrayとして出力される

第三引数には、一階層または複数階層のPHP配列を渡せます。連想配列ならJavaScript object、数値添字の配列ならJavaScript arrayとして出力されます。

wp_localize_script()の主な用途は、PHPで翻訳した文字列をJavaScriptへ渡すことです。WordPressのサーバー側で作ったURLや画面設定も渡せます。ただし、出力された値はページのHTMLから読めます。パスワード、外部サービスの秘密鍵、公開してはいけない設定を入れないでください。

WordPress 3.9では、配列の上位にあるscalar値が文字列として処理されます。数値として計算する値は、JavaScript側で変換が必要です。

var limit = parseInt(satolabMap.limit, 10);

数値、真偽値、空文字を混在させる前に、JavaScript側で必要な型を決めます。値があることと、その値が期待する型であることを分けて確認します。

objectは登録済みscriptが出力される直前に置かれる

wp_localize_script()を呼んだ時点では、JavaScriptのscript要素がただちに画面へ出るわけではありません。値はhandleへ保存され、enqueueされたscriptがページへ出力されるときに一緒に出ます。

2014年3月27日保存の公式Codexも、実際の出力はenqueueされたscriptが印字される時点だと説明しています。WordPress 3.9のWP_Scripts::do_item()では、追加データを出力してから、対応する外部scriptのscript要素を出力します。

この順序により、外部scriptは読み込み時点からobjectを参照できます。ただし、対応するscriptをenqueueしなければ、objectもページへ出力されません。

footerへ出すscriptでは、footerのscript出力前までに値を結び付けます。scriptがすでに印字されたあとでwp_localize_script()を呼んでも、そのscriptより前へ戻ってobjectを追加することはできません。

翻訳文字列と処理条件を同じobjectへ詰め込まない

一つのobjectへ値を増やし続けると、どの画面がどの値を必要とするか分からなくなります。渡す値は、対応するscriptがそのページで使うものへ絞ります。

たとえば、表示文、通信先URL、表示件数を渡す場合でも、次の責任を分けます。

値	決める側	JavaScriptで行うこと
翻訳済みの表示文	PHPと翻訳ファイル	読者へ表示する
サイト内URL	WordPress	通信先または移動先として使う
件数の上限	PHPの設定	文字列から数値へ変換して使う