管理画面が作れる！WordPressで自作のオプションページを実装する方法(Settings API)
みなさんこんにちは！エンジニアの高澤です！
今回はプラグインなしで自作のオプションページ（設定ページ）を実装する方法について解説していきたいと思います。
今回の内容はプラグイン開発でもしばしば機能の一部として実装される内容となっております。
プラグイン開発のみならず、テーマ作成にも実装されることがあるかと思いますので、ほぼほぼ必要になる実装内容といっても過言ではありません。
よろしければぜひテーマ作成やプラグイン開発などのお仕事の際にお役立ていただけますと幸いです。
目次
自作のオプションページとは
WordPressにおける自作のオプションページとは、WordPress管理画面に独自に作成した設定ページのことをいいます。
この自作のオプションページを通じて、開発者によって実装された、なにかしらのシステムや処理などを制御することを目的に実装されることが多いかと思います。
例えば、プラグイン開発において実装されることがしばしばあるかと思います。
その理由は、プラグイン専用のオプションページを作成して、そのプラグインで提供されている機能の動きやオプション的な部分をユーザーの思い通りに制御することができるように実装する必要になる場面が多いからです。
皆さんはプラグインをすでにいくつかインストールされているかと思いますが、大体プラグインごとに専用の設定ページが管理画面に追加されてますよね？
このように、プラグイン開発ではしばしば実装される内容になってくるので、自作オプションページの実装は非常に重要な技術なのです。
今回の実装内容について
実装する前に、今回の実装内容について事前にご説明させていただきます。
今回実装するのは以下のような独自のオプションページになります。
当記事のサンプルコードでは、データタイプの種類として「ラジオボタン」「チェックボックス」「テキスト」「画像」の4種類でご用意いたしました。
この4つがあればデータタイプの種類はひと通りカバーできており、プラグイン開発などで困ることは少ないかと思います。
また、万が一例えば「色」などのデータが必要になった場合でも「テキスト」ボックスを応用させて実装することなどが可能なため、ご自身で自由にカスタマイズしていただければと思います。
サンプルコードについて
ここで当記事の結論として解説の前にサンプルコードを掲載させていただきます。
以下のコードをfunctions.phpにコピー＆ペーストしてください。
<?php
// 設定ページのコンテンツを表示する関数
function my_custom_plugin_settings_page() {
wp_enqueue_media();
?>
<div class="wrap">
<h2>設定</h2>
<form method="post" action="options.php">
<?php settings_fields('my_custom_plugin_settings_group'); ?>
<h3>ラジオボタン</h3>
<label><input type="radio" name="sample_radio_data" value="sample_radio_data_1" <?php checked(get_option('sample_radio_data'), 'sample_radio_data_1', true); ?>> ラジオボタン1</label><br>
<label><input type="radio" name="sample_radio_data" value="sample_radio_data_2" <?php checked(get_option('sample_radio_data'), 'sample_radio_data_2'); ?>> ラジオボタン2</label><br>
<br>
<h3>チェックボックス</h3>
<label><input type="checkbox" name="sample_checkbox_data[]" value="sample_checkbox_data_1" <?php checked( !empty(get_option('sample_checkbox_data')) && in_array( 'sample_checkbox_data_1', get_option('sample_checkbox_data') ) ); ?>> オプション1</label><br>
<label><input type="checkbox" name="sample_checkbox_data[]" value="sample_checkbox_data_2" <?php checked( !empty(get_option('sample_checkbox_data')) && in_array( 'sample_checkbox_data_2', get_option('sample_checkbox_data') ) ); ?>> オプション2</label><br>
<br>
<h3>テキストボックス</h3>
<label><input type="text" name="sample_text_data" value="<?php echo esc_attr( get_option('sample_text_data') ); ?>"><span style="display:inline-block;margi-left:4px;"></span></label>
<br>
<h3>画像アップロード</h3>
<?php
$image_url = get_option('sample_image_data');
?>
<input type="text" name="sample_image_data" id="sample_image_data" value="<?php echo esc_attr($image_url); ?>" readonly>
<input type="button" id="upload_image_button" class="button" value="画像をアップロード">
<div id="image_preview" style="margin-top:10px;">
<?php if ($image_url) : ?>
<img src="<?php echo esc_url($image_url); ?>" style="max-width: 200px;">
<?php endif; ?>
</div>
<span id="upload_image_remove_button" style="display:inline-block;cursor:pointer;margin-top:5px;">
画像を削除
</span>
<script>
(function ($) {
var mediaUploader;
$('#upload_image_button').on('click', function (e) {
e.preventDefault();
if (mediaUploader) {
mediaUploader.open();
return;
}
// メディアアップローダーを呼び出し
var mediaUploader = wp.media({
title: 'Select Image',
library: { type: 'image' },
multiple: false,
});
// 画像が選択された時の処理
mediaUploader.on('select', function () {
var attachment = mediaUploader.state().get('selection').first().toJSON();
$('#sample_image_data').val(attachment.url);
$('#image_preview').html('<img src="' + attachment.url + '" style="max-width: 200px;">');
});
// メディアアップローダーを開く
mediaUploader.open();
});
})(jQuery);
(function ($) {
$('#upload_image_remove_button').on('click', function(e){
$('#sample_image_data').val("");
$('#image_preview').html("");
});
})(jQuery);
</script>
<br>
<?php submit_button(); ?>
</form>
</div>
<?php
}
// 設定ページを追加するアクションフック
add_action('admin_menu', 'my_custom_plugin_menu');
// 設定ページをメニューに追加する関数
function my_custom_plugin_menu() {
add_options_page(
'オリジナルの設定', // ページタイトル
'オリジナルの設定', // メニュータイトル
'manage_options', // 権限
'my-custom-plugin-settings', // ページスラッグ
'my_custom_plugin_settings_page' // コールバック関数
);
}
// 設定フィールドを登録するフック
add_action('admin_init', 'my_custom_plugin_register_settings');
// 設定フィールドを登録する関数
function my_custom_plugin_register_settings() {
register_setting('my_custom_plugin_settings_group', 'sample_radio_data');
register_setting('my_custom_plugin_settings_group', 'sample_checkbox_data');
register_setting('my_custom_plugin_settings_group', 'sample_text_data');
register_setting('my_custom_plugin_settings_group', 'sample_image_data');
}ペーストが完了し保存したら、管理画面ページを更新してください。
すると管理画面左メニューの「設定」に「オリジナルの設定」という項目が表示され、独自のオプションページが作成されたのが確認できるかと思います。
いってしまえばこれで完成になります。
お疲れ様でした！
次からは独自のオプションページの実装方法について具体的に詳しく解説していきますので、応用力をつけたい方はぜひ読み進めていただけますと幸いです。
当記事でオプションページ実装を学習するメリット
次に当記事でオプションページ実装を学習するメリットを解説いたします。
- プラグイン開発で使える
- 高度なテーマ開発ができる
- 独自システムを効率化でき管理・運用に貢献できる
当記事を読み進めていただければ独自のオプションページの実装方法がわかり、プラグイン開発や高度なテーマ開発、またご自身で実装いただいたシステムの効率化に繋がります。
当記事で解説するオプションページ実装の内容は、プラグイン開発でテンプレート感覚で利用できるようにサンプルコードを掲載いたしました。
サンプルコード自体もかなりカスタマイズしやすくいたしました。
そのため、実践で使えるというか、お仕事でそのままお役立ていただける構成になっているかと思います。
Settings APIとは
当記事のサンプルコードではSettings APIというWordPressのAPIを使用して実装されておりますので、ここで確認しておきましょう。
Settings API は、WordPressのオプションページ（設定ページ）を管理するためのWordPress公式の APIのことをいいます。
このAPIを使用することで、設定ページの作成、設定値の保存、入力値の検証などを簡単に行うことができます。
Settings APIを使用することで、セキュリティやデータ整合性の確保が簡単になります。
Settings APIが提供してくれる主な機能としては以下が挙げられます。
- オプションページ（設定ページ）の作成
- 設定値の保存と取得
- 検証とサニタイジング
それぞれ解説していきます。
オプションページ（設定ページ）の作成
独自のオプションページの作成には、Settings API を使用して add_options_page()関数などのページを追加する関数を呼び出すことで行います。
以下が具体的なコード例になります。
<?php
// 設定ページを作成する関数
function my_custom_plugin_settings_page() {
?>
<div class="wrap">
<h2>カスタムオプション</h2>
<form method="post" action="options.php">
<?php settings_fields('my_custom_plugin_settings_group'); ?>
<!-- ここに設定項目を記述 -->
<?php submit_button('保存'); ?>
</form>
</div>
<?php
}
// オプションページをメニューに追加する関数
function my_custom_plugin_menu() {
add_options_page(
'カスタムオプション', // ページタイトル
'カスタムオプション', // メニュータイトル
'manage_options', // 権限
'my-custom-plugin-settings', // ページスラッグ
'my_custom_plugin_settings_page' // コールバック関数
);
}
// アクションフックを使用してオプションページを追加、登録する
add_action('admin_menu', 'my_custom_plugin_menu');上記のコードでは、独自に定義したmy_custom_plugin_settings_page()関数でオプションページのHTMLを記述し、add_options_page()関数でそのオプションページを WordPress の管理メニューに追加しています。
独自に定義したmy_custom_plugin_settings_page()関数は、オプションページのHTMLを記述します。
<form> 要素内にはsettings_fields()関数を使用してセキュリティトークンを含む隠しフィールドを追加し、options.phpにデータを送信します。また、ここに設定項目を追加します。
add_options_page()関数は、独自のオプションページをWordPress管理画面左メニューの「設定」に追加します。
引数にはページのタイトル、メニューのタイトル、権限、ページスラッグ、コールバック関数を指定します。
ページスラッグは一意であり、管理メニュー内での位置を特定するために使用されます。
コールバック関数は、設定ページのHTMLを表示する関数です。
これにより、WordPress の管理画面に「設定」メニューの下に「カスタムオプション」という項目が追加され、そのページにはカスタムの設定項目が表示されるようになります。
設定値の保存と取得
オプションページの作成が完了したら、次は設定値の保存と取得の実装をします。
Settings API を使用してregister_setting()関数を呼び出すことで行います。
以下に、具体的なコードと解説を示します。
設定値の保存
設定値を保存するには、register_setting()関数を使用します。
<?php
// 設定フィールドを登録する関数
function my_custom_plugin_register_settings() {
register_setting('my_custom_plugin_settings_group', 'my_custom_option_name');
}
add_action('admin_init', 'my_custom_plugin_register_settings');上記のコードでは、register_setting()関数を使用して設定フィールドを登録しています。
第一引数には設定グループ名を指定し、第二引数にはオプション名（設定のキー）を指定します。
これにより、WordPressはこの設定を検証し、安全に保存します。
設定値の取得
設定値を取得するには、WordPressのget_option()関数を使用します。
$my_custom_option_value = get_option('my_custom_option_name');get_option()関数に設定のキーを渡すことで、対応する設定値を取得できます。
取得した値は、変数に代入して使用することができます。
具体的にコードを解説すると、独自に定義したmy_custom_plugin_register_settings()関数では、register_setting() 関数を使用して設定フィールドを登録しています。
これにより、WordPress は指定した設定グループ内の設定値を検証し、設定値の保存を管理します。
add_action('admin_init', 'my_custom_plugin_register_settings')の行は、設定フィールドを登録する関数をadmin_initアクションフックにフックしています。
これにより、管理画面が初期化されるときに設定フィールドが登録されます。
このように設定値の保存と取得を行うことで、カスタムの設定情報を安全に保存し、後で取得することができます。
検証とサニタイジング
最後に検証とサニタイジングを実装します。
検証とサニタイジングは、不正な入力やセキュリティ上のリスクを軽減するために非常に重要です。
Settings APIを使用して設定値を保存する際に、検証とサニタイジングを行うことができます。以下に、具体的なコードと解説を示します。
// 設定フィールドを登録する関数
function my_custom_plugin_register_settings() {
register_setting('my_custom_plugin_settings_group', 'my_custom_option_name', 'my_custom_sanitize_callback');
}
add_action('admin_init', 'my_custom_plugin_register_settings');
// サニタイジングコールバック関数
function my_custom_sanitize_callback($input) {
// サニタイジング処理を行う
$sanitized_input = sanitize_text_field($input);
// ここで追加の検証を行う場合があります
return $sanitized_input;
}上記コードは、独自に定義したmy_custom_plugin_register_settings()関数によって設定フィールドを登録する際に、サニタイジングのコールバック関数を指定しています。
ここでは register_setting()関数の第三引数にサニタイズ用に独自に定義したmy_custom_sanitize_callback関数を指定しています。
my_custom_sanitize_callback($input)の独自関数は、受け取った入力値をサニタイジングして安全な状態に変換します。
sanitize_text_field()関数を使用することで、入力値をテキストフィールドに適した形式に変換します。また、必要に応じて追加の検証を行うこともできます。
このように、サニタイジングは入力値を安全な状態に変換することを目的としています。
このプロセスにより、不正なデータや悪意のあるコードが保存されることを防ぎ、セキュリティを向上させることができます。
また、検証を行うことで、入力値が期待通りの形式であることを確認し、不正な入力を防止することができます。
Settings APIのまとめ
このように、Settings APIを使用することでWordPressのオプションページの作成や管理が簡単になります。
また、データの保存や取得、検証などのプロセスを簡素化し、開発者がよりセキュアで効率的なプラグインやテーマを作成できるようになります。
メディアアップローダーとは
メディアアップローダー（Media Uploader）とは、WordPress の機能の一つで、画像や動画などのメディアファイルをアップロードするためのツールです。
WordPressの管理画面のメディア機能やカスタム投稿タイプの編集画面などで利用されており、画像をアップロードするためのUIとして大変優れており、画像ファイルなどの管理・運用が非常に楽になります。
ちなみに下図がメディアアップローダーになります。
メディアアップローダーのサンプルコードとして、当記事では以下のように記述しております。
(function ($) {
var mediaUploader;
$('#upload_image_button').on('click', function (e) {
e.preventDefault();
if (mediaUploader) {
mediaUploader.open();
return;
}
// メディアアップローダーを呼び出し
var mediaUploader = wp.media({
title: 'Select Image',
library: { type: 'image' },
multiple: false,
});
// 画像が選択された時の処理
mediaUploader.on('select', function () {
var attachment = mediaUploader.state().get('selection').first().toJSON();
$('#sample_image_data').val(attachment.url);
$('#image_preview').html('<img src="' + attachment.url + '" style="max-width: 200px;">');
});
// メディアアップローダーを開く
mediaUploader.open();
});
})(jQuery);上記のコードは、jQuery を使用してWordPressのメディアアップローダーを呼び出し、画像が選択された際の処理を定義しています。
上記コードのメディアアップローダーの部分を切り分けて解説していきたいと思います。
メディアアップローダーの初期化
var mediaUploader;
$('#upload_image_button').on('click', function (e) {
// コードがここに入ります
});$('#upload_image_button')は、指定されたIDを持つ要素（通常はボタン）がクリックされたときに実行されるイベントハンドラーを定義しています。
このボタンをクリックすると、メディアアップローダーが起動します。
メディアアップローダーの呼び出し
var mediaUploader = wp.media({
title: 'Select Image',
library: { type: 'image' },
multiple: false,
});wp.media()関数を使用してメディアアップローダーを初期化します。
title はメディアアップローダーのタイトル、libraryはライブラリの種類（この場合は画像）、multiple は複数のファイルの選択ができるかどうかを指定します。
画像が選択されたときの処理
mediaUploader.on('select', function () {
// 選択された画像の処理がここに入ります
});mediaUploaderインスタンスにselect イベントハンドラーを追加し、画像が選択されたときの処理を定義します。
選択された画像の情報は attachment オブジェクトに格納され、その URL は attachment.url で取得できます。
メディアアップローダーの開始
mediaUploader.open();上記コードでメディアアップローダーを開始します。
初めてボタンがクリックされた場合は、この命令が実行されてメディアアップローダーが表示されます。
メディアアップローダーのまとめ
メディアアップローダーは、WordPress の多くの場所で利用され、コンテンツの豊かさや多様性を向上させるのに役立ちます。
また、開発者がカスタムフィールドやカスタム投稿タイプでメディアを扱う際にも頻繁に利用されますので、ここでしっかり内容をおさえておきいつでも使えるようにしましょう。
実装する方法
それでは早速、実装する方法について解説していきます。
すでに掲載させていただきましたが、以下のコードが独自のオプションページを実装するサンプルコードとなります。
以下のコードをfunctions.phpにコピー＆ペーストしてください。
<?php
// 設定ページのコンテンツを表示する関数
function my_custom_plugin_settings_page() {
wp_enqueue_media();
?>
<div class="wrap">
<h2>設定</h2>
<form method="post" action="options.php">
<?php settings_fields('my_custom_plugin_settings_group'); ?>
<h3>ラジオボタン</h3>
<label><input type="radio" name="sample_radio_data" value="sample_radio_data_1" <?php checked(get_option('sample_radio_data'), 'sample_radio_data_1', true); ?>> ラジオボタン1</label><br>
<label><input type="radio" name="sample_radio_data" value="sample_radio_data_2" <?php checked(get_option('sample_radio_data'), 'sample_radio_data_2'); ?>> ラジオボタン2</label><br>
<br>
<h3>チェックボックス</h3>
<label><input type="checkbox" name="sample_checkbox_data[]" value="sample_checkbox_data_1" <?php checked( !empty(get_option('sample_checkbox_data')) && in_array( 'sample_checkbox_data_1', get_option('sample_checkbox_data') ) ); ?>> オプション1</label><br>
<label><input type="checkbox" name="sample_checkbox_data[]" value="sample_checkbox_data_2" <?php checked( !empty(get_option('sample_checkbox_data')) && in_array( 'sample_checkbox_data_2', get_option('sample_checkbox_data') ) ); ?>> オプション2</label><br>
<br>
<h3>テキストボックス</h3>
<label><input type="text" name="sample_text_data" value="<?php echo esc_attr( get_option('sample_text_data') ); ?>"><span style="display:inline-block;margi-left:4px;"></span></label>
<br>
<h3>画像アップロード</h3>
<?php
$image_url = get_option('sample_image_data');
?>
<input type="text" name="sample_image_data" id="sample_image_data" value="<?php echo esc_attr($image_url); ?>" readonly>
<input type="button" id="upload_image_button" class="button" value="画像をアップロード">
<div id="image_preview" style="margin-top:10px;">
<?php if ($image_url) : ?>
<img src="<?php echo esc_url($image_url); ?>" style="max-width: 200px;">
<?php endif; ?>
</div>
<span id="upload_image_remove_button" style="display:inline-block;cursor:pointer;margin-top:5px;">
画像を削除
</span>
<script>
(function ($) {
var mediaUploader;
$('#upload_image_button').on('click', function (e) {
e.preventDefault();
if (mediaUploader) {
mediaUploader.open();
return;
}
// メディアアップローダーを呼び出し
var mediaUploader = wp.media({
title: 'Select Image',
library: { type: 'image' },
multiple: false,
});
// 画像が選択された時の処理
mediaUploader.on('select', function () {
var attachment = mediaUploader.state().get('selection').first().toJSON();
$('#sample_image_data').val(attachment.url);
$('#image_preview').html('<img src="' + attachment.url + '" style="max-width: 200px;">');
});
// メディアアップローダーを開く
mediaUploader.open();
});
})(jQuery);
(function ($) {
$('#upload_image_remove_button').on('click', function(e){
$('#sample_image_data').val("");
$('#image_preview').html("");
});
})(jQuery);
</script>
<br>
<?php submit_button(); ?>
</form>
</div>
<?php
}
// 設定ページを追加するアクションフック
add_action('admin_menu', 'my_custom_plugin_menu');
// 設定ページをメニューに追加する関数
function my_custom_plugin_menu() {
add_options_page(
'オリジナルの設定', // ページタイトル
'オリジナルの設定', // メニュータイトル
'manage_options', // 権限
'my-custom-plugin-settings', // ページスラッグ
'my_custom_plugin_settings_page' // コールバック関数
);
}
// 設定フィールドを登録するフック
add_action('admin_init', 'my_custom_plugin_register_settings');
// 設定フィールドを登録する関数
function my_custom_plugin_register_settings() {
register_setting('my_custom_plugin_settings_group', 'sample_radio_data');
register_setting('my_custom_plugin_settings_group', 'sample_checkbox_data');
register_setting('my_custom_plugin_settings_group', 'sample_text_data');
register_setting('my_custom_plugin_settings_group', 'sample_image_data');
}ペーストして保存していただき、管理画面ページを更新していただけますと下図のように管理画面左メニューの「設定」に「オリジナル設定」という項目名が追加されているかと思います。
「オリジナルの設定」をクリックしていただくと、下図のように独自のオプションページが実装されているのが確認できるかと思います。
内容としては、ラジオボタン、チェックボックス、テキスト、画像、の4種類となっており、それぞれデータを保存することができるようになっております。
改めまして、これでオリジナルの管理画面が実装できました。お疲れ様でした！
あとはご自身でお好きなようにカスタマイズしてください。
保存したデータを出力する方法
最後に保存したデータを出力する方法について解説していきたいと思います。
保存されたデータを出力するためには、基本的にget_option()関数を使用してオプションの値を取得し、必要に応じて表示します。
以下に、各種データを出力するための簡単なコード例を示します。
ラジオボタンの値を出力
<?php echo esc_html( get_option('sample_radio_data') ); ?>チェックボックスの値を出力
<?php
$checkbox_values = get_option('sample_checkbox_data', array());
if (!empty($checkbox_values)) {
foreach ($checkbox_values as $value) {
echo esc_html($value) . '<br>';
}
}
?>テキストボックスの値を出力
<?php echo esc_html( get_option('sample_text_data') ); ?>画像のURLを出力
<img src="<?php echo esc_url( get_option('sample_image_data') ); ?>">上記の各コードは、それぞれの設定値を適切にエスケープして表示しております。
esc_html() は HTML エスケープを行い、esc_url() は URL をエスケープします。
これにより、セキュリティ上のリスクを軽減し、正しいデータを表示することができます。
それぞれ簡単なコードにはなりますが、カスタマイズしやすいコードとなっているかと思います。
ご自身のサイトに合わせて適切な形でカスタマイズしていただけますと幸いです。
まとめ
プラグインなしで自作のオプションページ（設定ページ）を実装する方法についての解説は以上になります。
今回の内容はプラグイン開発でもしばしば機能の一部として実装される内容です。
また、プラグイン開発のみならずテーマ作成にも実装されることが多々ありますので、エンジニアにとっては学習すべき必須の実装スキルといっても過言ではありません。
よろしければぜひ当記事をプラグイン開発や高度なテーマ作成にお役立ていただけましたら幸いです。
UMENOKI編集部 高澤 翔汰
お気軽に皆さんのご要望をお聞かせください！
どんなに些細なことでも構いません！よろしければ記事や当サイトへの「こんな記事があったら仕事とかで役に立つな〜」や「こうだったらもっと役に立つのに！」といったようなご要望等をお気軽にお聞かせください！今後のサービス改善にお役立てさせていただきます！
例1）Reactの技術記事を書いてほしい！
例2）WordPressの使い方とかを初心者向けに解説してほしい！...など
