【Chapter13】テーマカスタマイザーの実装

概要と目標カスタマイズAPIを使って、
テーマカスタマイザーの基本を理解しよう。

WordPressの管理画面に「カスタマイズ」という機能がある。
カスタマイズAPIというものを利用することで、
インタラクティブにテーマをカスタムすることができる。

今回のゴール

RERUN

テーマカスタマイザーとは管理画面からインタラクティブに
テーマをカスタマイズする機能。

テーマカスタマイザーとは「Lightning」というテーマでも使ったが、
WordPressには管理画面に「カスタマイズ」から様々なカスタマイズを行う機能。
これによって、ユーザーが、テンプレートファイルを触らずに、サイトをカスタマイズできる。
デフォルトでもサイトの設定はできるが、ここに独自のオプションを追加することもできる。

今回作る機能

固定フロントページの
メインビジュアルのテキスト変更
固定フロントページの
メインビジュアルの画像の変更

メインビジュアルの画像のカスタマイズは、「カスタムヘッダー」という機能でも実装できるが、今回は、柔軟性の高いテーマカスタマイザーで実装する。

カスタマイズAPI: WordPRessにはカスタマイズAPIという仕組みがあり、管理画面からのテーマ変更を比較的容易にカスタマイズできる仕組みになっている。ただし、カスタマイズAPIは、オブジェクト指向で設計されている為、完全に使いこなすには、ある程度WordPressの熟練度が必要になる。

カスタマイザーの登録`customeize_register`という
アクションフックに登録する。

テーマカスタマイザーの項目を追加するには、「functions.php」に、
customeize_registerというアクションフックを使って登録する。
なお、このアクションは、「$wp_customize （カスタマイザーオブジェクト）」という引数が必要になる。
テーマカスタマイズ画面に作成したテーマ設定はすべてこの「$wp_customize」オブジェクトのメソッドで実行される。

カスタマイザーの登録をしてみよう。

今回は、「dummy_customize_register」という独自関するを作る。
そして、その引数に $wp_customize を渡す。
なお、この関数を customeize_register アクションフックに登録するが、
登録しただけでは管理画面に反映しない。
テーマカスタマイザーを有効にするには、
「セクション」、「セッティング」、「コントロール」を追加して初めて画面に反映される。

「dummy」 › 「functions.php」をテキストエディタで開く
下記を参考にカスタマイザーを登録するコードを記述

dummy/functions.php

/*======================================
  テーマカスタマイザー
======================================*/
function dummy_customize_register( $wp_customize ) {
  // ここにセクション、テーマ設定、コントロールを追加します。

}
add_action( 'customize_register', 'dummy_customize_register' );

上書き保存

セクションの追加パネルにオリジナルの
メニューを追加する。

設定項目を追加するには、「セクション」が必要となる。
既存の「サイト基本情報」、「メニュー」の様なセクションに項目を追加することも可能だが、
新たなセクションに項目を追加することが多い。
なおセクションの追加は、add_section()」というメソッドで追加する。

add_secition()(アドセクション)関数・・・パネルにセクションを追加するメソッド

$wp_customize->add_section(セクション名, オプションの配列)
                                            省略可

引数の詳細はWordPress Codex 日本語版を参照

主なオプション
項目	説明
`'priority'`	セクションの優先順位（デフォルト： 160）
`'title'`	パネルに表示されるセクションのタイトル
`'description'`	セクションの冒頭に表示される説明文

セクションを追加してみよう

「dummy」 › 「functions.php」をテキストエディタで開く
下記を参考にセクションを追加するコードを記述

dummy/functions.php

/*======================================
  テーマカスタマイザー
======================================*/
function dummy_customize_register( $wp_customize ) {
  // ここにセクション、テーマ設定、コントロールを追加します。
  $wp_customize->add_section( 'front_page_options', [
    'title'       => 'フロントページ設定',
    'priority'    => 130,
    'description' => 'フロントページの設定',
  ]);
}
add_action( 'customize_register', 'dummy_customize_register' );

上書き保存

セッティングの追加コントロールと、
データベースを結ぶためのもの。

セッティングは、カスタムする項目とデータベースとを結びつけるもので、
add_setting()」というメソッドで追加する。
これによって、他に何もしなくてもテーマ設定の追加、保存、取得が可能になる。

add_setting()(アドセッティング)関数・・・パネルにセッティングを追加するメソッド

$wp_customize->add_setting(セッティング名, オプションの配列)
                                            省略可

引数の詳細はWordPress Codex 日本語版を参照

主なオプション
項目	説明
`'default'`	デフォルト値
`'transport'`	ライブプレビューの更新タイミング `'refresh'`（即時反映）【初期値】/ 'postMessage'（JavaScriptを活用した任意の方法）
`'sanitize_callback'`	データベース保存時にサーバ側で無害化するためのコールバック関数

セッティングを追加してみよう。

今回は、キャッチコピーを編集するセッティングと、ヒーローイメージを変更できるセッティングの2つを用意する。

「dummy」 › 「functions.php」をテキストエディタで開く
下記を参考にセッティングを追加するコードを記述

dummy/functions.php

/*======================================
  テーマカスタマイザー
======================================*/
function dummy_customize_register( $wp_customize ) {
  // ここにセクション、テーマ設定、コントロールを追加します。
  $wp_customize->add_section( 'front_page_options', [
    'title'       => 'フロントページ設定',
    'priority'    => 130,
    'description' => 'フロントページの設定',
  ]);

  /*
    キャッチコピー
  ----------------------------------- */
  $wp_customize->add_setting( 'hero_text', [
    'default' => 'Hello. I\'m Web Designer'
  ]);

  /*
    ヒーローイメージ
  ----------------------------------- */
  $wp_customize->add_setting( 'hero_image', [
    'default' => get_theme_file_uri() . '/assets/images/hero-image.jpg'
  ]);
}
add_action( 'customize_register', 'dummy_customize_register' );

上書き保存

コントロールの追加カスタマイズするための
コントロール部品を作る。

コントロールは、それぞれのセッティングに対応するコントロール部分。
add_control()」というメソッドで追加する。
基本的にはには、このadd_control()に入力形式を決めるコントロールのクラスを指定する。
一般的な入力フォームは WP_Customize_Control() というクラスを指定することでコントロールを追加でき、画像をアップロードするには、 WP_Customize_Image_Control() というクラスを指定する。

add_control()(アドコントロール)関数・・・パネルにコントロールを追加するメソッド

$wp_customize->add_control(コントロールのクラス名 または コントロール名, オプションの配列)
                                                                    省略可

引数の詳細はWordPress Codex 日本語版を参照

主なコントロールのクラス
項目	説明
`'WP_Customize_Control'`	テキスト、ラジオボタン、チェックボックスなどの一般的なコントロール部品
`'WP_Customize_Color_Control'`	カラーピッカーで色を指定するコントロール部品
`'WP_Customize_Date_Time_Control'`	日時を指定するコントロール部品
`'WP_Customize_Code_Editor_Control'`	コードエディタをテキストを指定するコントロール部品
`'WP_Customize_Image_Control'`	画像をアップロードする用のコントロール部品
`'WP_Customize_Media_Control'`	動画などのメディアをアップロードする用のコントロール部品

主なオプション
項目	説明
`'settings'`	このコントロールを関連付けるセッティングのID
`'section'`	このコントロールを関連付けるセクションのID
`'label'`	コントロールのラベル
`'description'`	コントロールの説明
`'type'`	コントロールのタイプ
`'choices'`	`'type'`が、 `'radio'` または `'select'` タイプのコントロールの選択肢のリスト値をキーとして指定し、ラベルを値として配列で指定する

コントロールを追加してみよう。

今回は、キャッチコピーの編集にはテキストフィールドを、ヒーローイメージは、画像アップロードのコントロール部品を使ってみる。

「dummy」 › 「functions.php」をテキストエディタで開く
下記を参考に各セッティングの下に、コントロールを追加するコードを記述

dummy/functions.php

/*======================================
  テーマカスタマイザー
======================================*/
function dummy_customize_register( $wp_customize ) {
  // ここにセクション、テーマ設定、コントロールを追加します。
  $wp_customize->add_section( 'front_page_options', [
    'title'       => 'フロントページ設定',
    'priority'    => 130,
    'description' => 'フロントページの設定',
  ]);

  /*
    キャッチコピー
  ----------------------------------- */
  $wp_customize->add_setting( 'hero_text', [
    'default' => 'Hello. I\'m Web Designer'
  ]);

  $wp_customize->add_control( new WP_Customize_Control( $wp_customize, 'hero_text_field', [
      'label'    => 'キャッチコピー',
      'section'  => 'front_page_options',
      'settings' => 'hero_text',
      'type'     => 'text',
    ])
  );

  /*
    ヒーローイメージ
  ----------------------------------- */
  $wp_customize->add_setting( 'hero_image', [
    'default' => get_theme_file_uri() . '/assets/images/hero-image.jpg'
  ]);

  $wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize, 'hero_image_upload', [
      'label'       => 'ヒーローイメージ',
      'section'     => 'front_page_options',
      'settings'    => 'hero_image',
      'description' => '画像をアップロードするとデフォルトの画像と入れ替わります。',
    ])
  );
}
add_action( 'customize_register', 'dummy_customize_register' );

上書き保存
管理画面にアクセス
（http://localhost/wp-lesson/wp-admin/）
「外観」 › 「カスタマイズ」に移動し、
「フロントページ設定」の項目と、各設定項目が追加されていることを確認

コントロールのサンプル様々なコントロールのサンプル。

テーマカスタマイザーのコントロールは非常にややこしいため、
よく使うサンプルを掲載しておく。

コントロールのサンプルを見てみよう。

functions.php

/*======================================
  テーマカスタマイザー
======================================*/
function sample_customize_register( $wp_customize ) {
  // セクション、テーマ設定、コントロールを追加します。
  $wp_customize->add_section( 'sample_section' , [
    'title'       => 'サンプル',
    'priority'    => 130,
    'description' => 'サンプルの説明文',
  ]);

  /*
    一般的なコントロール部品
  ----------------------------------- */

  // テキストフィールド
  $wp_customize->add_setting( 'sample_setting_text' );
  $wp_customize->add_control( new WP_Customize_Control( $wp_customize, 'sample_control_text', [
      'label'    => 'テキスト',
      'section'  => 'sample_section',
      'settings' => 'sample_setting_text',
      'type'     => 'text',
    ])
  );

  // テキストエリア
  $wp_customize->add_setting( 'sample_setting_textarea' );
  $wp_customize->add_control( new WP_Customize_Control( $wp_customize, 'sample_control_textarea', [
      'label'    => 'テキストエリア',
      'section'  => 'sample_section',
      'settings' => 'sample_setting_textarea',
      'type'     => 'textarea',
    ])
  );

  // ラジオボタン
  $wp_customize->add_setting( 'sample_setting_radio' );
  $wp_customize->add_control( new WP_Customize_Control( $wp_customize, 'sample_control_radio', [
      'label'    => 'ラジオボタン',
      'section'  => 'sample_section',
      'settings' => 'sample_setting_radio',
      'type'     => 'radio',
      'choices'  => [
        'value1' => '選択肢1',
        'value2' => '選択肢2',
        'value3' => '選択肢3',
      ]
    ])
  );

  // チェックボックス
  $wp_customize->add_setting( 'sample_setting_checkbox' );
  $wp_customize->add_control( new WP_Customize_Control( $wp_customize, 'sample_control_checkbox', [
      'label'    => 'チェックボックス',
      'section'  => 'sample_section',
      'settings' => 'sample_setting_checkbox',
      'type'     => 'checkbox',
    ])
  );

  // セレクトボックス
  $wp_customize->add_setting( 'sample_setting_select' );
  $wp_customize->add_control( new WP_Customize_Control( $wp_customize, 'sample_control_select', [
      'label'    => 'セレクトボックス',
      'section'  => 'sample_section',
      'settings' => 'sample_setting_select',
      'type'     => 'select',
      'choices'  => [
        'value1' => '選択肢1',
        'value2' => '選択肢2',
        'value3' => '選択肢3',
      ]
    ])
  );

  /*
    カラーピッカー
  ----------------------------------- */
  $wp_customize->add_setting( 'sample_setting_colorpicker' );
  $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'sample_control_colorpicker', [
      'label'    => 'カラーピッカー',
      'section'  => 'sample_section',
      'settings' => 'sample_setting_colorpicker',
    ])
  );

  /*
    日時
  ----------------------------------- */
  $wp_customize->add_setting( 'sample_setting_datetime' );
  $wp_customize->add_control( new WP_Customize_Date_Time_Control( $wp_customize, 'sample_control_datetime', [
      'label'    => '日時',
      'section'  => 'sample_section',
      'settings' => 'sample_setting_datetime',
    ])
  );

  /*
    コードエディター
  ----------------------------------- */
  $wp_customize->add_setting( 'sample_setting_editor' );
  $wp_customize->add_control( new WP_Customize_Code_Editor_Control( $wp_customize, 'sample_control_editor', [
      'label'    => 'コードエディター',
      'section'  => 'sample_section',
      'settings' => 'sample_setting_editor',
    ])
  );

  /*
    画像アップロード
  ----------------------------------- */
  $wp_customize->add_setting( 'sample_setting_image' );
  $wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize, 'sample_control_image', [
      'label'    => '画像アップロード',
      'section'  => 'sample_section',
      'settings' => 'sample_setting_image',
    ])
  );

  /*
    メディアアップロード
  ----------------------------------- */
  $wp_customize->add_setting( 'sample_setting_media' );
  $wp_customize->add_control( new WP_Customize_Media_Control( $wp_customize, 'sample_control_media', [
      'label'    => 'メディアアップロード',
      'section'  => 'sample_section',
      'settings' => 'sample_setting_media',
    ])
  );

  /*
    固定ページのセレクトボックス
  ----------------------------------- */
  $wp_customize->add_setting( 'sample_setting_pages', [
    'default'           => false, // 初期値を false 設定
    'sanitize_callback' => 'absint', // データベースで保存する際、整数に変換する
  ]);

  $wp_customize->add_control( 'sample_setting_pages', [
    'label'          => '固定ページのセレクトボックス',
    'section'        => 'sample_section',
    'type'           => 'dropdown-pages',
    'allow_addition' => true, // 固定ページの新規追加を可能にするか
  ]);

}
add_action( 'customize_register', 'sample_customize_register' );

カスタマイザーの値を出力カスタマイザーの値を取得するには、
`get_theme_mod()` 関数を使う。

カスタマイザーの値を取得には、「get_theme_mod()」という関数で取得できる。

get_theme_mod()(ゲットテーマモッド)関数・・・現在のテーマのテーマ設定値をひとつ取得する関数

get_theme_mod(取得するセッティング名, 存在しない場合の値)
                                        省略可

引数の詳細はWordPress Codex 日本語版を参照

カスタマイザーの値を出力してみよう。

基本的には、if文を使って、テーマ設定の値が存在するか確認してから出力するとよい。

「dummy」 › 「front-page.php」をテキストエディタで開く
下記を参考にテーマカスタマイザーの値を反映させる

dummy/front-page.php

<div class="p-hero -home">
  <figure class="p-hero__eyecatch">
    <?php if ( get_theme_mod( 'hero_image') ) : ?>
    <img src="<?php echo esc_url( get_theme_mod( 'hero_image') ); ?>" alt="">
    <?php endif; ?>
  </figure>

  <?php if ( get_theme_mod( 'hero_text') ) : ?>
  <p class="p-hero__title"><?php echo esc_html( get_theme_mod( 'hero_text') ); ?></p>
  <?php endif; ?>
</div>

上書き保存
サイトにアクセス
（http://localhost/wp-lesson）
「テーマカスタマイザー」の値が反映されているかを確認

ブラウザでの表示例

RERUN

新しいウインドウで表示する

カスタマイザーの出力サンプル様々なコントロールを出力するサンプル。

基本的にはどのコントロールも get_theme_mod() 関数で取得し、
それを出力することができる。
ただし、一部のコントロールはそのままでは、利用しにくいので、
他の関数と組み合わせて、使いやすいデータに変更することが多い。

コントロールのサンプルを見てみよう。

functions.php

<dl>
  <?php if ( get_theme_mod( 'sample_setting_text' ) ) : ?>
  <dt>テキスト</dt>
  <dd>
    <?php echo esc_html( get_theme_mod( 'sample_setting_text' ) ); ?>
  </dd>
  <?php endif; ?>

  <?php if ( get_theme_mod( 'sample_setting_textarea' ) ) : ?>
  <dt>テキストエリア</dt>
  <dd>
    <?php echo nl2br( esc_html( get_theme_mod( 'sample_setting_textarea' ) ) ); ?>
  </dd>
  <?php endif; ?>

  <?php if ( get_theme_mod( 'sample_setting_radio' ) ) : ?>
  <dt>ラジオボタン</dt>
  <dd>
    <?php echo esc_html( get_theme_mod( 'sample_setting_radio' ) ); ?>
  </dd>
  <?php endif; ?>

  <?php if ( get_theme_mod( 'sample_setting_checkbox' ) ) : ?>
  <dt>チェックボックス</dt>
  <dd>
    チェックオン
  </dd>
  <?php endif; ?>

  <?php if ( get_theme_mod( 'sample_setting_select' ) ) : ?>
  <dt>セレクトボックス</dt>
  <dd>
    <?php echo esc_html( get_theme_mod( 'sample_setting_select' ) ); ?>
  </dd>
  <?php endif; ?>

  <?php if ( get_theme_mod( 'sample_setting_colorpicker' ) ) : ?>
  <dt>カラーピッカー</dt>
  <dd style="color: <?php echo esc_attr( get_theme_mod( 'sample_setting_colorpicker' ) ); ?>">
    <?php echo esc_html( get_theme_mod( 'sample_setting_colorpicker' ) ); ?>
  </dd>
  <?php endif; ?>

  <?php if ( get_theme_mod( 'sample_setting_datetime' ) ) : ?>
  <dt>日時</dt>
  <dd>
    <time><?php echo esc_html( get_theme_mod( 'sample_setting_datetime' ) ); ?></time>
  </dd>
  <?php endif; ?>

  <?php if ( get_theme_mod( 'sample_setting_editor' ) ) : ?>
  <dt>コードエディター</dt>
  <dd>
    <pre><code><?php echo esc_html( get_theme_mod( 'sample_setting_editor' ) ); ?></code></pre>
  </dd>
  <?php endif; ?>

  <?php if ( get_theme_mod( 'sample_setting_image' ) ) : ?>
  <dt>画像アップロード</dt>
  <dd>
    <img src="<?php echo esc_url( get_theme_mod( 'sample_setting_image') ); ?>" alt="">
  </dd>
  <?php endif; ?>

  <?php if ( get_theme_mod( 'sample_setting_media' ) ) : ?>
  <dt>ファイルアップロード</dt>
  <dd>
    ID： <?php echo esc_html( get_theme_mod( 'sample_setting_media' ) ); ?>
  </dd>
  <?php endif; ?>

  <?php if ( get_theme_mod( 'sample_setting_pages' ) ) : ?>
  <dt>固定ページのセレクトボックス</dt>
  <dd>
    <?php
      $post = get_post( get_theme_mod( 'sample_setting_pages' ) ); // 固定ページを取得
      setup_postdata($post); // グローバル変数の $post にセット

      the_title();

      wp_reset_postdata(); // $post を元のメインループに戻す
    ?>
  </dd>
  <?php endif; ?>
</dl>

まとめテーマカスタマイザーは、
難しいけど便利。

管理画面から簡単にテーマをカスタマイズできるテーマカスタマイザーは、
非常に便利だが少々扱いが難しい。

セクションの追加は、$wp_customize->add_section()で追加
セッティングの追加は、$wp_customize->add_setting()で追加
コントロールの追加は、$wp_customize->add_control()で追加

Chapter13 テーマカスタマイザーの実装

今回作る機能

カスタマイザーの登録をしてみよう。

セクションを追加してみよう

セッティングを追加してみよう。

コントロールを追加してみよう。

コントロールのサンプルを見てみよう。

カスタマイザーの値を出力してみよう。

コントロールのサンプルを見てみよう。