WordPress テーマカスタマイズAPIチートシート

コードサンプル

基本的な書き方は、以下のコードを参照くだだい。

<?php
add_action('customize_register', 'themename_customize_register');

function themename_customize_register ($wp_customize) {

  $wp_customize->add_panel(
    'themename_panel', // パネルID
    array(
      'title'    => 'パネルタイトル',
      'priority' => 1000,
    )
  );

  $wp_customize->add_section(
    'themename_section', // セクションID
    array(
      'title'       => 'セクションタイトル',
      'description' => 'セクションの説明',
      'panel'       => 'themename_panel', // 紐付けるパネルIDを指定。省略すると最上位に表示される。
      'priority'    => 1000
    )
  );

  /////////////////////////////////////////////////////////////////////////////////////

  // Text 1行テキスト

  /////////////////////////////////////////////////////////////////////////////////////

  $wp_customize->add_setting(
    'themename_text', // 設定ID
    array(
      'default' => '',
      'priority' => 1000,
      'sanitize_callback' => 'sanitize_text_field'
    )
  );

  $wp_customize->add_control(
    'themename_control_text',
    array(
      'section'     => 'themename_section',  // 紐づけるセクションIDを指定
      'settings'    => 'themename_text',  // 紐づける設定IDを指定
      'label'       => '1行テキスト',
      'description' => '説明',
      'type'        => 'text'
    )
  );

  /////////////////////////////////////////////////////////////////////////////////////

  // Textarea テキストエリア 複数行テキスト

  /////////////////////////////////////////////////////////////////////////////////////

  $wp_customize->add_setting(
    'themename_textarea', // 設定ID
    array(
      'default' => '',
      'priority' => 1000,
      'sanitize_callback' => 'sanitize_text_field'
    )
  );

  $wp_customize->add_control(
    'themename_control_textarea',
    array(
      'section'     => 'themename_section',  // 紐づけるセクションIDを指定
      'settings'    => 'themename_textarea',  // 紐づける設定IDを指定
      'label'       => '複数行テキスト',
      'description' => '説明',
      'type'        => 'textarea'
    )
  );

  /////////////////////////////////////////////////////////////////////////////////////

  // Checkbox チェックボックス

  /////////////////////////////////////////////////////////////////////////////////////

  $wp_customize->add_setting(
    'themename_checkbox', // 設定ID
    array(
      'priority' => 1000,
      'sanitize_callback' => 'sanitize_text_field'
    );
  );

  $wp_customize->add_control(
    'themename_control_checkbox',
    array(
      'section'     => 'themename_section',  // 紐づけるセクションIDを指定
      'settings'    => 'themename_checkbox',  // 紐づける設定IDを指定
      'label'       => 'チェックボックス',
      'description' => '説明',
      'type'        => 'checkbox'
    )
  );

  /////////////////////////////////////////////////////////////////////////////////////

  // Radio ラジオボタン

  /////////////////////////////////////////////////////////////////////////////////////

  $wp_customize->add_setting(
    'themename_radio', // 設定ID
    array(
      'default' => 'value1',
      'priority' => 1000,
      'sanitize_callback' => 'sanitize_text_field'
    )
  );

  $wp_customize->add_control(
    'themename_control_radio',
    array(
      'section'     => 'themename_section',  // 紐づけるセクションIDを指定
      'settings'    => 'themename_radio',  // 紐づける設定IDを指定
      'label'       => 'ラジオボタン',
      'description' => '説明',
      'type'        => 'radio',
      'choices'     => array(
        'value1' => '選択肢 1',
        'value2' => '選択肢 2',
        'value3' => '選択肢 3'
      )
    )
  );

  /////////////////////////////////////////////////////////////////////////////////////

  // Select セレクトボックス

  /////////////////////////////////////////////////////////////////////////////////////

  $wp_customize->add_setting(
    'themename_select', // 設定ID
    array(
      'default' => 'value1',
      'priority' => 1000,
      'sanitize_callback' => 'sanitize_text_field'
    )
  );

  $wp_customize->add_control(
    'themename_control_select',
    array(
      'section'     => 'themename_section',  // 紐づけるセクションIDを指定
      'settings'    => 'themename_select',  // 紐づける設定IDを指定
      'label'       => 'セレクトボックス',
      'description' => '説明',
      'type'        => 'select',
      'choices'     => array(
        'value1' => '選択肢 1',
        'value2' => '選択肢 2',
        'value3' => '選択肢 3'
      )
    )
  );

  /////////////////////////////////////////////////////////////////////////////////////

  // Page Dropdown 固定ページドロップダウン

  /////////////////////////////////////////////////////////////////////////////////////

  $wp_customize->add_setting(
    'themename_page',
    array(
      'priority' => 1000,
      'sanitize_callback' => 'absint'
    )
  );

  $wp_customize->add_control(
    'themename_control_page',
    array(
      'section'     => 'themename_section',  // 紐づけるセクションIDを指定
      'settings'    => 'themename_page',  // 紐づける設定IDを指定
      'label'       => '固定ページ',
      'description' => '',
      'type'        => 'dropdown-pages',
    )
  );

  /////////////////////////////////////////////////////////////////////////////////////

  // Image Upload 画像アップロード URLを取得

  /////////////////////////////////////////////////////////////////////////////////////

  $wp_customize->add_setting(
    'themename_image',
    array(
      'default'           => get_theme_mod('themename_image'), // これを入れないとアップロードした画像のプレビューが消えてしまう
      'priority'          => 1000,
      'sanitize_callback' => 'esc_url_raw'
    )
  );

  $wp_customize->add_control(
    new WP_Customize_Image_Control(
      $wp_customize,
      'themename_control_image',
      array(
        'section'     => 'themename_section',  // 紐づけるセクションIDを指定
        'settings'    => 'themename_image',  // 紐づける設定IDを指定
        'label'       => '画像アップロード',
        'description' => '説明'
      )
    )
  );
  
  /////////////////////////////////////////////////////////////////////////////////////

  // Image Upload 画像アップロード 画像IDを取得

  /////////////////////////////////////////////////////////////////////////////////////

  $wp_customize->add_setting(
    'themename_image_id',
    array(
      'default'           => '',
      'priority'          => 1000,
      'sanitize_callback' => 'esc_url_raw'
    )
  );

  $wp_customize->add_control(
    new WP_Customize_Image_Control(
      $wp_customize,
      'themename_control_image_id',
      array(
        'section'     => 'themename_section',  // 紐づけるセクションIDを指定
        'settings'    => 'themename_image_id',  // 紐づける設定IDを指定
        'label'       => '画像アップロード',
        'description' => '説明'
      )
    )
  );
  

  /////////////////////////////////////////////////////////////////////////////////////

  // File Upload ファイルアップロード

  /////////////////////////////////////////////////////////////////////////////////////

  $wp_customize->add_setting(
    'themename_file',
    array(
      'default' => '',
      'priority' => 1000,
      'sanitize_callback' => 'themename_sanitize_file'
    )
  );

  $wp_customize->add_control(
    new WP_Customize_Upload_Control(
      $wp_customize,
      'themename_control_file',
      array(
        'section'     => 'themename_section',  // 紐づけるセクションIDを指定
        'settings'    => 'themename_file',  // 紐づける設定IDを指定
        'label'       => 'ファイルアップロード',
        'description' => '',
      )
    )
  );

  /////////////////////////////////////////////////////////////////////////////////////

  // Color Picker カラーピッカー

  /////////////////////////////////////////////////////////////////////////////////////

  $wp_customize->add_setting(
    'themename_color',
    array(
      'default'           => '',
      'priority'          => 1000,
      'sanitize_callback' => 'sanitize_hex_color'
    )
  );

  $wp_customize->add_control(
    new WP_Customize_Color_Control(
      $wp_customize,
      'themename_control_color',
      array(
        'section'     => 'themename_section',  // 紐づけるセクションIDを指定
        'settings'    => 'themename_color',  // 紐づける設定IDを指定
        'label'       => 'カラーピッカー',
        'description' => ''
      )
    )
  );
}

/////////////////////////////////////////////////////////////////////////////////////

// Sanitize Callback サニタイズ

/////////////////////////////////////////////////////////////////////////////////////

// チェックボックス用
function themename_sanitize_checkbox($input) {
  return $input ? true : false;
}

// ファイル用
function themename_sanitize_file($input, $setting) {
  $mimes = array(
    'jpg|jpeg|jpe' => 'image/jpeg',
    'gif'          => 'image/gif',
    'png'          => 'image/png',
    'svg'          => 'image/svg+xml',
    'bmp'          => 'image/bmp',
    'tif|tiff'     => 'image/tiff',
    'ico'          => 'image/x-icon'
  );
  $file = wp_check_filetype($input, $mimes);
  return ($file['ext'] ? $input : $setting->default);
}

WordPressのビルトインセクション

WordPressでもともと用意されている、add_control で指定できるセクション。

title_tagline	サイトタイトルと説明文
colors	色
header_image	ヘッダー画像
background_image	背景画像
static_front_page	ホームページ設定

フィールドタイプ

add_control の type で指定できるタイプ名。他にもあると思う。

text	1行テキスト
textarea	複数行テキスト
email	メールアドレス
number	数値
url	URL
select	セレクトボックス
checkbox	チェックボックス
radio	ラジオボタン
dropdown-pages	ドロップダウン固定ページ

設定値の読み出しには get_theme_mod()を使う

<?php
return get_theme_mod(設定ID, デフォルト値);

第1引数は設定ID、第2引数はデフォルト値を設定できる。add_setting の第2引数の default="xxx" でデフォルト値を設定してない場合でも、こちらに設定しておけば良い。

get_theme_mod()の注意点

注意点として、add_setting の第2引数に 'type' => 'option' 等を設定していると、get_theme_mod() が使えないので、覚えておくべし。

というのも、デフォルトでは theme_mods_テーマ名 という名前でoptionに登録されるのだが、 'type' => 'option' を設定した項目は、設定IDの名前でデータベースのoptionに登録されるため。なので、その場合 get_option() で取得する必要がある。

サニタイズ sanitize_callback

設定項目には sanitize_callback を指定するべき。なくても動くけど、テーマを公式リポジトリに公開するには全ての設定項目に sanitize_callback を設定しなければなりません。

テキスト / テキストエリア

sanitize_text_field

HTMLタグの削除や記号のエスケープなどで文字列を無害化する。前後の半角スペースのトリミングも行われる。

wp_strip_all_tags

script と style を含むすべてのHTMLタグを削除する。

wp_filter_nohtml_kses の方が、不正なHTMLをよりよい方法で処理しようとするが、完全なHTMLパーサーではなく、かつはるかに遅い。通常は wp_strip_all_tags が推奨される。

CSS

wp_strip_all_tags を使うとよい。

HTML

wp_filter_post_kses

文字列を無害化するが、HTMLタグが使える。script タグは削除される。インラインスタイルの display 属性など特定のプロパティは削除される。クオーテーション, ダブルクオーテーションはエスケープされる。

メールアドレス

sanitize_email

メールアドレスに使用できない文字を削除する。

URL

esc_url_raw

URLエンコードされる。

色

sanitize_hex_color

有効なHEXカラー（#000000 から #ffffff まで）の場合はそのまま、それ以外は null を返す。

数値

absint

数値を正の整数に変換する。

チェックボックス

自前で用意する。

function themename_sanitize_checkbox($input) {
  return (isset($input) ? true : false);
}

ラジオボタン / セレクトボックス

さまざまなサイトでこれ↓が紹介されているが…僕の環境では$choices が null になってしまうので使えない。

function themename_sanitize_select($input, $setting) {
  $input = sanitize_key($input);
  $choices = $setting->manager->get_control($setting->id)->choices;
  return (array_key_exists($input, $choices) ? $input : $setting->default);
}

null になる原因は、get_control() の引数に control のIDではなく setting のIDを入れてるからだと思うんだけど、皆はこれでうまく取得できているのだろうか？

もちろん、control のIDを手動でハードコードすると choices を正しく取得できる。つまり $setting からそれぞれの control のIDを取得できれば解決するのだが、ググっても方法がわからない。（上のコードばかり出てくる）。

というわけで、僕は代替としてsanitize_text_field を使ってる。

ドロップダウン固定ページ

absint を使う。

ファイルアップロード

自前で用意する。

function theme_slug_sanitize_image($input, $setting) {
  $mimes = array(
    'jpg|jpeg|jpe' => 'image/jpeg',
    'gif'          => 'image/gif',
    'png'          => 'image/png',
    'svg'          => 'image/svg+xml',
    'bmp'          => 'image/bmp',
    'tif|tiff'     => 'image/tiff',
    'ico'          => 'image/x-icon'
  );
  $file = wp_check_filetype($input, $mimes);
  return ($file['ext'] ? $input : $setting->default);
}

参考文献