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

2019-12-02 /

コードサンプル

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

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

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

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

フィールドタイプ

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

text1行テキスト
textarea複数行テキスト
emailメールアドレス
number数値
urlURL
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

scriptstyle を含むすべての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);
}

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

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

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);
}

参考文献