Introdução ao Theme Customizer

Finalmente, chegamos em uma das lições mais interessantes, se não a mais importante da jornada de criação de temas para o WordPress 🥳

O assunto da vez será o Theme Customizer, ou também conhecido como customizador de temas, e garanto para você que no final dessa lição, você vai soltar um: UAU QUE FUNCIONALIDADE INCRÍVEL 🤩😍

Bora começar essa festa?

O que é o Theme Customizer?

Theme Customizer, é a tradução para customizador de temas, e refere-se a uma funcionalidade do WordPress que possibilita que o usuário do seu tema (e até mesmo você), personalize a aparência (layout) de cada elemento existente no seu tema.

Essa personalização incluí: títulos, logos, imagens, arquivos, links, botões.. ou qualquer outro elemento, que você como criador de temas, acredita que possa ser customizado.

O Theme Customizer oferece uma interface visual e 100% interativa, que te ajuda a ajustar diferentes elementos do seu tema em tempo real.

O que facilitando muito a visualização das mudanças antes de aplicá-las definitivamente ao site 😉

Se você está comigo deste o início dessa jornada, é bem provável que você já tenha se deparado com o Theme Customizer, a diferença é que até então, de forma proposital, eu o estava chamando de [Menu de Personalizar].

E sim, é aquele menu que costuma ser acessado quando vamos em Aparência > Personalizar:

Que nada mais é do que o lcoal que abre a sua página, junto a um menu que contém uma lista de opções diferentes para a personalização:

Nós já trabalhamos com ele na lição que fala sobre Suporte de Edição de Temas (Theme Support), você se lembra?

Theme Customizer X Theme Support X Personalizar

Até então, essa área da última imagem acima, já foi chamada de Theme Customizer, Theme Support e até mesmo [Menu de Personalizar].

Mas qual sera que é o verdadeiro nome dessa área? Pois bem, vamos dar os nomes 😌

[Personalizar] - [Aparência] - [Menu de Personalizar] nada mais é do que um nome bonitinho que eu dei para se referir a área de personalização de temas.

Essa área tem um nome específico, e se chama Theme Support.

Já o Theme Customizer, refere-se a uma funcionalidade do WordPress, que é capaz de adicionar novos menus, seções e controles ao Theme Support por meio do functions.php do tema.

Sabe aquelas opções como: Identidade do site, Menus, Configurações da página inicial, CSS Adicional? Então, todos eles são considerados como seções ou painés.

Tudo o que o Theme Customizer faz, é dar a possibilidade de você adicionar novas opções dentro do Theme Support, como por exemplo:

Vamos supor que você queira criar uma nova seção chamada de 'Configurações do Hero', onde dentro dela você quer criar campos de textos, área de textos, links e upload de arquivos e afins...

Você pode fazer isso? SIM VOCÊ PODE!

E esse é um dos objetivos principais do Theme Customizer.

Acredito que agora, não há mais dúvidas sobre o que o Theme Customizer faz 😋

Características do Theme Customizer

O Theme Customizer possuí algumas características interessantes que você precisa conhecer!

Começando pela visualização em tempo real, essa funcionalidade faz com que medida em que você opera ajustes nos controles, você veja imediatamente como essas mudanças afetam a aparência do seu site.

Um outro ponto super interessante é que o Theme Customizer mantém os dados que você informa, dentro de um histórico de mudanças, permitindo que você reverta para configurações anteriores, se necessário.

É importante ressaltar que as funcionalidades do Theme Customizer, varia de tema para tema, existem temas que te oferecem personalizações mais avançadas, e outros personalizações mais básicas.

Existem também temas que podem oferecer suas próprias interfaces de personalização, enquanto outros podem depender de plugins específicos para funcionalidades avançadas.

E falando em plugins, qual é a diferença entre o Theme Customizer e um Plugin do WordPress?

Theme Customizer X Plugins

O Theme Customizer e Plugins são dois conceitos distintos que possuem responsabilidades diferentes no ecossistema do WordPress.

Começando pelo Theme Customizer, ele é uma ferramenta nativa oferecida pelo CMS, com o intuito de personalizar a aparência do seu tema em tempo real.

Onde os usuários do seu tema, podem ajustar diversas configurações relacionadas à aparência do site, como títulos, subtítulos, background, cores, fontes, cabeçalho, rodapé plano de fundo, e muito mais.

Sendo uma funcionalidade especifica ligada ao tema em questão, tanto que ao ativar ou desativar um determinado tema, tais funcionalidades podem deixar de existir.

Ou seja, o Theme Customizer não adiciona funcionalidades adicionais ao site, apenas permite ajustar o visual do tema escolhido, isto é, quando este estiver ativo.

Já os Plugins, fazem parte de uma outra categoria totalmente diferente, sendo considerados extensões que adicionam funcionalidades ao WordPress como um todo.

E quando eu digo "como um todo", digo a capacidade de adicionar funcionalidades ao Painel Administrativo, a programação do próprio WordPress, além de personalizações no tema em que se encontra ativo.

Além disso, os plugins podem ser usados para uma variedade de propósitos, desde a criação de formulários, otimização de SEO, segurança do site, integração com redes sociais, integração com APIs, e tudo aquilo que pode ser projetado para estender as capacidades básicas do CMS.

Em resumo, o Theme Customizer é específico para ajustes visuais no tema, enquanto os Plugins são usados para estender as funcionalidades do WordPress.

Eu posso criar um plugin para atender as necessidades do meu tema?

Sim, isso é totalmente possível de ser feito. Tanto é, que existem temas que possuem seus próprios plugins específicos.

Campos personalizados dentro do painel de criação de páginas e posts

Não sei se você já viu, mas existem alguns temas que adicionam campos de texto e recursos de edição adicionais, dentro do painel de criação de páginas ou posts, como esses abaixo:

Esses recursos são possível de serem feitos por meio de uma funcionalidade chamada de MetaBoxes, ao mesmo tempo que não possuem nenhuma relação com o Theme Customizer.

Apesar de ambos oferecerem recursos de edição parecidos, o Theme Customizer serve para adicionar recursos dentro do Theme Support, enquanto os MetaBoxes adicionam recursos dentro do Painel do WordPress (ao mesmo tempo que não são considerados plugins, ok).

Nas próximas lições, veremos um conteúdo dedicado a eles 🤩

Opções do Theme Customizer

Existem diversas opções de edição que podemos criar com o Theme Customizer, e isso incluí os seguintes formulários HTML:

Radio Box;
CheckBox;
Select;
Text;
Textarea;
Email;
URL;
Number;
Dropdown;
File Input;
HTML Color & Code;
Javascript Code;

Como visto acima, são muitas possibilidades, e a cada nova versão do WordPress mais funcionalidades são adicionadas ao Theme Customizer.

Nesta lição veremos como realizar a configuração inicial 🥳

Entendendo a área de Theme Support

Antes de continuarmos, é interessante que você entenda a nomenclatura da área do Theme Support.

Quando abrimos esta área pela primeira vez, nós deparamos com menus que contam com diversas opções:

Os elementos que temos do lado esquerdo (Identidade do site, Mídia do cabeçalho... css adicional) são chamados de seções ou de painéis.

O nome depende das configurações daquela opção. Se uma daquelas opções levar o usuário para uma tela final onde exista recursos editáveis, como é o caso da opção [Identidade do site]:

Para o WordPress, a opção [Identidade do Site] deve ser chamada de seção. Onde os campos editáveis são conhecidos como controles.

Diferente do que vemos quando abrimos a opção [Menus] e [Widgets]:

Como podemos ver, existem outras opções que levam o usuário a outras telas, em casos como esses, o WordPress considera essas opções (Menus e Widgets) como painéis.

Com o Theme Customizer, conseguimos tanto criar novas seções, como também criar novos painéis.

Apesar disso, a própria documentação do WordPress diz que não deveríamos criar painéis na maioria dos casos, levando os usuários do nosso tema, diretamente para os controles.

Entendendo as Settings

Entre as nossas seções e os controles, nós temos as famosas settings, que nada mais são do que uma camadas de controle, responsável por trafegar as informações entre o banco de dados do WordPress e os seus controles.

Elas são responsáveis por definir os objetos que acessam, e que persistem os dados que seu usuária informa nos controles (text, textarea, upload...) no banco de dados, e também atualizam a página em tempo real.

Os dados que o seu usuário insere no Theme Support, são salvos dentro de uma tabela chamada de wp_options dentro de um campo que começa com theme_mods.

Para saber mais sobre elas, acesse este link.

Basicamente o settings é uma camada que vai salvar os dados que seu usuário informa no controle com o banco de dados do WordPress, como se fosse uma ponte, simples assim 👍

Trabalhando com Theme Customizer

Chega de momentos teóricos, que eu sei que você já está louco para colocar a mão na massa e criar seus campos personalizados no Theme Support.

E é o que vamos fazer agora 😆

Criando a pasta INC

Por questões de organização de código, vamos começar criando uma nova pasta dentro da raiz do seu tema, onde essa nova pasta deverá ser chamada de inc.

Será dentro dela que nós iremos adicionar todos os recursos que serão atribuídos ao Theme Customizer.

Criou a pasta? Então já podemos seguir a diante com nosso exercício.

Criando o arquivo de customizer

Dentro da pasta inc, você vai precisar criar um novo arquivo referente ao tipo de customização que você deseja aplicar.

No meu caso, eu vou reunir todas as customizações dentro de um único arquivo chamado de micilini-customizer.php.

Sendo assim, dentro da pasta inc, crie um novo arquivo, no meu caso nomeei ele de micilini-customizer.php:

Feito isso, vamos seguir adiante.

Importando o customizer dentro do functions.php

Já dentro do arquivo functions.php do seu tema, você vai precisar importar o arquivo que acabamos de criar (micilini-customizer.php), uma vez que, o WordPress não irá reconhecer o arquivo do customizer automaticamente assim como acontece com functions.php.

O código abaixo deve ser inserido fora de qualquer outra função que criamos até o momento dessa jornada.

Recomendo colar o código abaixo logo no início do functions.php:

require get_template_directory().'/inc/micilini-customizer.php';

Como falado em lições anteriores, a função get_template_directory() vai retornar o caminho da pasta raiz do seu tema.

Feito isso, já podemos voltar ao arquivo do customizer 😆

Criando uma função dentro do customizer

Assim como fizemos em algumas lições onde usamos o functions.php, por questões de organização, vamos seguir o mesmo procedimento no nosso arquivo do customizer (micilini-customizer.php), ou seja, vamos agrupar toda a lógica dentro de uma única função:

<?php

function micilini_customizer($wp_customize){
 //Insira aqui os códigos para criar painéis, seções e controles
}

add_action('customize_register', 'micilini_customizer');

Tudo começa com a abertura das tags PHP, seguido de uma função principal chamada de micilini_customizer(), que será responsável por agrupar todos os códigos que iremos usar daqui em diante para criar nossos painéis, seções e controles.

$wp_customize: é a variável que contem a classe do customizador, que lida com a execução e controle do customizer. Ela será usada para criar seções, painéis e controles.

Por fim, fizemos o uso do comando add_action(), que é uma função do próprio WordPress usada para fazer a vinculação com as funções do painel do WordPress.

'customize_register': este gancho é acionado quando o Theme Support é inicializado no painel de administração do WordPress.

'micilini_customizer': é o nome da função que será executada quando o gancho 'customize_register' for acionado.

Com essas configurações, não veremos nada de novo dentro do painel do Theme Support, mas já será suficiente para seguirmos com nossas implementações daqui em diante.

Criando Seções

Para criar uma nova seção no Theme Customizer, você vai precisar adicionar o seguinte código dentro da função micilini_customizer():

$wp_customize->add_section(
 'section_titulo',
 array(
 'priority' => 1,
 'title' => 'Minha Primeira Seção',
 'description' => 'Seja bem vindo a minha primeira seção =)'
 ) 
);

$wp_customize: chamamos a função que é responsável por lidar com a classe de customizer, pois precisamos dela para criar uma seção.

add_section(): é o método que chamamos para criar uma nova seção no theme customizer. Ela recebe dois argumentos principais:

'section_titulo': é o identificador único daquela seção. Por padrão eu sempre começo informando section_ + nome da seção.

O segundo argumento refere-se a um array que contém outros argumentos:

'priority': é a prioridade em que a sua seção ficará organizada no theme support, neste exemplo ela ficará no posição 1, acima da seção identidade do site.

'title': é o título da seção que vai aparecer como uma opção do theme support.

'description': é a descrição da seção que vai aparecer junto a opção do theme support.

Observação: Apenas com essa configuração, o WordPress não vai mostrar a sua nova seção no Theme Support, pois ela ainda precisa estar atrelada a pelo menos um controle.

Apesar disso, o resultado final ficará assim:

Criando Paineis

Para criar um novo painel no Theme Customizer, você vai precisar adicionar o seguinte código dentro da função micilini-customizer():

$wp_customize->add_panel(
 'panel_micilini', 
 array(
 'priority' => 1,
 'title' => 'Tema do Micilini',
 'description' => 'Aqui está todas as configurações personalizadas do tema =)'
 ) 
);

$wp_customize: chamamos a função que é responsável por lidar com a classe de customizer, pois precisamos dela para criar um painel.

add_panel(): é o método que chamamos para criar um novo painel no theme customizer. Ela recebe dois argumentos principais:

'panel_micilini': é o identificador único daquele painel. Por padrão eu sempre começo informando panel_ + nome do painel.

O segundo argumento refere-se a um array que contém outros argumentos:

'priority': é a prioridade em que o seu painel ficará organizado no theme support, neste exemplo ele ficará no posição 1, acima da seção identidade do site.

'title': É o título do painel que vai aparecer como uma opção do theme support.

'description': É a descrição do painel que vai aparecer junto a opção do theme support.

Observação: Apenas com essa configuração, o WordPress não vai mostrar o seu novo painel no Theme Support, pois ele ainda precisa estar atrelada a pelo menos uma seção que contenha pelo menos um controle.

Apesar disso, o resultado final ficará assim:

Atrelando sua seção a um painel

O processo de atrelamento é bem simples, basta que você defina um novo argumento dentro do array do segundo argumento do método add_section(), chamado de 'panel', observe:

// Panel
 $wp_customize->add_panel(
 'panel_micilini', 
 array(
 'priority' => 1,
 'title' => 'Tema do Micilini',
 'description' => 'Aqui está todas as configurações personalizadas do tema =)'
 ) 
 );
 //Section
 $wp_customize->add_section(
 'section_titulo',
 array(
 'priority' => 1,
 'title' => 'Minha Primeira Seção',
 'description' => 'Seja bem vindo a minha primeira seção =)',
 'panel' => 'panel_micilini'
 ) 
 );

Note que o argumento 'panel' armazena o identificador 'panel_micilini' que criamos no método add_panel() logo acima.

Observação: Tenha em mente que o seu painel e seção não estarão disponíveis para visualização no Theme Support enquanto não adicionarmos controles a nossa seção.

Adicionando Settings

Como falado anteriormente, uma setting nada mais é do que uma configuração que fazemos entre o banco de dados e um determinado controle.

Isso significa dizer que para cada controle que criamos, uma nova setting precisa ser criada também.

Será a setting que fará essa intermediação entre o controle e o banco de dados. Vejamos como isso funciona.

Dentro do seu arquivo de customizer, mais especificamente dentro da função micilini_customizer() você precisa adicionar o seguinte código:

$wp_customize->add_setting(
 'setting_informacoes_titulo',
 array(
 'type' => 'theme_mod',
 'default' => 'Este é um título de exemplo',
 'sanitize_callback' => 'sanitize_text_field'
 )
);

$wp_customize: chamamos a função que é responsável por lidar com a classe de customizer, pois precisamos dela para criar nossa setting.

add_setting(): método responsável por adicionar as settings no banco de dados. Ela recebe dois argumentos principais:

'setting_informacoes_titulo': é o identificador daquela settings. E significa que essa setting terá alguma relação com um controle responsável por editar o título do documento (veremos como criar ele a seguir).

O segundo argumento refere-se a um array que contém outros argumentos:

'type': define o tipo de configuração em que os dados serão salvos no banco de dados. Atualmente existem dois tipos de configurações: 'theme_mod' e 'options'.

'default': é o valor padrão da configuração. Se a configuração não tiver sido editada no controle, ele usará este valor como padrão.

'sanitize_callback': Este parâmetro especifica uma função de callback para sanitizar (limpar e validar) o valor antes de ser salvo no banco de dados.

Existem inúmeros tipos de sanitizadores disponibilizados pelo WordPress, veremos o funcionamento de cada um deles nas próximas lições.

'sanitize_text_field' é uma função padrão do WordPress que remove caracteres perigosos e garante que o valor seja uma string segura. Usamos ele já pensando no tipo de controle que iremos criar logo abaixo 🫢

É importante ressaltar que uma setting deve ser criada em conjunto com um controle, pois como vimos acima, o argumento de sanitize atua em conjunto com o tipo de controle que será usado.

Isso significa que para cada controle que criarmos, uma setting precisa estar associada a ele.

Tipos de configurações de settings

Vimos que o argumento 'type' pode receber dois tipos diferentes de configurações que são 'theme_mod' e 'options', vejamos a diferença entre cada uma delas.

No caso do 'theme_mod', estamos dizendo ao WordPress para que ele salve as modificações do seu tema no banco de dados. De modo que se o seu tema for alterado, as modificações do tema ainda permanecerão associadas ao antigo tema.

O 'theme_mod' são configurações que só podem ser acessadas pelo seu tema e mais nenhum outro.

Já o 'options' diz ao WordPress para salvar as modificações do seu tema globalmente, e isso significa que outros temas e plugins podem ter acesso a essas configurações.

Como essa opção não é afetada por mudanças de tema; elas permanecem mesmo se o tema for alterado.

Por padrão o WordPress recomenda que façamos o uso do 'theme_mod' na maioria dos casos.

Adicionando Controles

Como vimos no início desta lição, existem vários tipos de controles, desde text, textarea, file upload, dropdown e muitos outros.

Vamos começar primeiro aprendendo sobre o text, até porque, o setting que criamos acima será usado justamente com ele 😆

Controle: Text

O controle do tipo text refere-se a um campo de texto, ou seja, um <input type="text"> do HTML5, onde este, pode estar atrelado a um título junto a uma pequena descrição.

Para adicionar um controle do tipo text, basta inserir o comando abaixo dentro da função micilini_customizer():

//Control (Text Field)
 $wp_customize->add_control(
 'setting_informacoes_titulo',//Aqui passamos o identificador da setting referente ao controle
 array(
 'label' => 'Título do Documento',
 'description' => 'Informe um título para o seu documento.',
 'section' => 'section_titulo',
 'type' => 'text'
 )
 );

$wp_customize: chamamos a função que é responsável por lidar com a classe de customizer, pois precisamos dela para criar um controle.

add_control(): método responsável por adicionar novos controles no theme support. Ela recebe dois argumentos principais:

'setting_informacoes_titulo': é o identificador daquela settings que criamos anteriormente. Significa que essa setting tem relação com o controle, e será usada para trafégar e sanitizar as informações que o usuário informar no controle para o banco de dados.

O segundo argumento refere-se a um array que contém outros argumentos:

'label': é o título referente ao controle.

'description': é a descrição referente ao controle.

'section': é a seção em que o controle deve ser inserido. Aqui informamos o identificador da seção que criamos em passos anteriores.

'type': é o tipo de controle que será adicionado, no nosso caso estamos criando um campo de texto do tipo text.

Só com essas informações, você já será capaz de visualizar o Painel, a Seção e também o Controle no Theme Support.

Visualizando as alterações

Se você seguiu todos os passos acima, já será capaz de visualizar as alterações no Theme Support:

Note que todas as informações que inserimos nos passos anteriores, existem dentro do Theme Support.

Perceba que você também é capaz de editar o título do documento, e ao clicar em [Publicar] o novo título ficará salvo no banco de dados do WordPress sempre que você atualizar a página.

Legal né 😋

Conectando seu controle com seu tema

Após realizarmos todos os procedimentos acima, só restou uma única coisa, e uma das mais importantes... conectar o controle em um dos arquivos do seu tema.

O processo é bem simples, basta abrir um dos seus modelos de template em que aquele controle se relaciona, e em seguida colar o seguinte comando:

<?php echo get_theme_mod('setting_informacoes_titulo'); ?>

A função get_theme_mod() é uma função do WordPress que é usada para recuperar valores de modificações de temas no banco de dados, desde que o tipo da setting seja 'theme_mod'.

Essa função recebe dois parâmetros, sendo o segundo opcional:

<php echo get_theme_mod( $name, $default ); ?>

$name: é o identificador da setting que queremos retornar do banco de dados. No nosso caso informamos 'setting_informacoes_titulo'.

$default: um valor padrão a ser retornado, caso essa setting estiver vazia.

Já o comando get_theme_mods() com S no final, é usado para retornar uma lista em formato de array, contendo todas as settings atribuídas ao seu tema:

<php

// Obtém todas as modificações de tema
$theme_mods = get_theme_mods();

// Exibe todas as modificações de tema
print_r($theme_mods);

?>

Perfeito, se o get_theme_mod() é usado para retornar as configurações dos settings marcadas como 'theme_mod', qual é a função usada para retornar as settings marcadas como 'options'?

Neste caso usamos o comando get_option():

<php echo get_option('theme_mods_theme_name'); // Substitua 'theme_name' pelo slug do seu tema ?>

Perceba que estamos usando um argumento em formato de string, que diz para o WordPress acessar as settings do seu tema (theme_mods_) ligados a um tema específico (theme_name).

Não se esqueça de colocar o slug (identificador) do seu tema onde está escrito theme_name, por exemplo:

<php echo get_option('theme_mods_wp-micilini'); ?>

Para que possamos ver como ficou o resultado da conexão final, eu vou usar o comando get_theme_mod() dentro do page.php da seguinte forma:

<p><strong>Título do Documento: </strong> <?php echo get_theme_mod('setting_informacoes_titulo'); ?></p>

Veja como ficou o resultado final:

Incrível não? Dessa forma, tudo o que você salvar no controle, já será atualizado dentro da sua página.

Perguntas & Respostas sobre Theme Customizer?

1) Existe um limite de controles, seções ou painés que o WordPress suporta?

Não, você pode criar quantos painéis, seções e controles desejar.

2) Toda seção precisa estar associada a um painel?

Não, basta apenas que você não informe o argumento 'panel' dentro do segundo argumento da função add_section().

3) Todo controle deve estar associado a uma setting?

Sim, o controle é o formulário visual em que o usuário do seu tema vai interagir, e a setting é a lógica que existe por trás do controle que será responsável por validar e limpar os dados informados no controle, para posteriormente salvá-los no banco de dados.

4) Para que uma seção ou painel possa ser visualizada, ela sempre precisa estar conectada a um controle?

Sim, é uma regra do CMS que não podemos mudar.

5) Podemos conectar um painel diretamente a um controle?

Não, pois o painel é usado para exibir uma lista de seções. Já as seções são usada para exibir os controles associados a ela.

Conclusão

Acredito que agora você esteja boquiaberto pensando, ou até mesmo dizendo: UAU QUE FUNCIONALIDADE INCRÍVEL 🤩😍

Calma que você ainda não viu nada, pois esta lição foi somente uma introdução ao Theme Customizer, onde aprendemos a criar um único controle do tipo text.

Na próxima lição veremos o funcionamento dos outros tipos de controles.

Te espero lá 🙌