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

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

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

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

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

Создаем страницу настроек в админке WordPress

Для начала создадим отдельную страницу в меню админки. Для этого используем хук admin_menu и функцию add_theme_page. Вот простой пример:

add_action('admin_menu', 'wpzen_add_theme_settings_page');
function wpzen_add_theme_settings_page() {
    add_theme_page(
        'Настройки темы WPZen', // Заголовок страницы
        'Настройки WPZen',       // Название в меню
        'manage_options',         // Права доступа
        'wpzen-theme-settings',  // slug страницы
        'wpzen_render_settings_page' // Функция вывода страницы
    );
}

Эта функция добавит пункт меню в разделе «Внешний вид» с названием «Настройки WPZen».

Вывод формы настроек и сохранение данных

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

Лучше использовать API настроек WordPress — Settings API. Это гарантирует корректное сохранение данных, защиту от CSRF и удобство.

function wpzen_render_settings_page() {
    ?>
    <div class="wrap">
        <h1>Настройки темы WPZen</h1>
        <form method="post" action="options.php">
            <?php
            settings_fields('wpzen_theme_options_group');
            do_settings_sections('wpzen-theme-settings');
            submit_button();
            ?>
        </form>
    </div>
    <?php
}

Теперь нам нужно зарегистрировать настройки, секции и поля. Это делается через хук admin_init:

add_action('admin_init', 'wpzen_register_theme_settings');
function wpzen_register_theme_settings() {
    register_setting('wpzen_theme_options_group', 'wpzen_theme_options', 'wpzen_sanitize_options');

    add_settings_section(
        'wpzen_main_section',
        'Основные настройки',
        'wpzen_main_section_cb',
        'wpzen-theme-settings'
    );

    add_settings_field(
        'wpzen_facebook_url',
        'URL Facebook',
        'wpzen_facebook_url_cb',
        'wpzen-theme-settings',
        'wpzen_main_section'
    );

    add_settings_field(
        'wpzen_custom_css',
        'Пользовательский CSS',
        'wpzen_custom_css_cb',
        'wpzen-theme-settings',
        'wpzen_main_section'
    );
}

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

function wpzen_facebook_url_cb() {
    $options = get_option('wpzen_theme_options');
    $value = isset($options['facebook_url']) ? esc_url($options['facebook_url']) : '';
    echo "<input type='url' name='wpzen_theme_options[facebook_url]' value='" . $value . "' class='regular-text' />";
}

function wpzen_custom_css_cb() {
    $options = get_option('wpzen_theme_options');
    $value = isset($options['custom_css']) ? esc_textarea($options['custom_css']) : '';
    echo "<textarea name='wpzen_theme_options[custom_css]' rows='10' cols='50' class='large-text code'>" . $value . "</textarea>";
}

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

    if (isset($input['facebook_url']) && filter_var($input['facebook_url'], FILTER_VALIDATE_URL)) {
        $output['facebook_url'] = esc_url_raw($input['facebook_url']);
    } else {
        add_settings_error('wpzen_theme_options', 'facebook_url_error', 'Введите корректный URL Facebook.');
    }

    if (isset($input['custom_css'])) {
        // Можно здесь добавить очистку CSS или оставить как есть
        $output['custom_css'] = wp_kses_post($input['custom_css']);
    }

    return $output;
}

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

Чтобы применить сохранённые настройки в шаблонах, вызовите get_option('wpzen_theme_options') и используйте значения:

$options = get_option('wpzen_theme_options');
if (!empty($options['facebook_url'])) {
    echo '<a href="' . esc_url($options['facebook_url']) . '" target="_blank" rel="nofollow">Facebook</a>';
}

if (!empty($options['custom_css'])) {
    echo '<style type="text/css">' . $options['custom_css'] . '</style>';
}

Это позволит динамически менять ссылки и стили без правки файлов темы.

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

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

• Redux Framework — мощный фреймворк для создания панелей опций с множеством готовых полей.
• CMB2 — легкая библиотека для метабоксов и пользовательских настроек.
• Clearfy Pro — оптимизационный плагин, который среди прочего позволяет управлять настройками сайта и убирает лишнее из админки.

Однако для специфичных задач часто достаточно и собственного решения, как описано выше.

Советы по безопасности и удобству

Не забывайте использовать функции санитизации и проверки данных при сохранении, чтобы избежать XSS и других уязвимостей. Всегда проверяйте права пользователя через current_user_can('manage_options').

Для улучшения UX рекомендуется добавлять подсказки, описания к полям и использовать стандартные CSS классы WordPress для единообразия интерфейса.

Также полезно реализовать возможность экспорта/импорта настроек, чтобы упростить миграцию между сайтами.