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

В этой статье подробно разберём, как добавить настройки вашего плагина в панель настройки темы WordPress — Customizer. Это современный и удобный способ предоставить пользователям возможность менять параметры плагина с визуальным контролем и моментальным предпросмотром изменений.

Что такое WordPress Customizer и зачем он нужен для плагина

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

Преимущества использования Customizer для настроек плагина:

• Интуитивный интерфейс с живым предпросмотром изменений.
• Единое место для настройки темы и плагинов.
• Возможность добавлять разные типы полей: текст, цвет, выбор, переключатели, загрузка файлов и другие.

Для реализации этого нужно использовать API Customizer через хук customize_register.

Создание базовых настроек плагина в Customizer

Начнём с простого примера, где создадим секцию настроек плагина с полем для ввода текста и переключателем.

function wpgen_customize_register( $wp_customize ) {
    // Добавляем секцию для нашего плагина
    $wp_customize->add_section( 'wpgen_plugin_section', array(
        'title'    => 'Настройки плагина WPGen',
        'priority' => 30,
    ) );

    // Добавляем настройку для текстового поля
    $wp_customize->add_setting( 'wpgen_text_setting', array(
        'default'           => '',
        'sanitize_callback' => 'sanitize_text_field',
    ) );

    // Добавляем контрол для текстового поля
    $wp_customize->add_control( 'wpgen_text_control', array(
        'label'    => 'Текстовое поле',
        'section'  => 'wpgen_plugin_section',
        'settings' => 'wpgen_text_setting',
        'type'     => 'text',
    ) );

    // Добавляем настройку для переключателя
    $wp_customize->add_setting( 'wpgen_checkbox_setting', array(
        'default'           => false,
        'sanitize_callback' => 'wp_validate_boolean',
    ) );

    // Добавляем контрол для переключателя
    $wp_customize->add_control( 'wpgen_checkbox_control', array(
        'label'    => 'Включить функцию',
        'section'  => 'wpgen_plugin_section',
        'settings' => 'wpgen_checkbox_setting',
        'type'     => 'checkbox',
    ) );
}
add_action( 'customize_register', 'wpgen_customize_register' );

В этом примере мы создаём новую секцию с двумя настройками: текстовое поле и чекбокс. Обратите внимание на использование функций очистки данных (sanitize_text_field и wp_validate_boolean), чтобы защитить сайт от некорректных данных.

Вывод значений настроек в коде плагина

Чтобы использовать эти настройки в вашем плагине, достаточно получить их через функцию get_theme_mod:

$text_value = get_theme_mod( 'wpgen_text_setting', '' );
$checkbox_enabled = get_theme_mod( 'wpgen_checkbox_setting', false );

Например, можно условно подключать функционал в зависимости от значения чекбокса или выводить текст из настройки.

Добавление дополнительных типов настроек: цвет, выбор, загрузка файлов

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

Цветовой выбор

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

// Добавляем контрол цвета
$wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'wpgen_color_control', array(
    'label'    => 'Выбор цвета',
    'section'  => 'wpgen_plugin_section',
    'settings' => 'wpgen_color_setting',
) ) );

Выбор из списка (select)

// Настройка селекта
$wp_customize->add_setting( 'wpgen_select_setting', array(
    'default'           => 'option1',
    'sanitize_callback' => 'wpgen_sanitize_select',
) );

// Контрол селекта
$wp_customize->add_control( 'wpgen_select_control', array(
    'label'    => 'Выберите опцию',
    'section'  => 'wpgen_plugin_section',
    'settings' => 'wpgen_select_setting',
    'type'     => 'select',
    'choices'  => array(
        'option1' => 'Опция 1',
        'option2' => 'Опция 2',
        'option3' => 'Опция 3',
    ),
) );

// Функция санитизации для селекта
function wpgen_sanitize_select( $input, $setting ) {
    $choices = $setting->manager->get_control( $setting->id )->choices;
    if ( array_key_exists( $input, $choices ) ) {
        return $input;
    } else {
        return $setting->default;
    }
}

Загрузка файлов

// Настройка загрузки файла
$wp_customize->add_setting( 'wpgen_file_setting', array(
    'default'           => '',
    'sanitize_callback' => 'esc_url_raw',
) );

// Контрол загрузки файла
$wp_customize->add_control( new WP_Customize_Upload_Control( $wp_customize, 'wpgen_file_control', array(
    'label'    => 'Загрузите файл',
    'section'  => 'wpgen_plugin_section',
    'settings' => 'wpgen_file_setting',
) ) );

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

Практические советы по интеграции Customizer в плагин

Чтобы сделать настройки плагина удобными и надёжными, учтите следующие моменты:

• Используйте префиксы для всех ID настроек и функций, чтобы избежать конфликтов (например, wpgen_).
• Обязательно фильтруйте и проверяйте данные через санитайзеры, особенно если значения используются в выводе или запросах к базе.
• Добавляйте описание к настройкам для понятности пользователя.
• Для сложных настроек можно создавать свои контролы, расширяя WP_Customize_Control.
• Тестируйте совместимость с темами и другими плагинами, особенно если используете кастомные стили или скрипты в Customizer.

Пример подключения настроек Customizer в плагине WPGen

Допустим, у вас плагин, который выводит баннер с настраиваемым текстом и цветом. Добавим в Customizer настройку текста баннера и цвет фона:

function wpgen_customize_register( $wp_customize ) {
    $wp_customize->add_section( 'wpgen_banner_section', array(
        'title'    => 'Настройки баннера WPGen',
        'priority' => 31,
    ) );

    $wp_customize->add_setting( 'wpgen_banner_text', array(
        'default'           => 'Добро пожаловать на сайт!',
        'sanitize_callback' => 'sanitize_text_field',
    ) );

    $wp_customize->add_control( 'wpgen_banner_text_control', array(
        'label'    => 'Текст баннера',
        'section'  => 'wpgen_banner_section',
        'settings' => 'wpgen_banner_text',
        'type'     => 'text',
    ) );

    $wp_customize->add_setting( 'wpgen_banner_bg_color', array(
        'default'           => '#ff0000',
        'sanitize_callback' => 'sanitize_hex_color',
    ) );

    $wp_customize->add_control( new WP_Customize_Color_Control( $wp_customize, 'wpgen_banner_bg_color_control', array(
        'label'    => 'Цвет фона баннера',
        'section'  => 'wpgen_banner_section',
        'settings' => 'wpgen_banner_bg_color',
    ) ) );
}
add_action( 'customize_register', 'wpgen_customize_register' );

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

function wpgen_display_banner() {
    $text = get_theme_mod( 'wpgen_banner_text', 'Добро пожаловать на сайт!' );
    $bg_color = get_theme_mod( 'wpgen_banner_bg_color', '#ff0000' );
    echo '<div style="background-color:' . esc_attr( $bg_color ) . '; padding: 15px; color: #fff; text-align: center;">' . esc_html( $text ) . '</div>';
}

Добавьте вызов wpgen_display_banner() в нужном месте темы или плагина — и у вас есть настраиваемый баннер с изменяемым текстом и цветом фона.

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

Для расширения функционала и удобства создания настроек можно использовать плагины из каталога WPSHOP. Например:

• Clearfy Pro — для оптимизации и управления параметрами производительности.
• Expert Review — если нужно настроить параметры отзывов с визуальной настройкой.
• ABC Pagination — если плагин выводит постраничную навигацию с настройками.

Эти расширения могут быть интегрированы с Customizer для удобства управления прямо в интерфейсе сайта.

Итоги

WPGen рекомендует использовать Customizer для создания настроек плагина — это современный и удобный способ взаимодействия с пользователями. Благодаря API Customizer вы можете создавать любые типы настроек с живым предпросмотром, улучшая UX вашего плагина и снижая количество обращений в поддержку.

Используйте префиксы, тщательно фильтруйте данные и тестируйте на разных темах. А если хотите расширить функционал, посмотрите плагины из WPSHOP.