Функция do_settings_fields() в WordPress с примерами

Функция do_settings_fields() в WordPress используется для вывода полей настроек, зарегистрированных для определенной страницы и секции. Она является частью Settings API и обычно вызывается в сочетании с функциями add_settings_section() и add_settings_field(). Эта функция выводит HTML-код для полей, относящихся к указанной секции на странице админ-панели.

do_settings_fields( 
    string $page, 
    string $section 
)

Параметры

• $page (string) – Идентификатор страницы настроек (slug), на которой нужно вывести поля. Должен совпадать с параметром $page в функции add_settings_section().
• $section (string) – Идентификатор секции, поля которой нужно вывести. Должен совпадать с параметром $id в функции add_settings_section().

Как это работает

Функция do_settings_fields() используется в пределах формы, чтобы динамически вывести зарегистрированные поля для заданной страницы и секции. Она не обрабатывает поля или их вывод по стилям, а просто выводит их в том виде, в котором они были зарегистрированы. Для создания таблиц с полями используют дополнительные обертки HTML, например <table class="form-table">.

Пример 1: Вывод полей для страницы настроек плагина

Предположим, у нас есть плагин, который добавляет свои настройки на страницу general. Мы зарегистрировали новую секцию и поля, а теперь хотим вывести их в форме на странице.

<?php
add_action('admin_menu', 'my_custom_settings_page');

function my_custom_settings_page() {
    add_options_page(
        __('Настройки плагина', 'textdomain'), 
        __('Мой плагин', 'textdomain'), 
        'manage_options', 
        'my_plugin_settings', 
        'my_settings_page_callback'
    );
}

function my_settings_page_callback() {
    ?>
    <div class="wrap">
        <h1><?php _e('Настройки плагина', 'textdomain'); ?></h1>
        <form action="options.php" method="POST">
            <?php
            settings_fields('my_plugin_options_group'); // Регистрация настроек
            do_settings_fields('my_plugin_settings', 'my_plugin_section'); // Вывод полей
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

add_action('admin_init', 'my_plugin_settings_init');

function my_plugin_settings_init() {
    // Регистрация новой секции
    add_settings_section(
        'my_plugin_section', 
        __('Моя секция', 'textdomain'), 
        'my_plugin_section_callback', 
        'my_plugin_settings'
    );
    
    // Регистрация поля в этой секции
    add_settings_field(
        'my_custom_field', 
        __('Мое поле', 'textdomain'), 
        'my_custom_field_callback', 
        'my_plugin_settings', 
        'my_plugin_section'
    );
    
    // Регистрация самой опции
    register_setting('my_plugin_options_group', 'my_custom_field');
}

function my_plugin_section_callback() {
    echo '<p>' . __('Описание для моей секции', 'textdomain') . '</p>';
}

function my_custom_field_callback() {
    $value = get_option('my_custom_field', '');
    echo '<input type="text" name="my_custom_field" value="' . esc_attr($value) . '" />';
}

Пример 2: Создание вкладок на странице настроек

Часто на странице настроек нужно организовать несколько вкладок с разными секциями и полями. В этом случае можно использовать условные выражения для вывода полей для разных вкладок.

<?php
add_action('admin_menu', 'custom_settings_page_with_tabs');

function custom_settings_page_with_tabs() {
    add_options_page(
        __('Настройки с вкладками', 'textdomain'), 
        __('Вкладки', 'textdomain'), 
        'manage_options', 
        'tabs_settings', 
        'tabs_settings_page_callback'
    );
}

function tabs_settings_page_callback() {
    $active_tab = isset($_GET['tab']) ? $_GET['tab'] : 'general';
    ?>
    <div class="wrap">
        <h1><?php _e('Настройки с вкладками', 'textdomain'); ?></h1>
        <h2 class="nav-tab-wrapper">
            <a href="?page=tabs_settings&tab=general" class="nav-tab <?php echo $active_tab == 'general' ? 'nav-tab-active' : ''; ?>"><?php _e('Общие настройки', 'textdomain'); ?></a>
            <a href="?page=tabs_settings&tab=advanced" class="nav-tab <?php echo $active_tab == 'advanced' ? 'nav-tab-active' : ''; ?>"><?php _e('Продвинутые настройки', 'textdomain'); ?></a>
        </h2>
        <form action="options.php" method="POST">
            <?php
            if ($active_tab == 'general') {
                settings_fields('general_options_group');
                do_settings_fields('tabs_settings', 'general_section');
            } else {
                settings_fields('advanced_options_group');
                do_settings_fields('tabs_settings', 'advanced_section');
            }
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

add_action('admin_init', 'tabs_settings_init');

function tabs_settings_init() {
    // Общие настройки
    add_settings_section(
        'general_section', 
        __('Общие настройки', 'textdomain'), 
        'general_section_callback', 
        'tabs_settings'
    );
    
    add_settings_field(
        'general_option', 
        __('Опция 1', 'textdomain'), 
        'general_option_callback', 
        'tabs_settings', 
        'general_section'
    );
    
    register_setting('general_options_group', 'general_option');

    // Продвинутые настройки
    add_settings_section(
        'advanced_section', 
        __('Продвинутые настройки', 'textdomain'), 
        'advanced_section_callback', 
        'tabs_settings'
    );
    
    add_settings_field(
        'advanced_option', 
        __('Опция 2', 'textdomain'), 
        'advanced_option_callback', 
        'tabs_settings', 
        'advanced_section'
    );
    
    register_setting('advanced_options_group', 'advanced_option');
}

function general_section_callback() {
    echo '<p>' . __('Описание для общих настроек.', 'textdomain') . '</p>';
}

function general_option_callback() {
    $value = get_option('general_option', '');
    echo '<input type="text" name="general_option" value="' . esc_attr($value) . '" />';
}

function advanced_section_callback() {
    echo '<p>' . __('Описание для продвинутых настроек.', 'textdomain') . '</p>';
}

function advanced_option_callback() {
    $value = get_option('advanced_option', '');
    echo '<input type="text" name="advanced_option" value="' . esc_attr($value) . '" />';
}

Заключение

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