登録されたコントロールタイプ

同じタイプの複数のカスタマイザーコントロールに対して1つのテンプレートを持つという概念を導入するために、カスタマイズマネージャーにコントロールのタイプを登録する方法を導入する必要がありました。以前は、カスタムコントロールオブジェクトは、WP_Customize_Manager::add_control()を使用してカスタムコントロールが追加されたときにのみ遭遇しました。しかし、タイプごとに1つのテンプレートをレンダリングするために追加されたコントロールタイプを検出することは、そのタイプの他のインスタンスがロードされていない場合に新しいコントロールを動的に作成することを許可しませんでした。WP_Customize_Manager::register_control_type() solves this: 

  1. add_action( 'customize_register', 'prefix_customize_register' );
  2. function prefix_customize_register( $wp_customize ) {
  3.   // Define a custom control class, WP_Customize_Custom_Control.
  4.   // Register the class so that its JS template is available in the Customizer.
  5.   $wp_customize->register_control_type( 'WP_Customize_Custom_Control' );
  6. }

すべての登録されたコントロールタイプは、WP_Customize_Manager::print_control_templates()によってカスタマイザーにテンプレートが印刷されます。

PHPコントロールデータをJavaScriptに送信する

カスタマイザーコントロールデータは常にコントロールJSモデルに渡されており、これは常に拡張可能でしたが、JSテンプレートで作業する際にはデータを送信する必要がある可能性が高くなります。PHPのrender_content()でアクセスしたいものは、コントロールテンプレートでアクセスできるようにJavaScriptにエクスポートする必要があります。WP_Customize_Controlは、デフォルトで以下のコントロールクラス変数をエクスポートします：

  • type
  • label
  • description
  • active（ブール値の状態）

カスタムコントロールのサブクラスでWP_Customize_Control::to_json()をオーバーライドすることにより、カスタムコントロールに特有の追加パラメータを追加できます。ほとんどの場合、すべてのコア変数がエクスポートされることを確認するために、親クラスのto_json()メソッドも呼び出すことをお勧めします。以下は、コアカラ―コントロールからの例です： 

  1. public function to_json() {
  2.   parent::to_json();
  3.   $this->json['statuses'] = $this->statuses;
  4.   $this->json['defaultValue'] = $this->setting->default;
  5. }

JS/アンダースコアテンプレーティング

カスタムコントロールクラスをコントロールタイプとして登録し、カスタムクラス変数をエクスポートしたら、コントロールUIをレンダリングするテンプレートを作成できます。WP_Customize_Control::content_template()（デフォルトでは空）をWP_Customize_Control::render_content()の代わりにオーバーライドします。レンダーコンテンツはまだ呼び出されるので、サブクラスでも空の関数でオーバーライドすることを忘れないでください。

アンダースコアスタイルのカスタムコントロールテンプレートはPHPに非常に似ています。WordPressコアの多くがJavaScript駆動になるにつれて、これらのテンプレートはますます一般的になっています。コアのサンプルテンプレートコードは、メディア、リビジョン、テーマブラウザ、さらにはTwenty Fifteenテーマで見つけることができ、ここではJSテンプレートがカラースキームデータを保存し、カスタマイザーでカラースキームの変更を即座にプレビューするために使用されています。これらのテンプレートがどのように機能するかを学ぶ最良の方法は、コアの既存のコードを研究することです。したがって、以下は簡単な例です： 

  1. class WP_Customize_Color_Control extends WP_Customize_Control {
  2.   public $type = 'color';
  3. // ...
  4.   /**
  5.    * Render a JS template for the content of the color picker control.
  6.    */
  7.   public function content_template() {
  8.    ?>
  9.    <# var defaultValue = '';
  10.    if ( data.defaultValue ) {
  11.    if ( '#' !== data.defaultValue.substring( 0, 1 ) ) {
  12.    defaultValue = '#' + data.defaultValue;
  13.    } else {
  14.    defaultValue = data.defaultValue;
  15.    }
  16.    defaultValue = ' data-default-color=' + defaultValue; // Quotes added automatically.
  17.    } #>
  18.    <label>
  19.    <# if ( data.label ) { #>
  20.    <span class="customize-control-title">{{{ data.label }}}</span>
  21.    <# } #>
  22.    <# if ( data.description ) { #>
  23.    <span class="description customize-control-description">{{{ data.description }}}</span>
  24.    <# } #>
  25.    <div class="customize-control-content">
  26.    <input class="color-picker-hex" type="text" maxlength="7" placeholder="<?php esc_attr_e( 'Hex Value' ); ?>" {{ defaultValue }} />
  27.    </div>
  28.    </label>
  29.    <?php
  30.   }
  31. }

上記のコアカスタムカラ―コントロールのテンプレートでは、閉じたPHPタグの後にJSテンプレートがあります。評価されるステートメントの周りには記法が使用されており、ほとんどの場合、これは条件文に使用されます。エクスポートしたすべてのコントロールインスタンスデータはdataオブジェクトに格納されており、ダブル（エスケープされた）またはトリプル（エスケープされていない）ブレース記法{{ }}を使用して変数を印刷できます。前述のように、このようなコントロールを書くコツをつかむ最良の方法は、既存の例を読み通すことです。WP_Customize_Upload_Controlは最近このAPIを活用するように更新されましたが、メディアマネージャーの実装方法と見事に統合され、最小限のコードから多くの機能を引き出しています。もし本当に良い練習をしたいなら、他のコアコントロールのいくつかをこのAPIを使用するように変換してみてください。そしてもちろん、コアにもパッチを提出してください！

ピースを組み合わせる

カスタムカスタマイザーコントロールサブクラスで新しいAPIを活用するために必要なことの要約は次のとおりです：

  • 1. render_content()関数を空にします（ただし、デフォルトのものをオーバーライドするために存在する必要があります）。
  • 2. 新しい関数content_template()を作成し、render_content()の古い内容をそこに置きます。
  • 3. コントロールに必要なカスタムクラス変数をJavaScriptにエクスポートするためにto_json()関数を修正します（例としてWP_Customize_Color_Controlを参照）。
  • 4. render_content()からPHPをJSテンプレートに変換し、評価するためにJSステートメントの周りにを使用し、変数を印刷するために{{ }}を使用します。PHPクラス変数はdataオブジェクトで利用可能です。たとえば、ラベルは{{ data.label }}で印刷できます。
  • 5. カスタムコントロールクラス/タイプを登録します。この重要なステップは、カスタマイザーにこのコントロールのテンプレートを印刷するように指示します。これは、追加されたすべてのコントロールのテンプレートを印刷することとは異なります。なぜなら、1つのテンプレートから多くのインスタンスのこのコントロールタイプをレンダリングできるというアイデアがあるからです。また、将来的に動的コントロール作成のために登録されたコントロールタイプが利用可能であることも重要です。$wp_customize->register_control_type( \’WP_Customize_Color_Control\’ );のようにしてください。

カスタマイズAPIのPHP専用部分は、引き続き完全にサポートされており、使用するのに問題ありません。しかし、カスタマイザーをより柔軟にするという長期的な目標を考えると、ページロードなしでカスタマイザーでテーマを切り替えるようなことを行うために、可能な限りJS/アンダースコアテンプレートを使用することを強くお勧めします。