WordPress Customizer — подробный обзор API

Все больше премиум-тем для WordPress используют Customizer API для разных вещей. От изменения цветов всех видов блоков, до применения различных шрифтов и кастомного CSS. Что же такое Customizer API и нужно ли его использовать в каждом удобном случае? Попробуем разобраться.

#

Немного истории

Начиная с версии 3.4 в WordPress был включен Customizer, ссылка на него появилась в меню «Внешний вид» и в админ-баре (сверху). Стандартными настройками были: заголовки сайта, варианты главной страницы и возможность включить изменение фона (custom background) и изображения заголовка (custom header).

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

После этого туда добавили много всякого и сейчас мы имеем там настройки навигационных меню, виджетов. Со следующими релизами хотят добавить возможность менять темы. Поскольку WordPress Customizer — это backbone-приложение, работающее с WP REST API, его возможности почти безграничны.

Попробуем разобраться как же присоединиться к этом празднику жизни.

#

Экшены customize_register и customize_preview_init

Все действия, которые мы будем производить, вешаются на два экшена (action hook): customize_register и customize_preview_init. Сначала поговорим про первый, потому что с ним происходит вся основная магия.

customize_register

На этот экшен мы вешаем тот самый callback, который будет вносить изменения в глобальную переменную $wp_customize. Это PHP объект, который является экземпляром класса WP_Customize_Manager, у которого есть много любопытных методов по добавлению и изменению всякого:

• WP_Customize_Manager->add_setting() (добавить новую настройку) и WP_Customize_Manager->get_setting() (изменить аргументы уже существующей настройки).
• WP_Customize_Manager->add_control() (добавить новый HTML-элемент) и WP_Customize_Manager->get_control() (изменить аргументы уже существующего контрола). Каждый контрол должен быть привязан к конкретной настройке.
• WP_Customize_Manager->add_section() (добавить новую секцию, объединяющую несколько контролов) и WP_Customize_Manager->get_section() (изменить аргументы уже существующей секции).
• WP_Customize_Manager->add_panel() (добавить новую «панель», объединяющую несколько секций) и WP_Customize_Manager->get_panel() (изменить настройки уже существующей).

Давайте разберем аргументы каждого метода. Ниже приведены варианты дефолтных значений.

$wp_customize->add_setting( 'your_setting_id', array(
	//* Можно поменять с дефолтного значения (theme_mod) на option (о различиях между theme_mod и option).
	'type'              => 'theme_mod',
	//* Варианты Capabilities для того чтобы ограничить права настройки у пользователей.
	'capability'        => 'edit_theme_options',
	//* Можно добавить любой ID, чтобы потом включать в теме с помощью функции add_theme_support( 'theme_support_setting_id' ).
	'theme_supports'    => '',
	//* Дефолтное значение для этого поля.
	'default'           => '',
	//* Протокол изменения настройки в превью, подробнее остановлюсь на этом ниже.
	'transport'         => 'postMessage',
	//* Колбэк для валидации информации перед записью в БД, можно использовать встроенные, например esc_html и esc_url.
	'sanitize_callback' => '',
) );

//* здесь можно создавать экземпляр разных классов, в дефолтном виде это WP_Customize_Control, также есть: WP_Customize_Color_Control, WP_Customize_Upload_Control, WP_Customize_Image_Control, WP_Customize_Background_Image_Control, WP_Customize_Header_Image_Control
$wp_customize->add_control( new WP_Customize_Control( $wp_customize, 'your_setting_id', array(
	//* ID настройки, которую контролирует этот элемент.
	'settings'    => 'your_setting_id',
	//* Приоритет, можно менять для того чтобы переставлять контролы местами.
	'priority'    => 10,
	//* ID секции, в которую стоит поместить контрол.
	'section'     => '',
	//* Заголовок для элемента.
	'label'       => '',
	//* Дополнительное описание под заголовком.
	'description' => '',
	//* Тип элемента. Может быть нескольких вариантов: checkbox, radio, select, textarea, dropdown-pages.
	'type'        => 'text',
	//* Массив вариантов для radio и select типов.
	'choices'     => '',
) );

$wp_customize->add_section( 'your_section_id', array(
	//* Приоритет, можно менять для того чтобы переставлять панели местами.
	'priority'       => 160,
	//* Варианты Capabilities для того чтобы ограничить права настройки у пользователей.
	'capability'     => 'edit_theme_options',
	//* Можно добавить любой ID, чтобы потом включать в теме с помощью функции add_theme_support( 'theme_support_setting_id' ).
	'theme_supports' => '',
	//* Заголовок для панели.
	'title'          => '',
	//* Дополнительное описание под заголовком.
	'description'    => '',
	//* Тип панели. Можно добавить любое слово, оно отразится в классе для этой панели и примет вид control-panel-default при значении default.
	'type'           => 'default',
) );

$wp_customize->add_panel( 'your_section_id', array(
	//* Приоритет, можно менять для того чтобы переставлять секции местами.
	'priority'       => 160,
	//* ID "панели", в которую стоит поместить секцию.
	'panel'          => '',
	//* Варианты Capabilities для того чтобы ограничить права настройки у пользователей.
	'capability'     => 'edit_theme_options',
	//* Можно добавить любой ID, чтобы потом включать в теме с помощью функции add_theme_support( 'theme_support_setting_id' ).
	'theme_supports' => '',
	//* Заголовок для секции.
	'title'          => '',
	//* Дополнительное описание под заголовком.
	'description'    => '',
	//* Тип секции. Можно добавить любое слово, оно отразится в классе для этой секции и примет вид control-section-default при значении default.
	'type'           => 'default',
) );

После создания аргументы парсятся и присваиваются соответствующим свойствам объекта $wp_customize и к ним можно обращаться и менять значения так: $wp_customize->get_section( 'your_section_id' )->panel = 'your_panel_id'.

Можно видеть, что Customizer API в WordPress организован очень круто и понятно. Мне всегда удобнее было посмотреть сурсы напрямую. Если не хотите курочить свою копию и искать там, то можете почитать WordPress Code Reference.

customize_preview_init

Я выше в аргументах для настроек (setting) сказал, что подробнее остановлюсь на аргументе transport. Его дефолтное значение refresh применяет настройку после перезагрузки. Но мы же в интересное время живем, поэтому можно сделать все понастоящему интерактивным.

Второе значение аргумента transport — это postMessage. Но для него необходимо написать немножк)) небольшую JavaScript функцию, закинуть ее в js-файл и подвесить в экшен customize_preview_init, после чего будет работать на странице Customizer:

add_action( 'customize_preview_init', 'your_customizer_script' );
function your_customizer_script() {
	wp_enqueue_script( 'your-customizer-script', 'path/to/your/script/', array( 'jquery', 'customize-preview' ) );
}

Сама функция довольно-таки бесхитростная:

(function($){
	
	//* Объект wp, который доступен нам имеет метод customize, с помощью которого мы можем привязать на айдишник нашей настройки колбэк (в данном случае анонимная функция)
	wp.customize( 'your_setting_id', function( value ) {
		value.bind( function( to ) {
			//* При отсутствии значения скрываем контейнер
			if ( to == '' ) {
				$( '#samovar-test-meta' ).hide();
			//* При наличии значения показываем контейнер и связываем изменения значения с изменением текста внутри
			} else {
				$( '#samovar-test-meta' ).show();
				$( '#samovar-test-meta' ).text( to );
			}
		});
	});
	
})(jQuery);

#

Заключение по Customizer API

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

Старая добрая страница с настройками темы мне нравится больше. И оформить ее можно красивее.