Как создать настройку в админ панели WordPress с примерами кода

В этой статье мы подробно разберём, как создать собственные настройки в административной панели WordPress, используя стандартный API настроек. Это очень полезный навык, если вы разрабатываете темы или плагины и хотите предоставить пользователю удобный интерфейс для управления параметрами.

Почему важно создавать собственные настройки в админ панели WordPress

Админ панель WordPress предоставляет множество встроенных возможностей для настройки, но для уникальных функций вашего проекта нередко требуется расширять её, добавляя собственные разделы и поля настроек. Это позволяет не только улучшить UX, но и обезопасить данные, так как WordPress автоматически обрабатывает сохранение и валидацию, если сделать всё правильно.

Кроме того, использование стандартного Settings API гарантирует совместимость с будущими версиями WordPress и упрощает поддержку вашего кода.

Основы Settings API: что нужно знать

Settings API — это набор функций и хуков, позволяющих создавать страницы настроек, секции и поля, а также обрабатывать их сохранение. Основные элементы:

• register_setting() — регистрирует новую настройку и её опции.
• add_settings_section() — добавляет секцию на страницу настроек для группировки полей.
• add_settings_field() — добавляет конкретное поле ввода в секцию.
• Функция вывода страницы с помощью add_options_page() или похожих.

Далее мы покажем, как использовать эти функции на практике.

Создание страницы настроек с примером кода WP8

Начнём с того, что добавим новую страницу настроек в меню «Настройки» админки:

add_action('admin_menu', 'wp8_add_settings_page');
function wp8_add_settings_page() {
    add_options_page(
        'Настройки WP8',
        'Настройки WP8',
        'manage_options',
        'wp8-settings',
        'wp8_render_settings_page'
    );
}

Теперь создадим функцию вывода страницы:

function wp8_render_settings_page() {
    ?>
    <div class="wrap">
        <h1>Настройки WP8</h1>
        <form action="options.php" method="post">
            <?php
            settings_fields('wp8_options_group');
            do_settings_sections('wp8-settings');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

Регистрация настроек, секций и полей

Для начала зарегистрируем настройку и добавим секцию с полями:

add_action('admin_init', 'wp8_register_settings');
function wp8_register_settings() {
    register_setting('wp8_options_group', 'wp8_options', 'wp8_sanitize_options');

    add_settings_section(
        'wp8_main_section',
        'Основные настройки',
        'wp8_main_section_callback',
        'wp8-settings'
    );

    add_settings_field(
        'wp8_text_field',
        'Текстовое поле',
        'wp8_text_field_callback',
        'wp8-settings',
        'wp8_main_section'
    );

    add_settings_field(
        'wp8_checkbox',
        'Флаг включения',
        'wp8_checkbox_callback',
        'wp8-settings',
        'wp8_main_section'
    );
}

Объясним подробнее:

• register_setting() — регистрирует группу опций и указывает функцию для валидации/очистки данных.
• add_settings_section() — создаёт секцию с заголовком и описанием.
• add_settings_field() — добавляет поля в секцию, указывая функцию вывода.

Функции обратного вызова для секций и полей

Функция вывода описания секции:

function wp8_main_section_callback() {
    echo '<p>Здесь можно настроить основные параметры плагина WP8.</p>';
}

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

function wp8_text_field_callback() {
    $options = get_option('wp8_options');
    $value = isset($options['text_field']) ? esc_attr($options['text_field']) : '';
    echo "<input type='text' name='wp8_options[text_field]' value='$value' class='regular-text' />";
}

Функция вывода чекбокса:

function wp8_checkbox_callback() {
    $options = get_option('wp8_options');
    $checked = !empty($options['checkbox']) ? 'checked' : '';
    echo "<input type='checkbox' name='wp8_options[checkbox]' value='1' $checked /> Включить опцию";
}

Обработка и валидация данных

Очень важно проверять данные перед сохранением. Ниже пример простой функции очистки:

function wp8_sanitize_options($input) {
    $output = array();

    if (isset($input['text_field'])) {
        $output['text_field'] = sanitize_text_field($input['text_field']);
    }

    $output['checkbox'] = !empty($input['checkbox']) ? 1 : 0;

    return $output;
}

Такая функция гарантирует, что в базе будут храниться только корректные данные, и предотвращает возможные XSS-уязвимости.

Расширение: добавление выпадающего списка и поля с числом

Для примера добавим ещё два поля — селект и числовое поле.

add_settings_field(
    'wp8_select_field',
    'Выбор варианта',
    'wp8_select_field_callback',
    'wp8-settings',
    'wp8_main_section'
);

add_settings_field(
    'wp8_number_field',
    'Числовое поле',
    'wp8_number_field_callback',
    'wp8-settings',
    'wp8_main_section'
);

function wp8_select_field_callback() {
    $options = get_option('wp8_options');
    $selected = isset($options['select_field']) ? $options['select_field'] : '';
    $choices = array('option1' => 'Вариант 1', 'option2' => 'Вариант 2', 'option3' => 'Вариант 3');

    echo "<select name='wp8_options[select_field]'>";
    foreach ($choices as $value => $label) {
        $sel = selected($selected, $value, false);
        echo "<option value='$value' $sel>$label</option>";
    }
    echo "</select>";
}

function wp8_number_field_callback() {
    $options = get_option('wp8_options');
    $value = isset($options['number_field']) ? intval($options['number_field']) : 0;
    echo "<input type='number' name='wp8_options[number_field]' value='$value' min='0' max='100' />";
}

Не забудьте расширить функцию валидации:

function wp8_sanitize_options($input) {
    $output = array();

    if (isset($input['text_field'])) {
        $output['text_field'] = sanitize_text_field($input['text_field']);
    }

    $output['checkbox'] = !empty($input['checkbox']) ? 1 : 0;

    $choices = array('option1', 'option2', 'option3');
    if (isset($input['select_field']) && in_array($input['select_field'], $choices)) {
        $output['select_field'] = $input['select_field'];
    } else {
        $output['select_field'] = 'option1';
    }

    $output['number_field'] = isset($input['number_field']) ? max(0, min(100, intval($input['number_field']))) : 0;

    return $output;
}

Использование созданных настроек в коде темы или плагина

Данные, сохранённые в опциях, можно получить с помощью get_option('wp8_options') и использовать в вашем функционале. Например, если нужна проверка флага:

$options = get_option('wp8_options');
if (!empty($options['checkbox'])) {
    // Выполнить действие, если опция включена
}

Или вывести текст из настройки:

echo esc_html($options['text_field']);

Популярные плагины для расширения настроек WordPress

Если нужна более быстрая реализация с визуальным редактором настроек, можно использовать плагины:

• Advanced Custom Fields (ACF) — удобный интерфейс для создания полей, включая настройки.
• OptionTree — мощный фреймворк для создания панелей настроек.
• Carbon Fields — современный PHP-фреймворк с удобным API.

Однако знание стандартного Settings API даёт больше контроля и гибкости.

Заключение к теме настройки админ панели WP8

Создание собственных настроек в админ панели WordPress — важный навык для любого разработчика тем и плагинов. Использование Settings API позволяет сделать это правильно и надёжно, обеспечивая удобный интерфейс и безопасное хранение данных. В этой статье мы рассмотрели полный цикл от добавления страницы до валидации и примеров полей. Используйте этот подход в своих проектах WP8 для повышения качества и удобства работы с вашим продуктом.