Como criar campos no Personalizar (Customizer) do WordPress

Este post e este vídeo são o início de uma nova série no canal dedicada às telas de administração do WordPress. Vamos começar pela tela do Personalizar do WP, que é aquela telinha onde a gente faz alterações com pré-visualização. Não se esqueça de assinar o canal e ativar o sininho para não perder nenhum vídeo novo!

Esse conteúdo é o básico do básico. Você pode ver mais lá na documentação oficial. E, como eu expliquei no vídeo, para entender melhor o que precisa ser feito é preciso conhecer alguns nomes:

• Painel (panel): É aquela lista inicial com os itens que têm a setinha pro lado.
• Seção (section): É cada um dos itens que têm a seta. Uma seção agrupa vários campos.
• “Campo”: Não existe uma entidade chamada “campo”. Cada campo na verdade é uma dupla formada por uma setting e um control.
• Configuração (setting): É o dado que é gravado no banco de dados. É este dado que nós vamos chamar para exibir o que o usuário informou no Personalizar.
• Controle (control): É a ponte entre a section e a setting. Ele é o elemento que o usuário manipula de verdade, isto é, o input text, a textarea ou o campo para enviar um arquivo. Sempre está ligado a uma configuração.

Agora vamos para os códigos que eu usei no vídeo e algumas explicações.

Criar um arquivo novo e chamá-lo no functions.php

Isso é completamente opcional, mas recomendado para o seu functions.php não virar uma bagunça. Não precisa ser um arquivo com este nome e ele não precisa estar nesta pasta. Basta apontar para o arquivo certo.

// Isso vai no seu functions.php.
require_once get_template_directory() . '/inc/customizer.php';

Criar os campos

No arquivo que você acabou de criar (ou direto no functions.php, se você curte uma bagunça) é preciso pendurar uma função na action customize_register.

Esta função vai receber como parâmetro a variável $wp_customize, que é uma instância da classe WP_Customize_Manager. São os métodos deste objeto que nós vamos chamar para criar a nova seção “Rodapé” e seus dois campos: “Copyright” e “Logo”.

// O conteúdo do arquivo inc/customizer.php, que incluímos lá em cima.

function meutema_customize_register( $wp_customize ) {
	$wp_customize->add_section(
		'rodape',
		array(
			'title'    => __( 'Rodapé', 'odin' ),
			'priority' => 201,
		)
	);

	$wp_customize->add_setting( 'copyright' );
	$wp_customize->add_control(
		'copyright',
		array(
			'label'   => __( 'Copyright', 'odin' ),
			'section' => 'rodape',
		)
	);

	$wp_customize->add_setting( 'logo_rodape' );
	$wp_customize->add_control(
		new WP_Customize_Media_Control(
			$wp_customize,
			'logo_rodape',
			array(
				'label'     => __( 'Logo', 'odin' ),
				'section'   => 'rodape',
				'mime_type' => 'image',
			)
		)
	);
}
add_action( 'customize_register', 'meutema_customize_register' );

Exibir os valores dos campos

Por último, precisamos usar os valores que o usuário deu para estes campos. Fazemos isto com a função get_theme_mod(), passando o nome da setting como parâmetro.

<footer id="footer" role="contentinfo">
	<div class="container">
		<?php
		$logo_rodape = get_theme_mod( 'logo_rodape' );
		if ( $logo_rodape ) {
			echo wp_get_attachment_image( $logo_rodape, 'full' );
		}
		?>
		<p><?php echo get_theme_mod( 'copyright' ); ?></p>
	</div><!-- .container -->
</footer><!-- #footer -->

Um framework para facilitar

A Customizer API do WordPress é bem robusta, mas não resolve alguns casos como, por exemplo, campos repetíveis. Para isso podemos usar um framework chamado Kirki, que reduz a quantidade de código necessária para a criação de campos e também fornece alguns tipos de campo mais bacanas. Esse será o assunto do próximo vídeo dessa série (já assinou o canal, né?).

O que estudar agora

Como eu falei antes, o vídeo é só o básico. Agora você pode consultar a documentação oficial, ver as possibilidades para os arrays que passamos como segundo parâmetro de add_section, add_setting e add_control. Alterando o type no add_setting, por exemplo, vamos precisar chamar get_option() ao invés de get_theme_mod().

Lá na documentação oficial também tem material para você criar seus próprios controles, fazer atualização seletiva (ao invés de atualizar toda a página quando um campo é alterado), criar campos em seções já existentes, validar os dados antes de salvar e muito mais!