テーマカスタマイズ関係でWordPressコアのコードを調べた

テーマカスタマイザーにカラーピッカーを追加する際、引数をどうすればいいか分からなくて困ってしまったので、コアのコードまで辿って調べました。

関連記事:テーマカスタマイザーに自由にカスタマイズ項目を追加する方法

CodexのテーマカスタマイズAPIにはずばり、カラーピッカーを追加する際の例が載ってます。

$wp_customize->add_control( 
  new WP_Customize_Color_Control(
     $wp_customize,
    'link_color',
     array(
       'label'      => __( 'Header Color', 'mytheme' ),
       'section'    => 'your_section_id',
       'settings'   => 'your_setting_id',
     ) ) );

しかし、この引数になってる配列には何を指定すればいいのか、よく分かりません。というか、書いてありません。本家の英語版Codexも解説内容は同等です。「add_controlメソッドも参照せよ」とありますので移動します。

クラスリファレンスに飛びました、WordPressコアの仕様書です。
Class Reference/WP Customize Manager/add control

$wp_customize->add_controlメソッドが取る引数はCodexによると下記の通り。

Parameters
$id
(mixed) (required) A string or a specific customization controller object. Default: None
$args
(array) (required) Not used if $id is a control object, otherwise an instance of WP_Customize_Control() (plain text) is created using the specified arguments. Default: None

WP_Customize_Manager/add_control

第一引数は文字列かコントローラーオブジェクトが必須です。
第二引数の配列は、第一引数がオブジェクトの場合は使われないので、add_control()への引数はオブジェクト1個で、今回はnew WP_Customize_Color_Control()ですね。

ということは、WP_Customize_Color_Controlクラスのコンストラクタ引数を確認すればいいわけです。

しかし、その説明がWP_Customize_Color_Controlクラスのリファレンスにありません。

テーマカスタマイザーAPIのコード例と同じ!

Codexの右上の検索フォームからWordPress.org内を検索するとCodexでなくdeveloper.wordpress.orgのクラスリファレンスが見つかります。

Code Reference WP_Customize_Color_Control

しかし、コードリファレンスはまたしてもこれだけです。

説明らしい説明がありませんので、表示されているWordPressコアのコードもみてみます。

/**
 * Constructor.
 *
 * @since 3.4.0
 * @uses WP_Customize_Control::__construct()
 *
 * @param WP_Customize_Manager $manager Customizer bootstrap instance.
 * @param string               $id      Control ID.
 * @param array                $args    Optional. Arguments to override class property defaults.
 */
  • 第一引数:カスタマイズマネージャーのインスタンス
  • 第二引数:ID(識別子)
  • 第三引数:デフォルトのプロパティを上書きするための配列 (オプショナル、渡さなくてもいい)

記述はありましたが、結局、コンストラクタ引数の配列には何を入れたらいいんでしょうか?

ここで注目すべきはclass-wp-customize-color-control.php の最初の宣言です。

class WP_Customize_Color_Control extends WP_Customize_Control

WP_Customize_Color_ControlWP_Customize_Controlを継承したクラスです。
WP_Customize_Controlをベースに、カラーピッカーを表示するために必要な変数、関数を追加する形になっています。

よって、インスタンス引数は WP_Customize_Control と同じでよい、ということです。

参考:PHP公式 オブジェクトの継承

ということで、 CodexのWP_Customize_Cotrolリファレンスを確認します。

ようやく、辿り着きました。Arguments以下の定義リストが WP_Customize_Color_Controlにも指定できる引数一覧です。

テーマカスタマイザーに自由にカスタマイズ項目を追加する方法の記事では、ここから必要な項目のみを指定しています。

ちなみにWP_Customize_Controlクラスのリファレンスからソースコードをたぐると、コメントのConstructorセクションに引数の説明があります。

Comments