В WordPress начиная с версии 3.4 появился очень полезная штука под названием Theme Customization API. Данный интерфейс дает возможность разработчикам создавать дополнительные настройки темы, а пользователям менять эти настройки в реальном времени. В этой статье я поделюсь своим опытом работы с кастомайзером WordPress.
Содержание
- 1. Стандартное использование Кастомайзера WordPress.
- 2. Использование Кастомайзера на основе класса SP Customizer.
1. Стандартное использование Кастомайзера WordPress
Итак начнем. В админке, кастомайзер находится в разделе меню внешний вид -> настроить.
Здесь находятся стандартные настройки темы.
Давайте попробуем их расширить. Код кастомайзера, как правило находится в папке inc/customizer.php, а работа с ним осуществляется через хук customize_register
Создадим функцию test_customizer_addition и посмотрим что получилось. Данную функцию нужно добавить в файл customizer.php вашей темы.
function test_customizer_addition($wp_customize) {
//section
$wp_customize->add_section('test_section' , array(
'title' => 'Test Section',
'priority' => 99,
));
//text field
$wp_customize->add_setting('test_str', array(
'capability' => 'edit_theme_options',
'default' => '',
'sanitize_callback' => 'sanitize_text_field',
));
$wp_customize->add_control('test_str', array(
'type' => 'input',
'section' => 'test_section',
'label' => 'String',
));
}
add_action('customize_register', 'test_customizer_addition');
Здесь мы создали секцию test_section с помощью метода $wp_customize->add_section и текстовое поле используя методы $wp_customize->add_setting и $wp_customize->add_control.
$wp_customize->add_section - добавляет секцию. Используется группировки настроек и элементов управления.
$wp_customize->add_setting() - добавляет настройку. Используется для предпросмотра изменений, очистки и сохранения.
$wp_customize->add_control() - добавляет элемент управления. Используется для вывода элементов управления.
Важный момент, элемент управления не может существовать без секции.
Давайте теперь создадим что-нибудь посложнее. Расширим нашу функцию.
function test_customizer_addition($wp_customize) {
//section
$wp_customize->add_section('test_section' , array(
'title' => 'Test Section',
'priority' => 99,
));
//string field
$wp_customize->add_setting('test_str', array(
'capability' => 'edit_theme_options',
'default' => '',
'sanitize_callback' => 'sanitize_text_field',
));
$wp_customize->add_control('test_str', array(
'type' => 'input',
'section' => 'test_section',
'label' => 'String',
));
//number field
$wp_customize->add_setting('test_number', array(
'capability' => 'edit_theme_options',
'default' => '',
'sanitize_callback' => 'sp_sanitize_number',
));
$wp_customize->add_control('test_number', array(
'type' => 'number',
'section' => 'test_section',
'label' => 'Number',
));
//checkbox
$wp_customize->add_setting('test_checkbox', array(
'capability' => 'edit_theme_options',
'default' => '',
'sanitize_callback' => 'sp_sanitize_checkbox',
));
$wp_customize->add_control('test_checkbox', array(
'settings' => 'test_checkbox',
'label' => 'checkbox',
'section' => 'test_section',
'type' => 'checkbox',
));
//textarea
$wp_customize->add_setting('text_textarea', array(
'capability' => 'edit_theme_options',
'default' => '',
'sanitize_callback' => 'sp_sanitize_textarea',
));
$wp_customize->add_control('text_textarea', array(
'type' => 'textarea',
'section' => 'test_section',
'label' => 'Textarea',
));
//image
$wp_customize->add_setting('test_img', array(
'capability' => 'edit_theme_options',
'sanitize_callback' => 'esc_url_raw',
'default' => '',
));
$wp_customize->add_control( new WP_Customize_Image_Control($wp_customize, 'test_img', array(
'label' => 'Image',
'section' => 'test_section',
'settings' => 'test_img',
)));
}
add_action('customize_register', 'test_customizer_addition');
//sanitize checkbox
function sp_sanitize_checkbox($input) {
if ($input == 1) return 1;
else return '';
}
//sanitize textarea
function sp_sanitize_textarea($input){
return wp_kses_post($input);
}
function sp_sanitize_number($input){
return intval($input);
}
Мы создали числовое поле('type' => 'number'), чекбокс('type' => 'checkbox'), текстовое поле('type' => 'textarea') и изображение (WP_Customize_Image_Control).
Данного набора полей настроек достаточно что бы кастомизировать шаблон WordPress.
Так же стоит обратить внимание на параметр sanitize_callback. С его помощью мы вызываем функцию для очистки данных в зависимости от их типа.
Для строки - sanitize_text_field;
Для числа - sp_sanitize_number;
Для текста - sp_sanitize_textarea;
Для чекбокса - sp_sanitize_checkbox;
Для изображения - esc_url_raw;
Для вывода значений настройки используется функция get_theme_mod().
Пример:
echo get_theme_mod('test_str');
2. Использование Кастомайзера на основе класса SP_Customizer.
Теперь давайте подключим класс SP_Customizer в файл functions.php. Я его расположил в папке inc своего шаблона.
require get_template_directory() . '/inc/class-sp-customizer.php';
Код примера который я показывал выше нужно закомментировать, и наш новый код будет таким:
$spCC = new SP_Customizer(); $args = array( 'name' => 'SP_Customizer', 'priority' => 99, 'title' => 'SP Customizer', 'description' => 'testing', 'section' => array( 'test_section1' => array( 'name' => 'test_section', 'title' => 'Test Section', 'fields' => array( '0' => array( 'name' => 'test_str', 'type' => 'input', 'label' => 'String', 'sanitize' => 'y', ), '1' => array( 'name' => 'test_number', 'type' => 'number', 'label' => 'Number', 'sanitize' => 'y', ), '2' => array( 'name' => 'test_checkbox', 'type' => 'checkbox', 'label' => 'Checkbox', 'sanitize' => 'y', ), '3' => array( 'name' => 'test_textarea', 'type' => 'textarea', 'label' => 'Textarea', 'sanitize' => 'y', ), '4' => array( 'name' => 'test_img', 'type' => 'image', 'label' => 'Image', 'sanitize' => 'y', ), ), ), ), ); $spCC->sp_create_customizer($args);
Здесь мы передаем методу sp_create_customizer() многомерный массив $args с параметрами.
section - Секция. Содержит в себе элементы управления (fields).
name - уникальное имя секции
title - название секции.
Если нужно создать еще одну секцию, то добавляем элемент массива с индексом к примеру test_section2 и перечисляем нужные элементы управления(fields).
В fields содержатся элементы управления:
name - уникальное имя;
type - тип;
label - название;
sanitize - очистка данных (y/n);
Скачать class-sp-customizer.php можно тут.
Автор публикации
Привет Саш, спасибо за статью. Можно несколько замечаний?
Ты под номером 1 говоришь о ВП функции кастомайзера "Стандартное использование Кастомайзера WordPress." без использования класса своего, но ниже тут же пишешь для очистки функции
sp_sanitize_numberи другие с префиксомsp(и в примере тоже). Они у пользователя фатальную ошибку выведут. т.к. их нет. Потому как начало руководства по ВП кастомайзеру.Подключение класса лучше делать через проверку is_customize_preview() - то есть класс не будет в холостую загружаться всегда, а только когда мы в кастомайзере
'sanitize' => 'y'нет. Лучше просто 1 или 0 значение. Ведь по сути - булево (очищать или нет) и в классе сразу можешь определить действие - например очищать - тогда и указывать это не нужно будет. т.к. по безопасности очищать всегда нужно.И в кастомайзере еще есть js часть. Тут ты её не затрагивал?
Видео я не смотрел - увы нет столько времени. Но если текст по видео - то больше замечаний нет ))
Привет! Пожалуйста))
sp_sanitize_number надо добавить к себе в код.
'sanitize' => 'y' - приму к сведению. Можно сделать 'true/false', так приколнее будет
А js часть я не затрагивал.
is_customize_preview() а вот это хорошая идейка, спасибо, чето я не подумал)
- я бы поспорил. 1 и 0 более явно. Но не строкой, а числом
'sanitize' => 0p.s. недавно в каментах ВК проскочила такая мысль что кастомайзер и ВП виджеты - всё это рудименты. Потому как редактор блоков ВП 5.0 их медленно, но верно, отодвигает. Конечно они пока не предлагают php замену и просят всё это писать на js (чтоб мы не занимались ерундой и були fullstack - они по миру ценней всего для независимой команды). Но у того же ACF - есть обертка - на вход php, на выходе нужный js для всей кухни современного вордпресса. Думаю со временем появится php обертка и в ВП для гутенберга.
Согласен за гутенбергом будущее.)