Customizer JavaScript API: Предварительный просмотр

Предположим, что мы создали тему с определенным числом параметров и элементов управления в Customizer, которые позволяют пользователям настроить во фронт-енд такие параметры как заголовок, подзаголовок и цвет.

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

WordPress.com недавно добавил кнопки Edit в некоторых редактируемых областях, которые видны сразу же после запуска настройщика. При нажатии на данные кнопки, будут отображаться соответствующие элементы управления.

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

Необходимые условия

В предыдущем уроке мы написали файл customizer-control.js, который работает только с внутренним интерфейсом настройщика (Customizer). В данном уроке мы создадим еще один файл, customizer-preview.js, который загружается в окне предварительного просмотра. У вас должны быть созданы и загружены эти два файла. В противном случае я предлагаю вам просмотреть первый урок данной серии, чтобы вы могли следовать данному уроку.

Создаем кнопку Edit

Во-первых, добавляем пару кнопок Edit рядом с название сайта.

<h1 class="site-title">
  <a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a>
	<?php if ( is_customize_preview() ) : ?>
	<button class="customizer-edit" data-control='{ "name":"blogname" } ''><?php esc_html_e( 'Edit Text', 'cjs' ); ?></button>
	<button class="customizer-edit" data-control='{ "name":"header_textcolor", "color": true } ''><?php esc_html_e( 'Edit Color', 'cjs' ); ?></button>
	<?php endif; ?>
</h1>

Воспользуемся is_customize_preview(), эта кнопка будет показан только в окне просмотра настройщик. Каждой из этих кнопок присвоен класса с именем .customizer-edit, который позволит нам связать данные кнопки с событием click.

Кроме того, мы также добавили data-control атрибуты к данным кнопкам, содержащие либо имя либо идентификатор зарегистрированного в настройщике параметра. Имя в этом атрибуте поможет нам определить правильные настройки и элементы управления.

Так как презентация не является нашей главной задачей в настоящее время, внешний вид наших двух кнопок «Edit» в окне предварительного просмотра оставляет желать лучшего, по сравнению с такими же кнопками в WordPress.com. Вы можете добавить стили, соответсвующие дизайну вашей темы в целом.

Определяем пользовательские события

Далее мы определим пользовательское событие; Событие, которое реагирует на нажатие одной из кнопок. Добавьте следующий код в файл customizer-preview.js.

var customize = wp.customize;

$( document.body ).on( 'click', '.customizer-edit', function(){
	customize.preview.send( 'preview-edit', $( this ).data( 'control' ) );
});

С помощью метода .preview.send(), код привязывает каждую из кнопок к событию click, что приводит в действие событие. Метод .preview.send() принимает два параметра, а именно: имя настраиваемого события и аргумент. В нашем случае мы определили новое событие предварительного просмотра preview-edit,  и передаем аргумент с данными, полученными из атрибута кнопки data-control.

Слушаем пользовательские события

Мы можем слушать пользовательские события из метода .preview.send() через другой метод настройщика, называемый .previewer.bind() — Обратите внимание previewer написан с er. Этот метод похож на метод jQuery .on(), в котором мы определяем имя события и функция, которая будет выполняться при запуске события. Добавьте .previewer.bind() в файл customizer-control.js следующим образом.

var customize = wp.customize;

customize.previewer.bind( 'preview-edit', function( data ) {

} );

Далее мы преобразуем данные в формат, соответствующий JSON, выбирем элемент управления, основываясь на name,  и сфокусируемся на элементе управления, с помощью метода настройщика .focus().

var customize = wp.customize;

customize.previewer.bind( 'preview-edit', function( data ) {
	var data = JSON.parse( data );
	var control = customize.control( data.name );

	control.focus();
} );

Теперь, как вы можете видеть ниже, когда мы нажимаем, например, на кнопку «Редактирование текста», он покажет параметр «Заголовок Сайта» и зафиксирует курсор на вводе.

Кроме того, если взглянуть на исходный код, метод .focus() принимает параметр с именем completeCallback. Этот параметр сработает после того, как выполнится функция .focus(). Мы можем использовать этот параметр, например, чтобы добавить эффект анимации.

customize.previewer.bind( 'preview-edit', function( data ) {

	var data = JSON.parse( data );
	var control = customize.control( data.name );

	control.focus( {
		completeCallback : function() {
			setTimeout( function() {
				control.container.addClass( 'shake animated' );
			}, 300 );
		}
	} );
} );

Опыт пользователя теперь выглядит более интересным.

Подводя итоги

Мы уже упоминали несколько методов Customizer JavaScript API:

• метод .preview.send() для приведения пользовательского события.
• метод .previewer.bind()  для привязки настройщика к пользовательскому событию.
• метод .focus(), чтобы сфокусироваться на input элементе управления, а так же параметр completeCallback.

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

У нас осталась еще одна кнопка, чтобы настроить управление цветом. Но я оставлю эту задачу для вас, используйте те же три метода для функции «Изменить цвет». Если вы сомневаетесь, не стесняйтесь заглядывайте в исходный код.