Criando opções de tema do WordPress com a API de personalização de temas

Criar opções de tema do WordPress Com a API de personalização de temas é fácil de fazer. Este artigo mostra como isso é feito.

A API de personalização de temas do WordPress foi lançada com o WordPress 3.4, em 2012. Ela prometia aos desenvolvedores uma maneira padronizada de adicionar temas de opções ricas e aos usuários uma maneira de ajustar seu site de maneira amigável.

Para os usuários, o personalizador de temas front-end permite alterar rapidamente a aparência do seu site e até obter uma visualização ao vivo.

O sucesso deste projeto é discutível, mas está sendo aprimorado e está ganhando força. Ele foi construído sobre uma base sólida e não há razão para não começar com ele.

Então, vamos dar uma olhada em como podemos adicionar facilmente configurações a temas usando a API.

Aqui está o que vamos cobrir hoje:

• Construindo nossa base
• Os componentes de uma configuração de tema
• Usando valores de configuração
• Visualizações ao vivo
• Encapsulando em uma classe
• Outras opções

Construindo nossa base

A chave para a API de customização é a classe WP_Customize_Manager , que pode ser acessada através do objeto $wp_customize . Usaremos vários métodos definidos nesta classe para adicionar seções de configurações e controles dentro deles.

A maneira recomendada de criar configurações de tema é encapsulá-las em uma classe. Em nossos exemplos iniciais, não seguirei essa recomendação para garantir que fique claro o que faz parte da API de personalização e o que não é. Vou completar o artigo com uma implementação baseada em classes.

Vamos começar criando uma função no arquivo functions.php do nosso tema, que nos permitirá incluir nossas adições no customizador. Esta função precisa ser conectada ao customize_register.

Os componentes de uma configuração de tema

Conforme mencionado no exemplo, cada item que você adiciona ao personalizador consiste em três partes:

• Uma seção deve ser criada para colocá-lo. Esta seção pode ser uma das pré-existentes, é claro
• Uma configuração deve ser registrada no banco de dados e
• Um controle precisa ser criado que é usado para manipular a configuração definida

Se a separação entre um controle e uma configuração parece confusa, pense assim: Quando você cria uma configuração, você diz ao WordPress que realmente existe uma configuração para a cor da fonte e o valor padrão para isso é #444444. Por si só, isso já significa que essa configuração pode ser usada.

No entanto, o personalizador de temas precisa saber como manipular essa configuração. Você pode criar um campo de texto para ele onde o usuário insere novas cores manualmente como “#ff9900”, mas também pode especificar um controle de cores, que produziria um seletor de cores. Em um nível de banco de dados, tudo ainda se resume a uma cor hexadecimal, mas o lado voltado para o usuário é diferente.

Criando uma seção

O add_section() é usado para criar seções. São necessários dois parâmetros, um slug de seção e um array de argumentos. Aqui está um exemplo de como eu configuro uma seção para opções de rodapé em um tema.

A maior parte disso é bastante auto-explicativo. Observe a prioridade, no entanto! Isso determina a ordem da seção na tela. Eu gosto de incrementar minhas opções em dezenas. Se eu precisar inserir uma seção entre duas seções existentes, não precisarei reindexar tudo, posso apenas atribuir a nova 95.

Observe que as seções não serão exibidas quando vazias. Você deve adicionar uma configuração e um controle a eles antes de serem exibidos.

Adicionando configurações

As configurações são criadas com o método add_setting() . Eles também recebem um slug como o primeiro parâmetro e um array de argumentos como o segundo. Veja abaixo um exemplo de como adicionar uma cor de fundo à nossa seção acima.

Existem várias opções que poderíamos adicionar aqui, mas por enquanto isso funcionará bem. Observe que as configurações não estão vinculadas à seção. Como mencionei, as configurações são simplesmente registradas no WordPress. Cabe aos controles, que estão vinculados a seções para manipulá-los.

Criando um controle

Os controles são implementados com o método add_control() . Este método recebe um slug e um array de argumentos ou também pode receber um objeto de controle dedicado. Um objeto de controle é usado para controles mais complexos, como seletores de cores ou carregadores de arquivos.

Veja como criei o controle que modifica a cor de fundo do rodapé:

Eu passei um objeto de controle para o método add_control() . Esse objeto deve ser construído passando o objeto $wp_customize como primeiro parâmetro, um ID exclusivo para o controle como segundo e uma matriz de argumentos como terceiro.

Observe que o controle é onde tudo vem junto. section é definida com o id da seção que criamos e settings é definido com o id da configuração.

Depois que todos os três forem configurados, você poderá recarregar o personalizador e ver seu trabalho.

Usando valores de configuração

Por padrão, as configurações são salvas em um theme_mod. Theme_mods são uma alternativa à API de Configurações, eles fornecem uma maneira fácil de lidar com configurações específicas do tema. Tudo o que você precisa fazer para recuperar o valor de uma configuração é usar a função get_theme_mod() com o id da configuração passado para ela.

Vamos adicionar um CSS dinâmico ao nosso site conectando-se ao wp_head e usando nossa configuração salva:

Visualizações ao vivo

As visualizações ao vivo das configurações não são habilitadas por padrão. Para usá-los, você deve fazer três coisas:

• Enfileirar um arquivo Javascript que lida com as visualizações
• Adicione suporte de visualização ao vivo para configuração e
• Crie o código Javascript para cuidar de cada configuração

Enfileirando o script de visualização ao vivo

A única coisa irregular sobre esta etapa é que precisamos usar o customize_preview_init e devemos ter certeza de que 'jquery' e 'customize-preview' sejam carregados antes do nosso script. Fora isso, é um enfileiramento padrão apontando para um arquivo javascript em nosso tema:

Adicionar suporte de visualização ao vivo para configuração

Este é bem fácil. Nos argumentos para nossas configurações, precisamos definir uma chave de transport e definir seu valor como postMessage . Vamos revisar nosso código de antes:

Crie o código Javascript para cuidar de cada configuração

Precisaremos usar a função wp.customize() em Javascript. Esta função deve receber o id da configuração como o primeiro parâmetro, o segundo é uma função de retorno de chamada. Dentro nós vinculamos uma função à mudança da configuração e escrevemos nosso código que cuidará da mudança.

De tudo o que precisamos apenas escrever uma linha, use este modelo de copiar e colar para velocidade de gravação de visualização ao vivo:

Encapsulando em uma classe

Encapsular em uma classe é uma boa ideia porque permite que você escreva nomes de função melhores e torne seu código mais compatível com vários temas, caso você tenha vários temas em andamento. Aqui está como eu fiz isso para o nosso exemplo acima.

Note que tudo está exatamente igual, tudo o que mudou foi o nome de algumas funções e estamos nos referindo a métodos dentro da classe ao invés de funções espalhadas pelo nosso arquivo functions.php .

Outras opções

Eu recomendo ler a documentação sobre a API de personalização de temas no WordPress Codex. Ele contém muitas configurações adicionais e maneiras de trabalhar com a API.

• temas gratuitos
• temas premium