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

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

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

Настройки темы позволяют сделать шаблон универсальным и удобным для конечных пользователей. Вместо того, чтобы менять PHP-код или CSS, пользователи смогут управлять цветами, шрифтами, логотипом, контактной информацией и другими параметрами через привычный интерфейс.

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

Для реализации настроек можно использовать встроенный в WordPress API — Customizer API, который позволяет создавать интерактивные панели настроек с превью.

Основы работы с Customizer API в WordPress

Customizer API — это набор функций, который позволяет добавлять секции, настройки и контролы в панель «Внешний вид > Настроить». Это современный и удобный способ создавать настройки темы.

Основные понятия:

setting — хранит значение настройки в базе данных;
control — элемент интерфейса для выбора или ввода значения (текстовое поле, цвет, чекбокс и т.д.);
section — логическая группа контролов в панели.

Для добавления настроек нужно использовать хук customize_register и объект $wp_customize.

Пример добавления простой настройки цвета фона

Рассмотрим пример, как добавить цвет фона сайта, который пользователь сможет выбирать в настройках темы.

function wphelper_customize_register( $wp_customize ) {
    // Добавляем секцию
    $wp_customize->add_section( 'wphelper_colors_section', array(
        'title'    => 'Цвета сайта',
        'priority' => 30,
    ) );

    // Добавляем настройку
    $wp_customize->add_setting( 'wphelper_background_color', array(
        'default'           => '#ffffff',
        'sanitize_callback' => 'sanitize_hex_color',
        'transport'         => 'refresh',
    ) );

    // Добавляем контрол для настройки
    $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'wphelper_background_color_control', array(
        'label'    => 'Цвет фона сайта',
        'section'  => 'wphelper_colors_section',
        'settings' => 'wphelper_background_color',
    ) ) );
}
add_action( 'customize_register', 'wphelper_customize_register' );

В этом коде мы создали новую секцию с названием «Цвета сайта», добавили настройку wphelper_background_color с дефолтным значением белого (#ffffff) и контрол выбора цвета.

Вывод выбранного цвета в шаблоне

Чтобы применить выбранный цвет, добавим вывод стиля в header.php или в отдельный файл стилей, подключаемый динамически:

function wphelper_customizer_css() {
    $background_color = get_theme_mod( 'wphelper_background_color', '#ffffff' );
    ?>
    <style type="text/css">
        body {
            background-color: <?php echo esc_attr( $background_color ); ?>;
        }
    </style>
    <?php
}
add_action( 'wp_head', 'wphelper_customizer_css' );

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

Добавление различных типов настроек и контролов

Customizer API поддерживает множество контролов: текстовые поля, чекбоксы, выпадающие списки, радио-кнопки, загрузка изображений и даже кастомные контроли.

Рассмотрим несколько примеров.

Текстовое поле для контактного телефона

function wphelper_customize_register_phone( $wp_customize ) {
    $wp_customize->add_section( 'wphelper_contact_section', array(
        'title'    => 'Контактные данные',
        'priority' => 35,
    ) );

    $wp_customize->add_setting( 'wphelper_contact_phone', array(
        'default'           => '',
        'sanitize_callback' => 'sanitize_text_field',
    ) );

    $wp_customize->add_control( 'wphelper_contact_phone_control', array(
        'label'    => 'Телефон для связи',
        'section'  => 'wphelper_contact_section',
        'settings' => 'wphelper_contact_phone',
        'type'     => 'text',
    ) );
}
add_action( 'customize_register', 'wphelper_customize_register_phone' );

Для вывода телефона в шаблоне используйте:

echo esc_html( get_theme_mod( 'wphelper_contact_phone', '' ) );

Загрузка логотипа через Customizer

Для загрузки изображения в настройках используйте WP_Customize_Image_Control. Пример:

function wphelper_customize_register_logo( $wp_customize ) {
    $wp_customize->add_section( 'wphelper_logo_section', array(
        'title'    => 'Логотип сайта',
        'priority' => 40,
    ) );

    $wp_customize->add_setting( 'wphelper_logo', array(
        'default'           => '',
        'sanitize_callback' => 'esc_url_raw',
    ) );

    $wp_customize->add_control( new WP_Customize_Image_Control( $wp_customize, 'wphelper_logo_control', array(
        'label'    => 'Загрузить логотип',
        'section'  => 'wphelper_logo_section',
        'settings' => 'wphelper_logo',
    ) ) );
}
add_action( 'customize_register', 'wphelper_customize_register_logo' );

В шаблоне вывести логотип можно так:

$logo_url = get_theme_mod( 'wphelper_logo' );
if ( $logo_url ) {
    echo '<img src="' . esc_url( $logo_url ) . '" alt="Логотип">';
} else {
    echo '<h1>' . get_bloginfo( 'name' ) . '</h1>';
}

Использование плагинов для расширения Customizer

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

Kirki — мощный фреймворк для создания кастомных настроек с большим набором контролов и удобным API.
Customizer Remove All Parts — позволяет скрывать стандартные секции и контролы Customizer для упрощения интерфейса.
Advanced Custom Fields (ACF) — с плагином ACF PRO можно создавать пользовательские поля и интегрировать их с Customizer.

Например, с Kirki вы можете добавить цвет фона так:

Kirki::add_section( 'wphelper_colors_section', array(
    'title'    => 'Цвета сайта',
    'priority' => 30,
) );

Kirki::add_field( 'theme_config_id', [
    'type'        => 'color',
    'settings'    => 'wphelper_background_color',
    'label'       => 'Цвет фона сайта',
    'section'     => 'wphelper_colors_section',
    'default'     => '#ffffff',
] );

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

При добавлении настроек важно правильно очищать и валидировать данные. Используйте sanitize_callback для настройки, чтобы избежать XSS-уязвимостей.

Также используйте функции esc_html(), esc_attr(), esc_url() при выводе значений в шаблоне.

Чтобы улучшить производительность, используйте transport => postMessage и JavaScript для живого обновления превью без перезагрузки страницы в Customizer.

Пример добавления постмесседж для цвета фона

function wphelper_customize_register_live( $wp_customize ) {
    $wp_customize->get_setting( 'wphelper_background_color' )->transport = 'postMessage';
}
add_action( 'customize_register', 'wphelper_customize_register_live' );

function wphelper_customize_preview_js() {
    wp_enqueue_script( 'wphelper_customizer', get_template_directory_uri() . '/js/customizer.js', array( 'customize-preview' ), '1.0', true );
}
add_action( 'customize_preview_init', 'wphelper_customize_preview_js' );

В файле customizer.js добавьте:

( function( $ ) {
    wp.customize( 'wphelper_background_color', function( value ) {
        value.bind( function( newval ) {
            $( 'body' ).css( 'background-color', newval );
        } );
    } );
} )( jQuery );

Это обеспечит мгновенное обновление цвета фона в превью Customizer без перезагрузки.

Заключение

Создание настроек темы через Customizer API — это мощный и современный способ сделать тему гибкой и удобной для пользователя. Внимательно подходите к валидации данных, используйте готовые решения, такие как Kirki, если хотите ускорить разработку. Не забывайте про live preview и безопасность.

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

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