API настроек (опций)
API опций было добавлено в версии 2.7 и позволяет создавать поля формы для сохранения настроек. API автоматизирует сохранение опций в БД и вывод нужного HTML кода на экран. Такой подход дает возможность удобно добавлять свои опции и секции опций в уже существующие страницы настроек (Общие, Чтение, Медиафайлы и т.д.). Или можно создавать страницы настроек плагинов без использования лишнего кода.
Несмотря на все удобства, регистрация и проверка (очистка) значений полей никуда не исчезла - все это нужно делать вручную.
Смотрите также: API настроек для мультисайта (сети).
Заметка: все POST запросы с данными формы должны отправляться на страницу wp-admin/options.php
. Пользователи должны иметь право manage_options
. В мультисайт версиях должны быть Супер Админами (Super Admin), чтобы отправлять данные формы.
Все функции регистрации опций: register_setting(), add_settings_*()
и т.д. должны вызываться на хуке admin_init.
Функции API настроек
Регистрация/удаление опций
Добавление секций и отдельных полей
Вывод на экран
Ошибки
Добавление полей опций
Новое поле опции можно добавить в секцию на уже существующую страницу опций WordPress или на страницу опций плагина. Для этого используется функция add_settings_field().
Функция обратного вызова (callback) должна выводить html код поля (input, textarea, ...). 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 тег