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

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

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

Иногда стандартных настроек темы или плагина недостаточно. Например, вы хотите дать пользователю возможность выбирать цветовую схему, указывать API-ключи или настраивать поведение функционала. Создание пользовательских настроек решает эти задачи и повышает гибкость вашего решения.

Также это улучшает UX: пользователь управляет параметрами через привычный интерфейс админки, а не меняет файлы вручную.

Прежде чем углубляться в код, отметим, что WordPress предлагает API для создания настроек — Settings API. Это мощный инструмент, который упрощает работу с формами и сохранением данных.

Создание страницы настроек в админке — базовый пример

Для начала создадим новую страницу в меню админки и разместим на ней форму с настройками.

Добавляем страницу настроек

В файле плагина или functions.php темы подключим функцию, которая создаст страницу:

function wpexamples_add_admin_menu() {
    add_menu_page(
        'Настройки WPExamples', // Заголовок страницы
        'WPExamples Настройки', // Название в меню
        'manage_options',        // Возможность доступа
        'wpexamples_settings',  // Уникальный слаг страницы
        'wpexamples_settings_page', // Функция вывода контента
        'dashicons-admin-generic', // Иконка
        80 // Позиция в меню
    );
}
add_action('admin_menu', 'wpexamples_add_admin_menu');

Эта функция добавит новый пункт меню «WPExamples Настройки» в админку.

Выводим содержимое страницы

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

function wpexamples_settings_page() {
    ?>
    <div class="wrap">
        <h1>Настройки WPExamples</h1>
        <form action="options.php" method="post">
            <?php
            settings_fields('wpexamples_options_group');
            do_settings_sections('wpexamples_settings');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

Здесь мы используем стандартные функции WordPress, которые выводят поля безопасности и секции формы.

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

Далее нужно зарегистрировать настройки, секции и поля, чтобы WordPress знал, как их обрабатывать.

Для этого используем хук admin_init:

function wpexamples_settings_init() {
    // Регистрируем опцию
    register_setting('wpexamples_options_group', 'wpexamples_options');

    // Добавляем секцию
    add_settings_section(
        'wpexamples_section',
        'Основные настройки',
        'wpexamples_section_callback',
        'wpexamples_settings'
    );

    // Добавляем поле: текстовое поле
    add_settings_field(
        'wpexamples_text_field',
        'Текстовое поле',
        'wpexamples_text_field_render',
        'wpexamples_settings',
        'wpexamples_section'
    );

    // Добавим чекбокс
    add_settings_field(
        'wpexamples_checkbox',
        'Включить опцию',
        'wpexamples_checkbox_render',
        'wpexamples_settings',
        'wpexamples_section'
    );
}
add_action('admin_init', 'wpexamples_settings_init');

Функции вывода полей

Теперь добавим функции, которые выводят HTML для каждого поля:

function wpexamples_text_field_render() {
    $options = get_option('wpexamples_options');
    ?>
    <input type="text" name="wpexamples_options[wpexamples_text_field]" value="<?php echo isset($options['wpexamples_text_field']) ? esc_attr($options['wpexamples_text_field']) : ''; ?>" />
    <?php
}

function wpexamples_checkbox_render() {
    $options = get_option('wpexamples_options');
    ?>
    <input type="checkbox" name="wpexamples_options[wpexamples_checkbox]" <?php checked(isset($options['wpexamples_checkbox']) ? $options['wpexamples_checkbox'] : 0, 1); ?> value="1" />
    <?php
}

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

Как правильно сохранять и использовать настройки

При сохранении WordPress автоматически обрабатывает данные, которые приходят из формы, если вы используете register_setting. Но важно валидировать и фильтровать входящие данные, чтобы избежать ошибок и уязвимостей.

Добавим функцию валидации для наших опций:

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

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

    $output['wpexamples_checkbox'] = isset($input['wpexamples_checkbox']) && $input['wpexamples_checkbox'] == 1 ? 1 : 0;

    return $output;
}
register_setting('wpexamples_options_group', 'wpexamples_options', 'wpexamples_options_validate');

Теперь наши данные безопасно сохраняются, а пользовательский ввод фильтруется.

Чтобы использовать сохранённые настройки в коде темы или плагина, можно обращаться к ним так:

$options = get_option('wpexamples_options');
$my_text = isset($options['wpexamples_text_field']) ? $options['wpexamples_text_field'] : '';
$my_checkbox = isset($options['wpexamples_checkbox']) ? $options['wpexamples_checkbox'] : 0;
// Используем переменные по назначению
if ($my_checkbox) {
    echo 'Опция включена';
}

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

Если не хочется писать настройки с нуля, можно воспользоваться готовыми плагинами. Вот несколько популярных вариантов:

• Advanced Custom Fields (ACF) — позволяет создавать поля для постов, но и для опций тоже.
• CMB2 — мощный фреймворк для создания метабоксов и страниц настроек.
• OptionTree — удобный интерфейс для создания страниц настроек с множеством типов полей.

Все они имеют документацию и примеры, но знание базового Settings API поможет вам лучше понимать, как они работают под капотом.

Советы и лучшие практики

При создании настроек в админке важно следовать нескольким правилам:

• Используйте префиксы в названиях функций и опций, чтобы избежать конфликтов с другими плагинами.
• Обязательно фильтруйте и валидируйте пользовательский ввод.
• Делайте интерфейс понятным и удобным для пользователя.
• Используйте стандартные функции WordPress для безопасности — settings_fields, do_settings_sections, submit_button.
• Тестируйте на разных уровнях доступа, чтобы не допустить ошибок у пользователей с ограниченными правами.

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