WordPress カスタマイザー JavaScript API: 入門

Japanese (日本語) translation by Amelia Rossi (you can also view the original English article)

WordPress のカスタマイザーは実装されて以来、活発に開発されています。 JavaScript API を含め、API は絶えず進化しています。しかしながら、WordPress Codex の中ではあまり文書化されていません。そこで、実際に JavaScript API を活用する方法を書きました。

WordPress カスタマイザーの JavaScript API を活用することで、テーマカスタマイズ中にコントロールの変更をプレビューウィンドウに反映し、より魅力的なリアルタイム体験を提供することができます。

カスタマイザー JavaScript API を使用して、プレビューウィンドウにリアルタイムで変更を反映する方法についてご存知でしょうか。実装するにはtransport モードを postMessage に設定し、対応する JavaScript コードを次のように追加します。

wp.customize( 'blogname', function( value ) {
  value.bind( function( to ) {
		$( '.site-title a' ).text( to );
	} );
} );

しかしながら、API をさらに拡張することもできます。例えば「セクション」「パネル」「コントロール」を隠す、表示する、または移動したり、他の設定値に基づいて設定値を変更する、プレビューとコントロールを相互に接続するなどです。これらはチュートリアルで見てゆくものです。

簡単にはじめる

WordPress カスタマイザーには、カスタマイザー API の入力と出力を網羅するたくさんの記事と、いくつかのシリーズがあります。

WordPress Customizer のコアコンセプトと「パネル」「セクション」「セッティング」「コントロール」などのコンポーネントを理解していることを前提としています。そうでない場合は、先に進む前にチュートリアルやビデオコースを視聴することをおすすめします。

設定とコントロール

はじめる前に、このチュートリアルの目的となるカスタマイザーの「設定」と「コントロール」を見てみましょう。実際のコードも見てゆきます。

チュートリアルでは、Web サイトの「サイトタイトル」にフォーカスします。上のコードでは、通常の WordPress の「サイトタイトル」入力欄と、サイトタイトルを有効化または無効化するカスタムチェックボックスの2つのコントロールがあります。これら2つのコントロールは「サイト基本情報」セクションにあります。そして画像の右側にプレビューがあり、「サイトタイトル」が出力されています。

さらに以下のように、「サイトタイトル」の文字色と hover 色のを変える、色セクション内の2つのコントロールがあります

基本コード

このテーマは Underscores をベースにしており、すべてのカスタマイザー関連のコードは /inc/customizer.php ファイル内にあります。

function tuts_customize_register( $wp_customize ) {

	$wp_customize->get_setting( 'blogname' )->transport = 'postMessage';

	$wp_customize->get_setting( 'blogdescription' )->transport = 'postMessage';
	$wp_customize->get_control( 'blogdescription' )->priority = '12';

	$wp_customize->get_setting( 'header_textcolor' )->default = '#f44336';
	$wp_customize->get_setting( 'header_textcolor' )->transport = 'postMessage';

	// Checkbox to Display Blogname
	$wp_customize->add_setting( 'display_blogname', array(
		'transport' => 'postMessage',
	) );

	$wp_customize->add_control( 'display_blogname', array(
		'label'     => __( 'Display Site Title', 'tuts' ),
		'section'   => 'title_tagline',
		'type'      => 'checkbox',
		'priority'  => 11,
	) );

	// Add main text color setting and control.
	$wp_customize->add_setting( 'header_textcolor_hover', array(
		'default'           => '#C62828',
		'sanitize_callback' => 'sanitize_hex_color',
		'transport'         => 'postMessage',
	) );

	$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'header_textcolor_hover', array(
		'label'    => __( 'Header Text Color: Hover', 'tuts' ),
		'section'  => 'colors',
		'priority' => '11'
	) ) );
}
add_action( 'customize_register', 'tuts_customize_register' );

上のように、このチュートリアルでは私たちが必要としているコードをいくつか変更しました。

WordPress デフォルトの設定 blogdescription を 12 に下げ、チェックボックス設定 display_blogname が「サイトタイトル」入力フィールドの下に表示されるようにします。
display_blogname という名前の新しいコントロールを作成します。今回は priority を 11 に設定し、「サイトタイトル」と「タグライン」入力フィールドの間にします。
header_text のデフォルト色を #f44336 に、transport タイプを postMessage に設定します。
新しい設定 header_text_color も作成します。同様に、header_textcolor 設定のすぐ下に表示されるように、優先順位を11に設定します。

これらの設定はすべて、refresh ではなく postMessage で設定されます。 postMessage オプションを使用すると、値を非同期に転送し、プレビューウィンドウにリアルタイムで表示できます。ただし、変更を処理するために独自の JavaScript を記述する必要があります。

JavaScript の読み込み

JavaScript ファイルを2つ作成する必要があります。customizer-preview.js はプレビューを扱い、customizer-control.js はカスタマイザーパネル内のコントロールを処理します。

js
├── customizer-preview.js // 1. File to handle the Preview
├── customizer-control.js // 2. File to handle the Controls
├── navigation.js
└── skip-link-focus-fix.js

customizer-preview.js 内に以下のコードがあります。

( function( $ ) {
	// Codes here.
} )( jQuery );

今のところ、JavaScript 関数は空です。このシリーズの次のチュートリアルで、プレビューウィンドウで変更をプレビューする方法をさらに詳しく説明します。

もう一方のファイル customizer-control.js に次のコードを追加します。

(function( $ ) {
	wp.customize.bind( 'ready', function() {
		var customize = this;
		// Codes here
	} );
})( jQuery );

上のように、このファイルのコードはカスタマイザーの ready イベントにラップされます。これにより、カスタマイズされた機能の実行を開始する前に、設定、パネル、コントロールを含むカスタマイザー内のすべてが完全に準備されていることを確かめます。

最後にコードを追加したら、これら2つの JavaScript ファイルをそれぞれ異なる位置で読み込みます。

// 1. customizer-preview.js
function tuts_customize_preview_js() {
	wp_enqueue_script( 'tuts_customizer_preview', get_template_directory_uri() . '/js/customizer-preview.js', array( 'customize-preview' ), null, true );
}
add_action( 'customize_preview_init', 'tuts_customize_preview_js' );

// 2. customizer-control.js
function tuts_customize_control_js() {
	wp_enqueue_script( 'tuts_customizer_control', get_template_directory_uri() . '/js/customizer-control.js', array( 'customize-controls', 'jquery' ), null, true );
}
add_action( 'customize_controls_enqueue_scripts', 'tuts_customize_control_js' );

customizer-preview.js ファイルは customize_preview_init アクションフックを介してカスタマイザープレビューウィンドウ内に読み込みます。 customizer-control.js ファイルは、カスタマイザーのバックエンドでロードします。ここで、設定とコントロール要素には、 customize_controls_enqueue_scripts アクションフックを使用してアクセスできます。

その次は？

WordPress は創業以来、PHP に非常に多くの時間を費やしてきました。したがって、エコシステムをサポートする開発者の大部分が JavaScript API よりも PHP API に習熟しているのは驚くことではありません。

最近では、カスタマイザーと WP-API を使ってJavaScript と幅広く連携しています。 WordPress カスタマイザーで JavaScript API を把握することは非常に困難です。言及したように、WordPress では現在のところ最もドキュメント化されていません。したがって、私たちはこの問題を徹底的に踏まえます。

その間、WordPress 用の拡張ツールや WordPress で学ぶためのコードを構築するのに役立つユーティリティを探しているなら、Envato Market で利用可能なものをお忘れなく。

ここでは、WordPress JavaScript API を使用するための必須要素をすべて準備しました。今回はここで終わりです。シリーズの次の段階では、WordPress の JavaScript API の下にあるものをもっと明らかにし、テーマに即座に実装できる機能的なスクリプトを書くことにします。

乞うご期待！