Este tutorial mostrará como adicionar configurações de tema, por exemplo, cores de tema, no WordPress Customizer e recompilar a folha de estilo do tema com as variáveis escolhidas. Ao ter um estilo de tema no SCSS usando uma biblioteca, você pode facilmente permitir que os usuários do tema personalizem quaisquer variáveis na folha de estilo do tema, sem que eles tenham que editar os próprios arquivos SCSS.
Qualquer bom tema deve permitir uma boa customização. No mínimo, deve ser possível definir as cores do tema principal. Em vez de escrever muito CSS feio para substituir as cores do tema em todos os lugares, você pode recompilar a folha de estilo completa diretamente do Customizer. Este tutorial vai te ensinar como!
O que faremos – e o que precisamos
Suponho que seu tema já tenha um pouco de estilo nos arquivos SCSS que você já compila no arquivo style.css. E usando SCSS você provavelmente define coisas recorrentes como cores, tamanhos ou pontos de interrupção como variáveis SCSS e usa essas variáveis em todo o seu estilo.
Você pode criar qualquer e quantas configurações do Customizer desejar para as variáveis em seu arquivo SCSS. Colorpickers, números e entradas de texto são perfeitos para isso. Enquanto o usuário altera as configurações no WordPress Customizer, ele verá uma prévia do tema com as variáveis alteradas. E quando eles clicarem em “Salvar", o CSS final será compilado no arquivo CSS da folha de estilo principal usando os valores escolhidos.
Como exemplo para este tutorial, assumirei que o arquivo SCSS da folha de estilo principal do tema faz @importum variables.scssarquivo. Nele definimos três variáveis que queremos que sejam personalizáveis no Customizer: Duas cores e um tamanho de texto em px.
$main: #594c74 !default;
$secondary: #555 !default;
$text-size: 12px !default;Observe que, para permitir que o SCSS redefina variáveis, elas devem ser definidas com !default. Esta é uma regra em SCSS. Para que este tutorial funcione; quaisquer variáveis que você deseja que sejam personalizáveis devem ser definidas como padrão em seus arquivos SCSS.
Cabe a você quando (ou se) deseja substituir o arquivo CSS. Este tutorial assume que quando o usuário clicar em “Salvar” no Customizer, ele irá recompilar e gravar no CSS do tema. No entanto, enquanto a visualização do Customizer estiver ativa e o usuário estiver alterando as configurações (antes de clicar em Salvar), simplesmente enviamos o CSS compilado no cabeçalho para a visualização do site. Não queremos substituir o arquivo CSS imediatamente caso o usuário queira cancelar as alterações feitas.
Tenha em mente…
Este tutorial substituirá o arquivo do tema style.csssempre que as configurações do Personalizador forem salvas.
Suponho que você já compile seus arquivos SCSS com um programa compilador (por exemplo, Koala ou linha de comando). Ter esse código em seu tema substituirá o arquivo CSS, mas não alterará seus arquivos SCSS de origem. Isso significa que sempre que você fizer alterações no Customizer e depois voltar para seus arquivos SCSS originais e recompilar, suas configurações de Customize serão perdidas!
Existem vários métodos para contornar isso e depende do seu projeto e de como você trabalha. Na maioria dos casos não seria um problema. Geralmente é apenas uma coisa a ter em mente enquanto você está desenvolvendo seu tema. Se você está dando seu tema finalizado para outra pessoa usar, eles normalmente não tocariam em seus arquivos SCSS de qualquer maneira.
Com isso fora do caminho, vamos começar a analisar como fazemos isso:
- Familiarizando-se com a biblioteca SCSSPHP e incluindo-a em nosso tema
- Crie configurações do Customizer para cada variável SCSS que queremos que seja personalizável
- Certificando-se de que o Personalizador visualiza as alterações em movimento
- Ao salvar as configurações do Customizer, recompilamos e sobrescrevemos o arquivo CSS do tema.
1 A biblioteca SCSSPHP
Para compilar os arquivos SCSS, usaremos uma biblioteca SCSSPHP da leafo (licença MIT). Observe que este tutorial é para a biblioteca SCSS. O autor da biblioteca tem uma biblioteca LESS PHP semelhante se você preferir usar LESS, mas lembre-se de que o tutorial a seguir é para a biblioteca SCSS.
A biblioteca SCSSPHP é realmente simples de usar! Aqui está uma visão geral simplificada de como usaremos a biblioteca no PHP do nosso tema:
- Incluímos a biblioteca
- Crie uma nova instância da classe do compilador da biblioteca
- Carregar o conteúdo do arquivo SCSS de origem e passá-lo para o objeto do compilador
- Defina um array associativo; Nomes de variáveis SCSS (incluindo o
$) como chaves e seus valores. Qualquer elemento nesta matriz substituirá as variáveis de mesmo nome no arquivo SCSS fornecido. - Pedimos ao objeto compilador para compilar e receber o CSS compilado como uma string em troca. Podemos então produzir este CSS dentro
headou podemos escrevê-lo nostyle.cssarquivo do tema
Que tipo de variáveis SCSS podemos compilar?
A resposta simples é: Qualquer tipo de variável SCSS válida!
A biblioteca SCSSPHP pode compilar qualquer tipo de variável SCSS válida, mas lembre-se de que você deve certificar-se de que elas sejam formatadas corretamente no Customizer. Por exemplo, as cores precisam ser prefixadas com um #para cores hexadecimais ou ser formatadas como rgb()ou rgba()definições. Uma variável de tamanho normalmente precisaria ser anexada com ‘ px‘, ‘ em‘, ‘ %‘ e assim por diante.
Se você planeja fazer um sistema avançado para compilar variáveis SCSS através do tema Customizer, certifique-se de ter um bom sistema para formatar corretamente cada tipo de variável!
Vamos dar o primeiro passo; baixando e incluindo a biblioteca em nosso tema:
Baixando e incluindo a biblioteca SCSSPHP em seu tema
O primeiro passo é baixar a biblioteca SCSSPHP. Na página vinculada, clique no botão "Download" no topo. Se você preferir usar o Composer, o site fornece um guia sobre isso.
Extraia o zip em uma subpasta em algum lugar dentro do seu tema. Como exemplo, estou colocando-o dentro da theme/inc/scssphp/pasta.
Abra o arquivo PHP onde você deseja adicionar seu código para compilar. Pode estar diretamente dentro do seu tema functions.phpou em um arquivo PHP incluído por functions.php. Para simplificar, estou escrevendo tudo dentro do functions.php.
Antes de podermos usar a biblioteca, precisamos incluí-la; igual a:
require_once(get_stylesheet_directory(). '/inc/scssphp/scss.inc.php');Ajuste o caminho para seus arquivos de acordo. Precisamos incluir o scss.inc.phparquivo encontrado dentro da pasta raiz da biblioteca. Agora, após esta linha podemos usar as classes da biblioteca!
2 Criando as configurações do Customizer para as variáveis SCSS
Vamos criar as configurações do WordPress Customizer para nossas variáveis. Para fins do tutorial, adicionaremos configurações para as variáveis SCSS mencionadas acima: dois colorpickers e uma entrada numérica.
Não entrarei em detalhes explicando como adicionar configurações do Customizer – existem muitos tutoriais para isso. No exemplo de código abaixo eu crio uma nova seção e coloco as três configurações dentro:
Este código se conecta customize_registere adiciona uma seção chamada “Variáveis de Tema”. Em seguida, ele adiciona um seletor de cores ‘ theme-main‘, outro seletor de cores ‘ theme-secondary‘ e uma entrada numérica ‘ theme-text-size‘. Esta é toda a funcionalidade padrão do WordPress. Eu também adiciono definir o padrão de cada configuração para os mesmos valores definidos no variables.scssarquivo. Isso é apenas para garantir que as configurações do Personalizador sejam iniciadas com as cores corretas.
Está ótimo! Mas a partir de agora nada acontece quando você ajusta essas variáveis. Vamos continuar com o passo 3; manipulação de visualização no Customizer.
3 Compile CSS em movimento na visualização do Customizer
Esta etapa trata da atualização da visualização do Personalizador enquanto o usuário altera as configurações e não grava em nenhum de nossos arquivos. Em vez disso, enviaremos o CSS compilado na <head>visualização dentro de uma <style>tag. Dessa forma, garantimos que o CSS inline substitua todo o estilo do arquivo CSS original.
Para verificar se estamos ou não usando a visualização do Customizer, usamos a função [is_customize_preview](https://developer.wordpress.org/reference/functions/is_customize_preview/)(). Quando isso retorna true, criamos uma função vinculada ao wp_head. Dentro da função, iniciamos e configuramos a biblioteca SCSSPHP, buscamos os valores de configuração atuais, compilamos o CSS e o enviamos em uma <style>tag.
Na linha #7definimos o caminho para o arquivo SCSS de origem e carregamos seu conteúdo em uma variável em #8. E na linha #9e #10configuramos o caminho de importação para a biblioteca para garantir que qualquer @imports funcione corretamente em nossos arquivos SCSS. Você pode ler mais sobre isso no site de documentação da biblioteca, sob o título “Import Paths”. Basicamente, a biblioteca SCSSPHP precisa saber o caminho relativo da sua pasta SCSS para que todos os @importcaminhos estejam corretos.
Na linha #12-16criamos o array para o compilador; uma matriz associativa com os nomes das variáveis como chaves. Para os valores que usamos [get_theme_mod](https://developer.wordpress.org/reference/functions/get_theme_mod/)()para obter os valores do Customizer. A função get_theme_mod()permite definir um padrão como segundo parâmetro se o valor não foi salvo. Isso nos poupa de travar o compilador com valores como null. Portanto, fornecemos o mesmo padrão de nosso arquivo de variáveis SCSS e quando registramos as configurações do Personalizador.
Observe também que o código na linha #15anexa um ‘ px‘, garantindo que o valor real da variável seja válido. Caso contrário, compilaria como ” $text-size: 12;” quando precisarmos de ” $text-size: 12px;“. Fornecemos o array de variáveis para o compilador em line #17, dizendo para compilar usando essas variáveis.
Então na linha #19-22chamamos a compile()função que deve retornar o CSS compilado como uma string. Nós produzimos uma <style>tag com a string CSS dentro. Como estamos viciados em wp_head, o Personalizador renderizará a visualização com o CSS alterado toda vez que uma alteração for feita.
4 Salvando o CSS compilado na folha de estilo do tema
O código para compilar o CSS é muito semelhante ao da etapa anterior. A única diferença é que agora estamos escrevendo o CSS em um arquivo em vez de emiti-lo. Você realmente deveria considerar colocar isso em uma função para que você não repita o código, mas por uma questão de clareza eu escolhi separar os dois.
Nós nos conectamos a [customize_save_after](https://developer.wordpress.org/reference/hooks/customize_save_after/)quais gatilhos sempre que alguém clica em Salvar no WordPress Customizer. Neste ponto, buscamos o SCSS de origem, definimos os valores das variáveis e compilamos em CSS. Com a string CSS, usamos uma função PHP simples para gravá-la no arquivo CSS do tema.
A única diferença de antes está na linha #8onde definimos o arquivo de destino para gravar e na linha #19onde gravamos no arquivo.
Conclusão
Agora temos configurações do Customizer que controlam as variáveis no arquivo SCSS do tema e sobrescrevem a folha de estilo principal do tema usando essas variáveis. Não há limite para quantas ou que tipo de configurações você deseja permitir que os usuários do tema personalizem! Invista algum tempo na configuração de um sistema adequado para lidar com a formatação de diferentes tipos de variáveis (por exemplo, prefixos ou pós-fixos) e estruturar adequadamente as configurações do Customizer. Os usuários do tema apreciarão a flexibilidade e a facilidade de personalizar seu tema!
Você também pode descobrir diferentes maneiras de lidar com a gravação do arquivo do CSS final. Se você não quiser sobrescrever a folha de estilo principal, talvez queira enviá-la para um arquivo diferente. Você também pode usar condicionais if-else no SCSS.
Este tutorial foi escrito para fornecer um trampolim sobre como você pode personalizar seu tema do WordPress no Customizer. Deixe-me saber se foi útil para você – ou se você quer um tutorial mais avançado que garanta que a folha de estilo do tema não seja substituída!