API налаштувань (опцій)
API опцій було додано у версії 2.7 і дозволяє створювати поля форм (опції), які будуть оброблятися автоматично (зберігатися БД і виводитися на екран). Такий підхід дає можливість зручно додавати свої опції та блоки опцій у вже існуючі сторінки налаштувань (Загальні, Читання, Медіафайли тощо). Або можна створювати сторінки налаштувань плагінів без використання зайвого коду.
Незважаючи на всі зручності, реєстрація та перевірка значень полів нікуди не зникла – все це потрібно робити вручну. Використання API дозволяє уникнути багатьох багів, пов’язаних зі створенням сторінок налаштувань плагінів в адмінці.
Примітка: всі post дані форми повинні надсилатися на сторінку wp-admin/options.php. Користувачі повинні проходити перевірку можливості: manage_options, а мультисайтових версіях повинні бути Супер Адмінами (Super Admin), щоб відправляти дані форми.
register_setting() і всі функції реєстрації опцій та їх блоків: add_settings_*(), повинні викликатися в момент спрацювання хукаadmin_init
Функції API
Реєстрація/видалення опцій
Додавання блоків та окремих полів
Виведення на екран
Помилки
Додавання полів опцій
Нове поле опції можна додати в розділ на вже існуючу сторінку опцій WordPress або на сторінку опцій плагіна. Для цього використовується функція add_settings_field() .
Функція зворотного дзвінка (callback) повинна виводити html код поля input. Значення значення поля також повинно заповнитися. WordPress сам подбає про збереження опції до бази даних (зазвичай зберігається в таблицю wp_options, але можна і переналаштувати).
Примітка: опція, що додається, повинна бути спочатку зареєстрована функцією register_setting, інакше вона не буде зберігатися і оновлюватися.
add_settings_field( $id, $title, $callback, $page, $section = 'default', $args = array() );
$id – Ярлик (slug) опції, що використовується як ідентифікатор поля. Використовується в атрибуті ID тега.
$title – заголовок поля.
$callback – назва функції зворотного дзвінка. Функція повинна заповнювати поле потрібним
<input>тегом, який стане частиною великої форми. Атрибут name повинен дорівнювати параметру $option_name з register_setting(). Атрибут id зазвичай дорівнює параметру $id. Результат повинен відразу виводитись на екран (echo).$page – сторінка меню, в яку буде додано поле. Вказувати слід slug сторінки, тобто. параметр повинен дорівнювати параметру $menu_slug з add_theme_page() . На базових сторінках WordPress назви рівні: general, reading, writing і т.д. по аналогії…
$section – назва секції сторінки налаштувань, до якої має бути додано поле. За промовчанням default або може бути секцією доданої функцією add_settings_section.
- $args – додаткові параметри, які мають бути передані callback функції.
Додавання секції опцій
Секції опцій – це блоки опцій, виділені заголовком. Замість того, щоб створювати нову сторінку налаштувань, іноді розумніше додати нову секцію на вже існуючу сторінку налаштувань WordPress – це зробить плагін більш простим і WordPress не буде навантажений новою сторінкою налаштувань плагіна.
add_settings_section( $id, $title, $callback, $page );
$id – ідентифікатор секції. До цього ID прикріплюються поля (див. add_settings_field()).
$title – заголовок секції (назва блоку).
$callback – функція зворотного дзвінка, яка виконується на початку секції, перед виведенням полів. У ній можна вивести текст, що описує секцію, виводити потрібно відразу на екран, використовуючи echo.
- $page – тип сторінки налаштувань, де буде показано секція (general, reading, writing, …).
Реєстрація опцій
register_setting($option_group, $option_name, $sanitize_callback);
unregister_setting( $option_group, $option_name, $sanitize_callback );
$option_group – назва групи, до якої належить опція. Повинна збігатися з групою функції settings_fields().
$option_name – назва опції, яка зберігатиметься.
- $sanitize_callback – функція зворотного виклику, яка оброблятиме значення перед збереженням.
Виведення секції опцій на екран
Коли API використовується для додавання опцій до вже існуючої сторінки опцій, немає необхідності турбуватися про html тег самої форми, тому що вона вже додана на сторінці і опції (input поля) будуть вставлятися всередині цієї форми. Однак, коли ви створюєте нову сторінку опцій, вам потрібно вказати HTML тег форми (form) і його структуру.
settings_fields
Щоб вивести приховані поля та забезпечити безпеку даних форми опцій, використовуйте функцію settings_fields() :settings_fields( $option_group );
- $option_group – назва групи. Повинно збігатися з таким же параметром register_setting(). Ця назва сторінки (її slug), на якій виводяться опції.
do_settings_sections
Щоб вивести секцію, призначену для сторінки опцій, потрібно використовувати функцію do_settings_sections() :do_settings_sections( $page );
- $page – альтернативна назва (slug) сторінки секції якої потрібно вивести. Повинен збігатися з назвою сторінки функції add_settings_section().
Функція do_settings_fields() схожа на do_settings_sections(), вона також виводить поля для певної сторінки та секції, тільки ці поля не форматуються у табличний вигляд, а виводяться як є. Зазвичай не потрібно викликати цю функцію безпосередньо, а потрібно використовувати do_settings_sections(), щоб вивести поля опцій, пов’язані з секцією.
submit_button
Форма опцій потребує кнопки надсилання даних. Для цього використовуйте функцію submit_button().
Виведення всього блоку форми
І на завершення вам потрібно буде додати HTML тег <form> у якому вказати атрибути action=”options.php” method=”POST”. Цей приклад показує, як правильно виводити форму для окремої сторінки опцій з використанням раніше зареєстрованих полів:
<form method="POST" action="options.php"> <?php settings_fields( 'my-page' ); // Назва групи опцій - register_setting($option_group) do_settings_sections( 'my-page' ); // slug сторінки, на якій виводиться форма submit_button(); ?> </form>
Приклади
#1. Додаткові опції на сторінці налаштування WordPress “Читання”
Додамо нову секцію із двома новими опціями на базову сторінку налаштувань WordPress “Читання”
// ------------------------------------------------ ------------------
// Вішаємо всі блоки, поля та опції на хук admin_init
// ------------------------------------------------ ------------------
//
add_action( 'admin_init', 'eg_settings_api_init');
function eg_settings_api_init() {
// Додаємо блок опцій на базову сторінку "Читання"
add_settings_section(
'eg_setting_section', // секція
'Заголовок для секції налаштувань',
'eg_setting_section_callback_function',
'reading' // сторінка
);
// Додаємо поля опцій. Вказуємо назву, опис,
// функцію виводить html код поля опції.
add_settings_field(
'eg_setting_name',
'Опис поля опції',
'eg_setting_callback_function', // можна вказати ''
'reading', // сторінка
'eg_setting_section' // секція
);
add_settings_field(
'eg_setting_name2',
'Опис поля опції2',
'eg_setting_callback_function2',
'reading', // сторінка
'eg_setting_section' // секція
);
// Реєструємо опції, щоб вони зберігалися під час відправлення
// $_POST параметрів і щоб callback функції опцій виводили їх значення.
register_setting('reading', 'eg_setting_name');
register_setting( 'reading', 'eg_setting_name2');
}
// ------------------------------------------------ ------------------
// Сallback функція для секції
// ------------------------------------------------ ------------------
//
// Функція спрацьовує на початку секції, якщо не потрібно виводити
// ніякий текст або робити щось ще до того, як виводити опції,
// то функцію можна використовувати для цього вкажіть '' у третьому
// Параметри add_settings_section
//
function eg_setting_section_callback_function() {
echo '<p>Текст, що описує блок налаштувань</p>';
}
// ------------------------------------------------ ------------------
// Callback функції виводять HTML код опцій
// ------------------------------------------------ ------------------
//
// Створюємо checkbox та text input теги
//
function eg_setting_callback_function() {
echo '<input
name="eg_setting_name"
type="checkbox"
'. checked (1, get_option ( 'eg_setting_name'), false). '
value="1"
class="code"
/>';
}
function eg_setting_callback_function2() {
echo '<input
name="eg_setting_name2"
type="text"
value="' . get_option( 'eg_setting_name2' ) . '"
class="code2"
/>';
}Що вийшло і який блок за що відповідає:
#2. Сторінка налаштувань плагіна (опції в масиві)
Давайте створимо плагін, в якому буде лише сторінка налаштувань. Зробимо ми це, щоб розібратися, як працює API налаштувань.
Тут реєструється одна опція і до неї додаються кілька різних опцій як масив даних. Так зручніше та практичніше.
<?php
/*
* Plugin name: Primer
* Description: Демонстрація створення сторінки налаштувань для плагіна
*/
/**
* Створюємо сторінку налаштувань плагіна
*/
add_action('admin_menu', 'add_plugin_page');
function add_plugin_page(){
add_options_page( 'Параметри Primer', 'Primer', 'manage_options', 'primer_slug', 'primer_options_page_output' );
}
function primer_options_page_output(){
?>
<div class="wrap">
<h2><?php echo get_admin_page_title() ?></h2>
<form action="options.php" method="POST">
<?php
settings_fields('option_group'); // приховані захисні поля
do_settings_sections( 'primer_page'); // секції з налаштуваннями (опціями). У нас вона лише одна 'section_id'
submit_button();
?>
</form>
</div>
<?php
}
/**
* Реєструємо налаштування.
* Налаштування зберігатимуться в масиві, а не одне налаштування = одна опція.
*/
add_action('admin_init', 'plugin_settings');
function plugin_settings(){
// Параметри: $option_group, $option_name, $sanitize_callback
register_setting( 'option_group', 'option_name', 'sanitize_callback' );
// Параметри: $id, $title, $callback, $page
add_settings_section( 'section_id', 'Основні налаштування', '', 'primer_page');
// параметри: $id, $title, $callback, $page, $section, $args
add_settings_field('primer_field1', 'Назва опції', 'fill_primer_field1', 'primer_page', 'section_id' );
add_settings_field('primer_field2', 'Інша опція', 'fill_primer_field2', 'primer_page', 'section_id' );
}
## Заповнюємо опцію 1
function fill_primer_field1(){
$ val = get_option('option_name');
$val = $val? $val['input'] : null;
?>
<input type="text" name="option_name[input]" value="<?php echo esc_attr( $val ) ?>" />
<?php
}
## Заповнюємо опцію 2
function fill_primer_field2(){
$ val = get_option('option_name');
$val = $val? $val['checkbox'] : null;
?>
<label><input type="checkbox" name="option_name[checkbox]" value="1" <?php checked( 1, $val ) ?> /> відзначити</label>
<?php
}
## Очищення даних
function sanitize_callback( $options ){
// Очищаємо
foreach( $options as $name => & $val ){
if( $name == 'input' )
$ val = strip_tags ($ val);
if( $name == 'checkbox' )
$ val = intval ($ val);
}
//die(print_r($options)); // Array ([input] => aaaa [checkbox] => 1)
return $options;
}У результаті отримаємо таку сторінку:
Тепер давайте розберемо код по порядку, від загального до часткового…
Щоб швидко засвоїти принцип, треба мислити категоріями, а не змінними…
Категорія 1: Створення сторінки налаштувань
Реєструємо сторінку налаштувань іншою функцією, що не стосується API налаштувань:
add_options_page( 'Параметри Primer', 'Primer', 'manage_options', 'primer_slug', 'primer_options_page_output' );
- ‘primer_slug’ – це ярлик сторінки налаштувань і він по суті в API налаштувань ніде не фігурує.
Категорія 2: Виведення секції на сторінці налаштувань
Сторінка налаштувань є, тепер на ній нам потрібно викликати секцію з налаштуваннями. Самої секції поки що немає і в ній теж нічого немає. Секцію та її вміст ми створимо трохи нижче:
<form action="options.php" method="POST">
<?php
settings_fields('option_group'); // приховані захисні поля
do_settings_sections( 'primer_page'); // секції з налаштуваннями (опціями). У нас вона лише одна 'section_id'
submit_button();
?>
</form>Категорія 3: Реєстрація/створення секції
add_settings_section( 'section_id', 'Основні налаштування', '', 'primer_page');
- ‘section_id’ – щоб до цієї секції потім додати поля
- ‘primer_page’ – прив’язує цю секцію висновку секції do_settings_sections( ‘primer_page’ );
Категорія 4: Заповнення секції опціями
add_settings_field('primer_field1', 'Назва опції', 'fill_primer_field1', 'primer_page', 'section_id' );
add_settings_field('primer_field2', 'Інша опція', 'fill_primer_field2', 'primer_page', 'section_id' );
- ‘section_id’ – додає поле до секції.
- ‘primer_page’ – додаткове уточнення, що потрібно додати поле в секцію, яка викликається з параметром do_settings_sections( ‘primer_page’ ); .
Категорія 5: Реєстрація налаштування
Зараз у нас вже повністю готовий весь виведення налаштувань, але збереження не працює, тому що WordPress не знає про нову опцію. Потрібно сказати WordPress, що є налаштування option_nameі її потрібно обробляти.
register_setting( 'option_group', 'option_name', 'sanitize_callback' );
‘option_group’ – потрібно виведення прихованих полів, захисту форми. Для settings_fields(‘option_group’);
‘option_name’ – назва опції, яка буде записуватися в таблицю wp_options
- ‘sanitize_callback’ – функція для зміни/очищення даних, що передаються. Її можна вказувати, тоді дані зберігатися як є (як передаються).
#3. Поле із введенням телефону
Додамо поле із введенням телефону на сторінку “Загальні налаштування”:
add_action( 'admin_init', 'phone_settings_api_init');
function phone_settings_api_init() {
register_setting( 'general', 'phone', 'sanitize_text_field');
add_settings_field(
'phone',
'<label for="phone">Телефон</label>',
'phone_field_html',
'general'
);
}
function phone_field_html() {
$ value = get_option( 'phone', '' );
printf( '<input type="text" id="phone" name="phone" value="%s" />', esc_attr( $value ) );
}Виведемо збережений телефон на екран у потрібному місці шаблону:
echo esc_html( get_option( 'phone', '' ) );