Guia do Personalizador de Temas do WordPress

O que é o Personalizador de Temas do WordPress

O sistema de personalização do WordPress conhecido como Personalizador de Temas é uma ferramenta integrada que permite a personalização visual do aspeto do site com pré-visualização das alterações em tempo real. Em vez de modificar o código do tema ou utilizar páginas de definições separadas, o Personalizador disponibiliza uma interface unificada onde vê os efeitos de cada alteração antes de a guardar. É acedido através de Aspeto, Personalizar no painel de administração. Se está apenas a começar, consulte o nosso guia para configurar o WordPress. Se ainda não instalou o WordPress, veja o nosso guia passo a passo do WordPress ou aceda-lhe adicionando /wp-admin/customize.php ao URL do seu site.

O Personalizador foi introduzido no WordPress 3.4 e tem sido continuamente melhorado a cada nova versão desde então. Utiliza AJAX para a comunicação com o servidor e JavaScript para a pré-visualização em tempo real, proporcionando uma experiência de utilizador fluida sem atualizações de página. Todos os temas principais do WordPress e a maioria dos temas de qualidade utilizam o Personalizador para as suas definições.

Anatomia do Personalizador

Painéis, Secções e Controlos

O Personalizador está organizado numa estrutura hierárquica com três níveis. Os painéis são a categoria mais ampla e servem para agrupar secções relacionadas, por exemplo um painel de Cabeçalho que contém secções para logótipo, navegação e barra superior. As secções são grupos de controlos relacionados, por exemplo uma secção de Cores que contém controlos para a cor de fundo, do texto e das ligações. Os controlos são elementos de introdução individuais para definições como seletores de cor, listas pendentes, campos de texto e controlos de carregamento de imagens.

Definições e Transporte

Cada Controlo está associado a uma Definição que estabelece onde o valor é armazenado e como é aplicado. Uma Definição pode armazenar o seu valor na base de dados como theme_mod ou option. O parâmetro Transport determina como as alterações são aplicadas — refresh recarrega a moldura de pré-visualização a cada alteração, enquanto postMessage utiliza JavaScript para aplicação instantânea sem atualização. O postMessage é significativamente mais rápido e proporciona uma melhor experiência de utilizador, mas exige código JavaScript adicional para cada controlo.

Registar secções e controlos

Adicionar uma secção

As secções são registadas no functions.php através do hook customize_register. Invoca o método add_section de $wp_customize com um ID único e um array de parâmetros que inclui title para o nome da secção, description para o texto apresentado no topo da secção, priority para a ordem de apresentação em que números mais baixos significam posição mais elevada, e panel se pretender colocar a secção dentro de um painel. Um exemplo é criar uma secção de definições de cabeçalho com o título Definições do Cabeçalho, uma descrição da função e prioridade 30.

Adicionar definições e controlos

Para cada definição, registe primeiro a definição com o método add_setting, onde especifica o valor predefinido, o tipo de transporte e a função sanitize_callback para validação da introdução. Em seguida, adicione um controlo com o método add_control que define o tipo de controlo, a etiqueta, a secção a que pertence e a prioridade. O WordPress oferece tipos de controlo integrados que incluem text para campos de texto, textarea para texto de várias linhas, checkbox para caixas de confirmação, radio para botões de opção, select para listas pendentes, dropdown-pages para seleção de páginas e number para campos numéricos.

Controlos avançados

O WordPress dispõe de controlos avançados integrados para tipos de dados específicos. O WP_Customize_Color_Control apresenta um seletor de cor com valor hexadecimal, o WP_Customize_Image_Control permite carregar ou selecionar uma imagem da biblioteca de multimédia, o WP_Customize_Cropped_Image_Control acrescenta a possibilidade de recortar imagens para as dimensões pretendidas, e o WP_Customize_Media_Control é um controlo universal para qualquer tipo de multimédia. Para utilizar estes controlos, instancie-os diretamente em vez de invocar add_control com um tipo, porque são classes PHP com parâmetros específicos.

Pré-visualização em direto com postMessage

O lado PHP

Para ativar a pré-visualização em direto sem atualização, defina o parâmetro transport como postMessage na chamada a add_setting. Isto indica ao Personalizador para utilizar JavaScript de modo a aplicar as alterações em vez de atualizar a página inteira. No código de saída do tema, utilize a função get_theme_mod para ler o valor guardado e aplicá-lo ao elemento adequado através de CSS inline ou de uma classe.

O lado JavaScript

Crie um ficheiro JavaScript que carregue apenas na pré-visualização do Personalizador, utilizando o hook customize_preview_init para enfileirar o script. No script, utilize a API wp.customize para detetar alterações nas definições e aplicá-las aos elementos de pré-visualização. Para alterar uma cor, por exemplo, deteta as alterações à definição header_bg_color e atualiza a propriedade CSS do elemento correspondente. Para alterar texto, modifica o innerHTML do elemento. O postMessage proporciona feedback visual instantâneo sem atraso, o que melhora significativamente a experiência de utilizador.

Selective Refresh

O Selective Refresh é uma abordagem híbrida introduzida no WordPress 4.5 que atualiza apenas parte da página em vez da página inteira. Regista um partial com o método add_partial, onde especifica um selector — o seletor CSS do elemento a atualizar — e uma função PHP render_callback que gera novo HTML para esse elemento. Isto é ideal para elementos complexos cujo aspeto depende de várias definições, porque é mais simples do que escrever JavaScript para cada combinação possível de alterações e mais rápido do que uma atualização completa da página.

Validação e sanitização

Sanitize callback

Cada definição tem de ter uma função sanitize_callback que limpa e valida a introdução do utilizador antes de a guardar na base de dados. O WordPress oferece funções integradas para casos comuns que incluem sanitize_text_field para campos de texto, sanitize_email para endereços de e-mail, sanitize_hex_color para cores hexadecimais, absint para inteiros positivos, esc_url_raw para URLs e wp_kses_post para conteúdo HTML com etiquetas permitidas. Nunca armazene a introdução do utilizador sem sanitização, porque isso expõe o site a ataques XSS e outros.

Validation callback

Desde o WordPress 4.6 existe a validate_callback, que pode devolver um objeto WP_Error com uma mensagem de erro apresentada ao utilizador na interface do Personalizador. Ao contrário da sanitize_callback, que corrige silenciosamente valores inválidos, a validate_callback notifica explicitamente o utilizador de que a introdução é inválida. Por exemplo, pode validar que um URL é válido, que um número está dentro do intervalo permitido ou que o texto não excede o comprimento máximo e apresentar uma mensagem de erro adequada.

Painéis e controlos personalizados

Criar um controlo personalizado

Para necessidades que os controlos integrados não cobrem, pode criar um controlo personalizado ao estender a classe WP_Customize_Control. Substitui o método render_content para definir o HTML do controlo e o método enqueue para incluir CSS e JavaScript específicos do controlo. Exemplos de controlos personalizados são um cursor de intervalo com apresentação do valor atual, um interruptor de alternância em vez de uma caixa de seleção, um seletor de Google Fonts com pré-visualização do tipo de letra, um controlo de ordenação de elementos por arrastar e largar e um controlo de configuração de esquema com apresentação visual das opções.

Criar um painel

Os painéis são registados com o método add_panel e são úteis para organizar muitas secções em grupos lógicos. Um tema com muitas definições pode ter painéis para cabeçalho, rodapé, blogue, cores, tipografia e esquema. Cada painel contém várias secções e cada secção vários controlos. Não exagere na profundidade da hierarquia, porque os utilizadores não gostam de clicar através de muitos níveis para chegar a uma definição pretendida.

Definições condicionais

O parâmetro active_callback nas secções e controlos permite apresentar controlos apenas quando determinadas condições são cumpridas. Por exemplo, o controlo da cor do cabeçalho é apresentado apenas se a opção mostrar cabeçalho estiver ativada, as definições do blogue são apresentadas apenas na página do blogue na pré-visualização e as opções do cursor são apresentadas apenas na página inicial. Isto torna a interface mais limpa e menos confusa, porque os utilizadores só veem definições relevantes para o contexto atual.

Integração com temas de Blocos

Com a introdução da Full Site Editing no WordPress 5.9, o Personalizador ganhou uma alternativa sob a forma do Site Editor. Os temas de blocos utilizam um ficheiro theme.json para definir as definições em vez da Customizer API. No entanto, os temas clássicos e os temas híbridos continuam a utilizar ativamente o Personalizador, que permanece uma parte importante do ecossistema WordPress. Se está a desenvolver um tema clássico, o Personalizador continua a ser a forma recomendada de implementar definições de tema com pré-visualização em direto.

Boas práticas

• Utilize o transporte postMessage sempre que possível para pré-visualização instantânea das alterações
• Implemente sempre sanitize_callback para cada definição sem exceção
• Organize as definições logicamente em secções e painéis para facilitar a navegação
• Utilize valores predefinidos sensatos para que o site tenha bom aspeto sem qualquer personalização
• Acrescente descrições às secções e controlos para que os utilizadores compreendam o que cada definição faz
• Teste a pré-visualização em direto em diferentes páginas, porque o comportamento pode variar
• Utilize active_callback para apresentar controlos apenas quando relevantes
• Não acrescente demasiadas definições, porque isso confunde os utilizadores e complica a manutenção

Conclusão

O Personalizador de Temas do WordPress é uma ferramenta poderosa para criar uma interface intuitiva de personalização de temas com pré-visualização em direto. A hierarquia de painéis, secções e controlos permite uma apresentação organizada das definições, o transporte postMessage proporciona feedback visual instantâneo, e a sanitização e validação garantem a segurança dos dados. No alojamento WordPress otimizado, todas as funcionalidades do Personalizador são suportadas com um servidor otimizado para a aplicação rápida das alterações e o funcionamento fiável do site.