APIs JavaScript do Customizer: O Pré-visualizador

Assumamos que construímos um tema com algumas configurações e controles do Customizador que os usuários customizar várias coisas do front-end fo tema, como o título do site, slogan e cor.

Contudo, alguns dos usuários podem não saber que podem customizar essas áreas do tema, especialmente se elas estiverem enterradas em vários painéis e seções. Então, como agilizar o processo de customização de um tema?

WordPress.com adicionou recentemente botões a algumas áreas editáveis, que são notáveis imediatamente após abrir o Customizador. Quando o usuário clica nesses botões, ele mostrará o respectivo controle.

É um aprimoramento legal que também podemos ter, usando a API JavaScript do Customizador em nosso tema. E não é tão complicado quanto aparenta ser. Então, vejamos como ele funciona.

Pré-requisitos

No tutorial passado, criamos o arquivo customizer-control.js, que afeta as interfaces backend do Customizador Nesse tutorial, usaremos outro arquivo, customizer-preview.js, que será carregado na janela de visualização. Devemos ter esses dois arquivos criados e carregados. Caso contrário, sugerimos que siga o primeiro tutorial dessa série antes de continuar.

Criando um Botão Editar

Primeiro, adicionaremos botões Editar próximo ao Título do Site.

1

<h1 class="site-title">

2

  <a href="<?php echo esc_url( home_url( '/' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a>

3

	<?php if ( is_customize_preview() ) : ?>

4

	<button class="customizer-edit" data-control='{ "name":"blogname" } ''><?php esc_html_e( 'Edit Text', 'cjs' ); ?></button>

5

	<button class="customizer-edit" data-control='{ "name":"header_textcolor", "color": true } ''><?php esc_html_e( 'Edit Color', 'cjs' ); ?></button>

6

	<?php endif; ?>

7

</h1>

Usando is_customizer_preview(), esse botão será visto apenas na Pré-visualização do Customizador. A cada um dos botões é atribuído .customizer-edit, que nos permitirá selecioná-los e vincular o evento click.

Além do mais, também adicionamos aos botões um atributo data-control contendo o nome ou id da configuração registrada no Customizador. O nome nesse atributo ajudará a determinar a configuração e controle apropriados que nos servirão mais tarde.

Como apresentação não é nossa preocupação principal agora, os dois botões "Editar" na prévisualização não são tão bonitos quanto os do WordPress.com. Podemos adicionar estilos que casem com o design do tema como um todo.

Definindo Eventos Customizados

Agora, definiremos um evento customizado que diz que um dos botões foi clicado. Adicionemos o código a seguir em customizer-preview.js.

1

var customize = wp.customize;

2

3

$( document.body ).on( 'click', '.customizer-edit', function(){

4

	customize.preview.send( 'preview-edit', $( this ).data( 'control' ) );

5

});

O código vincula cada um dos botões a um evento click, usando o método .preview.send() para lançar um evento. O método .preview.send() leva dois parâmetro, o nome do evento customizado e seu argumento. Em nosso caso, definimos um evento chamado preview-edit e passamos um argumento com os dados do atributo data-control do botão.

Observando o Evento Customizado

Podemos observar um evento lançado pelo método .preview.send() através do método .previewer.bind() do Customizador—note o er de previewer. Ele é um método similar ao .on() do jQuery, em que definimos o nome de um evento ao qual observaremos e uma função que será executada quando o evento é ativado. Adicione .previewer.bind() no customizer-control.js, assim:

1

var customize = wp.customize;

2

3

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

4

5

} );

Agora, transformamos os dados passados em no formato JSON, selecionamos um elemento de controle usando name dos dados, e focamos no elemento de controle, usando o método .focus() do Customizador.

1

var customize = wp.customize;

2

3

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

4

	var data = JSON.parse( data );

5

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

6

7

	control.focus();

8

} );

Como vemos abaixo, ao clicar, por exemplo, no botão "Edit Text", ele mostrar a configuração "Site Title" e focará o cursos no campo.

Além do mais, se espionarmos o código, o método .focus() aceita um parâmetro chamado completeCallback. Esse parâmetro é executado após o método .focus() ser executado. Podemos usar esse parâmetro, por exemplo, para adicionar uma animação.

1

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

2

3

	var data = JSON.parse( data );

4

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

5

6

	control.focus( {

7

		completeCallback : function() {

8

			setTimeout( function() {

9

				control.container.addClass( 'shake animated' );

10

			}, 300 );

11

		}

12

	} );

13

} );

A experiência como um todo parece mais viva, agora.

Resumindo

Mencionamos várias APIs JavaScript do Customizador

• .preview.send() para lançar um evento customizado
• .previewer.bind() para vincular o Customizador a um evento customizado
• .focus() para focar no campo do controle e também o parâmetro completeCallback.

Nesse tutorial, usamos métodos para permitir os usuários do tema editar o título do site, bem rápido, clicando no botão "Edit Text" na pré-visualização.

Ainda falta um botão para vincular o controle de cores. Mas ele será um desafio. Use os mesmos três métodos para criar a função "Edit Color". Em caso de dúvidas, dê uma olhada no código fonte.