Как создать собственную настройку для темы WordPress в админке

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

Что такое Settings API и зачем он нужен

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

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

Создание страницы настроек темы — пошаговое руководство

Регистрация страницы настроек в меню

Первый шаг — добавить новую страницу в меню админки. Для этого используем хук admin_menu и функцию add_theme_page(). Ниже пример кода, который добавляет страницу в раздел «Внешний вид»:

function wpsource_add_theme_settings_page() {
    add_theme_page(
        'Настройки темы WPSource',
        'WPSource Настройки',
        'edit_theme_options',
        'wpsource_theme_settings',
        'wpsource_render_theme_settings_page'
    );
}
add_action('admin_menu', 'wpsource_add_theme_settings_page');

Параметры функции понятны: заголовок страницы, название в меню, уровень доступа, slug страницы и функция вывода содержимого.

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

Создадим функцию wpsource_render_theme_settings_page(), которая будет выводить форму настроек. Но прежде зарегистрируем настройки через хук admin_init:

function wpsource_settings_init() {
    // Регистрируем опцию
    register_setting('wpsource_theme_options_group', 'wpsource_theme_options', 'wpsource_sanitize_options');

    // Добавляем секцию
    add_settings_section(
        'wpsource_section_general',
        'Общие настройки',
        'wpsource_section_general_cb',
        'wpsource_theme_settings'
    );

    // Добавляем поле для ввода текста
    add_settings_field(
        'wpsource_field_text',
        'Текст приветствия',
        'wpsource_field_text_cb',
        'wpsource_theme_settings',
        'wpsource_section_general'
    );
}
add_action('admin_init', 'wpsource_settings_init');

Здесь мы регистрируем группу настроек, добавляем секцию и поле ввода. Обратите внимание на функцию очистки данных wpsource_sanitize_options — она нужна для безопасности.

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

Эти функции выводят описание секции и поле ввода на странице настроек.

function wpsource_section_general_cb() {
    echo '<p>Настройки, влияющие на общий вид темы.</p>';
}

function wpsource_field_text_cb() {
    $options = get_option('wpsource_theme_options');
    $text = isset($options['welcome_text']) ? esc_attr($options['welcome_text']) : '';
    echo "<input type='text' name='wpsource_theme_options[welcome_text]' value='$text' style='width: 300px;' />";
}

Функция очистки данных

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

function wpsource_sanitize_options($input) {
    $output = array();
    if (isset($input['welcome_text'])) {
        $output['welcome_text'] = sanitize_text_field($input['welcome_text']);
    }
    return $output;
}

Функция вывода страницы настроек

Теперь можно вывести форму с помощью стандартных функций WordPress:

function wpsource_render_theme_settings_page() {
    ?>
    <div class="wrap">
        <h1>Настройки темы WPSource</h1>
        <form method="post" action="options.php">
            <?php
            settings_fields('wpsource_theme_options_group');
            do_settings_sections('wpsource_theme_settings');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

Расширение настроек — добавляем чекбоксы и селект

Настройки не обязательно ограничивать одним полем. Добавим несколько разных типов полей для примера.

Добавление чекбокса

В функции wpsource_settings_init добавим поле:

add_settings_field(
    'wpsource_field_show_header',
    'Показывать заголовок',
    'wpsource_field_show_header_cb',
    'wpsource_theme_settings',
    'wpsource_section_general'
);

И функцию обратного вызова для чекбокса:

function wpsource_field_show_header_cb() {
    $options = get_option('wpsource_theme_options');
    $checked = isset($options['show_header']) ? checked(1, $options['show_header'], false) : '';
    echo "<input type='checkbox' name='wpsource_theme_options[show_header]' value='1' $checked />";
}

Добавление селекта

Для выбора цвета темы добавим селект:

add_settings_field(
    'wpsource_field_color_scheme',
    'Цветовая схема',
    'wpsource_field_color_scheme_cb',
    'wpsource_theme_settings',
    'wpsource_section_general'
);

function wpsource_field_color_scheme_cb() {
    $options = get_option('wpsource_theme_options');
    $value = isset($options['color_scheme']) ? $options['color_scheme'] : '';
    $colors = array(
        'light' => 'Светлая',
        'dark' => 'Тёмная',
        'blue' => 'Синяя',
    );
    echo "<select name='wpsource_theme_options[color_scheme]'>";
    foreach ($colors as $key => $label) {
        $selected = selected($value, $key, false);
        echo "<option value='$key' $selected>$label</option>";
    }
    echo "</select>";
}

Обновляем функцию очистки данных

Добавим обработку новых полей:

function wpsource_sanitize_options($input) {
    $output = array();
    if (isset($input['welcome_text'])) {
        $output['welcome_text'] = sanitize_text_field($input['welcome_text']);
    }
    $output['show_header'] = isset($input['show_header']) && $input['show_header'] == 1 ? 1 : 0;
    $valid_colors = array('light', 'dark', 'blue');
    if (isset($input['color_scheme']) && in_array($input['color_scheme'], $valid_colors)) {
        $output['color_scheme'] = $input['color_scheme'];
    } else {
        $output['color_scheme'] = 'light';
    }
    return $output;
}

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

После сохранения настроек можно использовать их в файлах темы. Например, чтобы вывести приветственный текст в header.php:

$options = get_option('wpsource_theme_options');
if (!empty($options['show_header']) && $options['show_header'] == 1) {
    echo '<h1>' . esc_html($options['welcome_text']) . '</h1>';
}

Также можно менять стили в зависимости от выбранной цветовой схемы:

$color_scheme = !empty($options['color_scheme']) ? $options['color_scheme'] : 'light';
// Подключаем соответствующий CSS файл
wp_enqueue_style('wpsource-theme-style', get_template_directory_uri() . "/css/style-" . $color_scheme . ".css");

Лучшие плагины для расширения настроек темы

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

• Advanced Custom Fields (ACF) — позволяет создавать поля и интерфейс для управления ими, подходит не только для постов, но и для опций темы.
• Customizer API — встроенный в WordPress инструмент для создания настроек с живым предпросмотром. Можно расширить его, добавляя кастомные секции.
• Redux Framework — мощный фреймворк для создания панелей опций в админке с множеством готовых компонентов.

Использование плагинов удобно для быстрой реализации, но для легкости и безопасности лучше писать собственный код, как описано выше.

Безопасность и рекомендации при работе с настройками

Обязательно используйте функции очистки и валидации данных, чтобы избежать внедрения вредоносного кода. Никогда не выводите данные пользователя без предварительной обработки, используйте esc_html(), esc_attr() и другие функции WordPress для экранирования.

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

Регулярно тестируйте совместимость с новыми версиями WordPress и обновляйте код при необходимости.