Настройки API: регистрация и вывод опций, добавление полей и секций

# Настройки API (Опции)

Настройки API были добавлены в версии 2.7 и позволяют создавать поля форм для сохранения параметров. Этот API автоматизирует процесс сохранения опций в базе данных и генерирует необходимый HTML-код для отображения. Благодаря этому удобно добавлять свои опции и секции опций на существующие страницы настроек (Общие, Чтение, Медиа и т.д.). Также вы можете создавать страницы настроек для плагинов, не используя лишний код.

Не смотря на все удобства, регистрацию и проверку значений полей (санитацию) всё же нужно выполнять вручную.

## Содержание

- Функции API настроек
- Добавление полей опций
- Добавление секций опций
- Регистрация опций
- Вывод секций опций на экран
- Примеры
  - #1. Дополнительные опции на странице настроек "Чтение"
  - #2. Страница настроек плагина (опции в массиве)
  - #3. Поле ввода телефона

**Примечание:** Все POST-запросы с данными формы должны отправляться на страницу wp-admin/options.php. Пользователи должны иметь права manage_options. В мультисайтовых версиях им нужно быть Супер Администраторами для отправки данных формы.

Все функции регистрации опций: register_setting(), add_settings_*() и т.д. должны вызываться на хуке admin_init.

## Функции API настроек

### Регистрация/отмена опций

- register_setting()
- unregister_setting()

### Добавление секций и индивидуальных полей

- add_settings_section()
- add_settings_field()

### Вывод на экран

- settings_fields()
- do_settings_sections()
- do_settings_fields()

### Ошибки

- add_settings_error()
- get_settings_errors()
- settings_errors()

## Добавление полей опций

Вы можете добавить новое поле опции в секцию на существующей странице настроек WordPress или на странице настроек плагина. Это делается с помощью функции add_settings_field().

Функция обратного вызова должна вывести HTML-код для поля (input, textarea и т.д.). WordPress сам позаботится о сохранении опции в базу данных. Обычно данные сохраняются в таблице wp_options, но это можно изменить.

Перед добавлением опции её нужно зарегистрировать с помощью функции register_setting(); в противном случае опция не будет сохранена или обновлена.

Пример вызова функции:

```php
add_settings_field( $id, $title, $callback, $page, $section = 'default', $args = array() );

• $id — Идентификатор опции, используется для HTML-атрибута id.
• $title — Заголовок поля.
• $callback — Имя функции обратного вызова, которая выводит input тег, часть одной большой формы.
• $page — Страница меню, на которую будет добавлено поле. Нужно указать идентификатор страницы.
• $section — Заголовок секции в настройках, куда будет добавлено поле. По умолчанию — 'default'.
• $args — Дополнительные параметры, которые будут переданы функции обратного вызова.

Добавление секций опций

Секции опций — это блоки опций с названием. Вместо создания новой страницы настроек, иногда разумнее добавить новую секцию на существующей странице настроек WordPress. Это упростит плагин и не будет загружать WordPress новой страницей настроек.

Пример вызова функции:

add_settings_section( $id, $title, $callback, $page );

• $id — Идентификатор секции. Поля прикрепляются к этому ID.
• $title — Заголовок секции (название блока).
• $callback — Функция обратного вызова, выполняемая в начале секции.
• $page — Тип страницы настроек, на которой будет отображаться секция.

Регистрация опций

Функция регистрации выглядит так:

register_setting( $option_group, $option_name, $sanitize_callback );

• $option_group — Название группы, к которой принадлежит опция. Должно совпадать с группой в функции settings_fields().
• $option_name — Имя опции, которая будет сохранена.
• $sanitize_callback — Функция обратного вызова для обработки значения перед сохранением.

Вывод секций опций на экран

При использовании API для добавления опций на существующую страницу настроек, не нужно беспокоиться о HTML-теге формы, так как он уже добавлен на страницу. Однако, при создании новой страницы настроек, необходимо указать тег формы (form) и её структуру.

settings_fields

Чтобы вывести скрытые поля и обеспечить безопасность данных формы, используйте функцию settings_fields():

settings_fields( $option_group );

• $option_group — Имя группы, которое должно совпадать с параметром в register_setting().

do_settings_sections

Чтобы вывести секцию на странице опций, используйте функцию do_settings_sections():

do_settings_sections( $page );

• $page — Альтернативное имя страницы секции, которое должно совпадать с именем страницы в add_settings_section().

Функция do_settings_fields() работает аналогично, но выводит поля для определённой страницы и секции без форматирования в табличный вид. Обычно нет необходимости вызывать её напрямую.

submit_button

Форма опций должна содержать кнопку отправки. Для этого используйте функцию submit_button().

Вывод всего блока формы

Вам нужно добавить HTML-тег:

Примеры

1. Дополнительные опции на странице настроек "Чтение"

Давайте добавим новую секцию с двумя новыми опциями на базовую страницу настроек "Чтение".

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' // страница
    );

    add_settings_field(
        'eg_setting_name',
        'Описание поля опции',
        'eg_setting_callback_function',
        'reading', // страница
        'eg_setting_section' // секция
    );

    add_settings_field(
        'eg_setting_name2',
        'Описание другого поля опции',
        'eg_setting_callback_function2',
        'reading', // страница
        'eg_setting_section' // секция
    );

    register_setting( 'reading', 'eg_setting_name' );
    register_setting( 'reading', 'eg_setting_name2' );
}

function eg_setting_section_callback_function() {
    echo '
Текст, описывающий блок настроек
';
}

function eg_setting_callback_function() {
    ?>
    
        value="1"
        class="code"
    />
    
    
    

/*
 * Название плагина: Primer
 * Описание: Демонстрация создания страницы настроек для плагина
 */

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(){
    ?>
    

        

        

            
        
    
    
    
    
     /> галочка
     & $val ){
        if( $name == 'input' )
            $val = strip_tags( $val );

        if( $name == 'checkbox' )
            $val = intval( $val );
    }
    return $options;
}

add_action( 'admin_init', 'phone_settings_api_init' );

function phone_settings_api_init() {
    register_setting( 'general', 'phone', 'sanitize_text_field' );

    add_settings_field(
        'phone',
        'Телефон',
        'phone_field_html',
        'general'
    );
}

function phone_field_html() {
    $value = get_option( 'phone', '' );
    printf( '', esc_attr( $value ) );
}

echo esc_html( get_option( 'phone', '' ) );