O Customizer API do WordPress permite criar opções no tema que você estiver desenvolvendo, ou em um tema que você já utiliza. Além disso, também permite a utilização do live preview para que o usuário possa visualizar alterações ao-vivo antes de salvar e colocar o novo conteúdo no ar.
Uma das partes mais interessantes do Customizer API do WordPress para o desenvolvedor, é que ele é um framework que facilita a criação de opções do tema, já que não é necessário se preocupar com design ou a criação de uma nova página para que o usuário possa alterar o tema em questão. Ele já vem pronto para adicionar controles de campos de texto, checkbox, radio, textareas, cores, upload de imagens, widgets, menus e mais. Na verdade, um desenvolvedor será capaz de adicionar alterações para total configuração do tema em live preview sem dores de cabeça ou dificuldades.
Caso você ainda não conheça esta opção, todo e qualquer tema WordPress apresenta opções que fazem uso do Customizer API, mesmo que um desenvolvedor não adicione nenhuma opção no tema ativo. Por falar em “tema ativo”, um tema não precisa necessariamente estar ativo para que o usuário possa alterar suas opções utilizando o Live Preview (Pré-visualização ao-vivo).
Para acessar o Live Preview, simplesmente acesse a opção “Aparência” – “Personalizar” no seu Painel do WordPress.
Acessando o Live Preview do WordPress
Dentro do Live Preview serão apresentadas as opções divididas por seções, exemplo: Identidade do site, Imagem do cabeçalho, Menus, Widgets, e qualquer outra que o desenvolvedor queira adicionar.
Dentro das sessões você poderá encontrar as opções do tema, que poderão alterar quaisquer partes do tema que o desenvolvedor preferir.
Vamos ver em mais detalhes como adicionar sessões, configurações e controles para fazer uso do Customizer API do WordPress.
Como funciona o Customizer API para o desenvolvedor
O Customizer API do WordPress requer pelo menos o seguinte para funcionar corretamente:
- Uma seção –
add_section() - Uma configuração –
add_setting() - Uma controle –
add_control()
Além disso, é necessário adicionar tudo isso dentro de uma função PHP para que você possa utilizar o gancho customize_register do WordPress.
Veja um exemplo básico para adicionar uma seção que contém apenas um campo:
<?php
/**
* Função para registrar as opções do customizer
*/
function funcao_do_customizer( $wp_customize ) {
/**
* Define a sessão
* Para este exemplo nossa sessão terá o ID "campos_de_texto", título "Textos" e
* descrição "Altere os textos do seu tema."
*/
$wp_customize->add_section(
'campos_de_texto',
array(
'title' => 'Textos',
'description' => 'Altere os textos do seu tema.',
'priority' => 30,
)
);
/**
* Adiciona uma nova setting
* O interessante aqui é que você pode definir um valor padrão e o modo como
* o transport será realizado.
*/
$wp_customize->add_setting(
'campo1', // campo
array(
'default' => '', // Valor padrão
'transport' => 'refresh', // Transport
)
);
/**
* Adiciona um control
* Aqui você trata do campo que será exibido.
*/
$wp_customize->add_control(new WP_Customize_Control(
$wp_customize,
"campo1", // campo
array(
"label" => "Label do campo 1", // Rótulo do campo
"section" => "campos_de_texto", // Sessão que o campo será exibido
"settings" => "campo1", // A settings do campo
"type" => "text", // Tipo do campo
)
));
}
// Utiliza o gancho para adicionar nossa função
add_action( 'customize_register', 'funcao_do_customizer' );
?>
Os comentários no código acima poderão lhe ajudar a entender melhor o que estamos fazendo.
Observação: O trecho de código acima poderá ser adicionado diretamente no arquivo functions.php do seu WordPress.
O trecho de código anteriormente exibido criará uma seção de “Textos” no Live Preview do WordPress. Dentro dela, temos apenas um campo.
Veja uma imagem mostrando a sessão:
A seção “Textos” foi criada pelo código exibido
Veja como ficou dentro da seção com a configuração e campo que criamos:
Dentro da seção “Textos”
Observação: Para este exemplo, estou utilizando o tema Twenty Fifteen que já vem por padrão na última versão do WordPress.
Agora que você já entendeu o básico, vamos adicionar alguns campos mais complexos.
Campos de texto
Vamos criar um formulário completo dentro da seção de textos que acabamos de criar, fique atento aos comentários do código, eles irão descrever o que precisamos.
<?php
/**
* Função para registrar as opções do customizer
*/
function funcao_do_customizer( $wp_customize ) {
// -------------------------------------------------------------------------
// Seção
// Ela será utilizada em todos os campos do formulário
// -------------------------------------------------------------------------
$wp_customize->add_section(
'campos_de_texto',
array(
'title' => 'Textos',
'description' => 'Altere os textos do seu tema.',
'priority' => 30,
)
);
// -------------------------------------------------------------------------
// Input do tipo "text"
// -------------------------------------------------------------------------
// Setting do campo1
$wp_customize->add_setting(
'campo1', // campo1
array(
'default' => '', // Valor padrão
'transport' => 'refresh', // Transport
)
);
// Controle do campo1
$wp_customize->add_control(new WP_Customize_Control(
$wp_customize,
"campo1", // campo1
array(
"label" => "Label do campo 1", // Rótulo do campo
"section" => "campos_de_texto", // A seção
"settings" => "campo1", // Settings do campo
"type" => "text", // Input do tipo "text"
)
));
// -------------------------------------------------------------------------
// Input do tipo "checkbox"
// -------------------------------------------------------------------------
// Setting do campo2
$wp_customize->add_setting(
'campo2', // campo2
array(
'default' => '', // Valor padrão
'transport' => 'refresh', // Transport
)
);
// Controle do campo2
$wp_customize->add_control(new WP_Customize_Control(
$wp_customize,
"campo2", // campo2
array(
"label" => "Label do campo 2", // Rótulo do campo
"section" => "campos_de_texto", // A seção
"settings" => "campo2", // Settings do campo
"type" => "checkbox", // Input do tipo "checkbox"
)
));
// -------------------------------------------------------------------------
// Input do tipo "radio"
// -------------------------------------------------------------------------
// Setting do campo3
$wp_customize->add_setting(
'campo3', // campo3
array(
'default' => '', // Valor padrão
'transport' => 'refresh', // Transport
)
);
// Controle do campo3
$wp_customize->add_control(new WP_Customize_Control(
$wp_customize,
"campo3", // campo3
array(
"label" => "Label do campo 3", // Rótulo do campo
"section" => "campos_de_texto", // A seção
"settings" => "campo3", // Settings do campo
"type" => "radio", // Input do tipo "radio",
// Para "radio" é necessário adicionar um array de escolhas
"choices" => array(
"escolha-1" => "Escolha 1",
"escolha-2" => "Escolha 2",
"escolha-3" => "Escolha 3",
),
)
));
// -------------------------------------------------------------------------
// Área de texto do tipo "textarea"
// -------------------------------------------------------------------------
// Setting do campo4
$wp_customize->add_setting(
'campo4', // campo4
array(
'default' => '', // Valor padrão
'transport' => 'refresh', // Transport
)
);
// Controle do campo4
$wp_customize->add_control(new WP_Customize_Control(
$wp_customize,
"campo4", // campo4
array(
"label" => "Label do campo 4", // Rótulo do campo
"section" => "campos_de_texto", // A seção
"settings" => "campo4", // Settings do campo
"type" => "textarea", // Área de texto do tipo textarea
)
));
// -------------------------------------------------------------------------
// Escolhas do tipo "select"
// -------------------------------------------------------------------------
// Setting do campo5
$wp_customize->add_setting(
'campo5', // campo5
array(
'default' => '', // Valor padrão
'transport' => 'refresh', // Transport
)
);
// Controle do campo5
$wp_customize->add_control(new WP_Customize_Control(
$wp_customize,
"campo5", // campo5
array(
"label" => "Label do campo 5", // Rótulo do campo
"section" => "campos_de_texto", // A seção
"settings" => "campo5", // Settings do campo
"type" => "select", // Escolhas do tipo "select"
// Para "select" é necessário adicionar um array de escolhas
"choices" => array(
"escolha-1" => "Escolha 1",
"escolha-2" => "Escolha 2",
"escolha-3" => "Escolha 3",
),
)
));
// -------------------------------------------------------------------------
// FIM
// -------------------------------------------------------------------------
} // funcao_do_customizer
// Utiliza o gancho para adicionar nossa função
add_action( 'customize_register', 'funcao_do_customizer' );
?>
Por parecer muito código, mas é bastante simples. Se você observar, são blocos de código que estão divididos em partes para gerar novos campos.
O trecho de código acima deverá gerar um formulário com a maioria dos tipos de campo que você possa precisar: text, checkbox, radio, textarea e select. Veja como o formulário é apresentado no Live Preview do WordPress.
Formulário gerado no Live Preview do WordPress
Tudo feito de maneira simples e rápida. Agora vamos analisar outros tipos de campos, como cores e upload de imagens.
Campos de escolha de cores
Os campos de escolha de cores facilitam demais a vida do usuário, já que ele poderá escolher a cor que mais preferir sem ter que ficar buscando códigos de cores HTML pela Internet. Além disso, poderá visualizar alterações em tempo real.
Para gerar um campo de cores, vamos utilizar a mesma seção que estávamos utilizando anteriormente. Apesar de ser possível criar quantas seções você preferir, vamos gerar tudo no mesmo formulário.
Observação: Ao invés de postar o código completo, vou postar apenas o bloco de códigos necessários. Perceba que o trecho de código abaixo deverá ser adicionado dentro da nossa função funcao_do_customizer() .
Veja como adicionar opções de escolha de cores:
// -------------------------------------------------------------------------
// Escolhas de cores
// -------------------------------------------------------------------------
// Setting do campo6
$wp_customize->add_setting(
'campo6', // campo6
array(
'default' => '', // Valor padrão
'transport' => 'refresh', // Transport
)
);
// Controle do campo6
$wp_customize->add_control( new WP_Customize_Color_Control(
$wp_customize,
'campo6',
array(
'label' => 'Label do campo 6',
'section' => 'campos_de_texto',
)
));
O trecho de código acima deverá adicionar um campo para que o usuário escolha uma cor qualquer.
Escolha de cores
Outra parte muito interessante para o nosso formulário, seria permitir que o usuário faça upload de imagens utilizando o customizer API. E não é que isso também é bastante simples, veja na próxima seção.
Upload de imagens com o Customizer API do WordPress
Seguindo o mesmo exemplo do trecho de código anterior, veja como adicionar um campo de upload de imagens dentro do Live Preview do WordPress:
// Setting do campo7
$wp_customize->add_setting(
'campo7', // campo7
array(
'default' => '', // Valor padrão
'transport' => 'refresh', // Transport
)
);
// Controle do campo7
$wp_customize->add_control( new WP_Customize_Media_Control(
$wp_customize,
'campo7',
array(
'label' => 'Label do campo7',
'section' => 'campos_de_texto',
'mime_type' => 'image',
)
));
O trecho de código acima permitirá que o usuário faça upload, remova ou altere imagens diretamente do Live Preview do WordPress.
Upload de imagens dentro do Live Preview
Simples assim!
Mas e agora? Como vou utilizar isso dentro do meu tema? Mais simples do que você imagina, veja na próxima seção.
Utilizando opções do customizer API do WordPress dentro do tema
Para acessar qualquer opção salva dentro do Live Preview pelo customizer API do WordPress, simplesmente utilize a seguinte função:
<?php echo get_theme_mod(campo1); ?>
Nesse caso estou utilizando a função get_theme_mod para pegar o texto diretamente do “campo1” da nossa função. Se você é um desenvolvedor, poderá fazer coisas incríveis utilizando o “Customizer API do WordPress” juntamente com a função get_theme_mod.
Por exemplo, vamos pegar o campo de cor e gerar uma DIV com um background qualquer, veja:
<?php // Obtem a cor ou utiliza #000000 $cor = get_theme_mod(campo6, "#000000"); ?> <div style="width: 100%; height: 100px; background-color: <?php echo $cor; ?>"> </div>
O pequeno trecho de código acima deverá gerar algo parecido com:
Exemplo de utilização do Customizer API do WordPress
Quer um exemplo real?
Se você precisa de um tema que utiliza o Customizer API do WordPress em seu código para realizar personalizações em tempo real do tema, adquira nosso Tema WordPress Premium Letícia no link abaixo:
Além de bonito e elegante, ele também faz uso da API que acabei de descrever no texto acima.
Até o próximo.