Desenvolvimento de temas Wordpress

Anotações úteis para o desenvolvimento de temas Wordpress.

Recursos úteis para desenvolvimento Wordpress

image-1654875811504.png

Aplicativos

Servidores e ambiente

Para simular o funcionamento do Wordpress no ambiente de desenvolvimento local é necessário instalar aplicativos que irão atuar como servidores, pois como o Wordpress é feito em PHP, ele não pode ser executado localmente sem estes recursos.

Alguns exemplos de servidores que vem com um pacote completo necessário para rodar o Wordpress, instalar o banco de dados MySQL e administrá-lo através do PHPMyAdmin. 

Se a escolha for não fazer toda esta configuração de servidores locais, uma boa opção é o aplicativo Local WP, que literalmente pode fazer quantas instalações do Wordpress forem solicitadas através de um botão e poucas configurações adicionais.

A minha favorita é criar ambientes com Docker e Docker-Compose:

Editores de texto
Wordpress e documentação


Repositório deste projeto no GitHub

Se você está habituado a utilizar o GitHub, poderá acompanhar este projeto de estudo e baixá-lo no seu repositório do tema.

 

Ambiente de desenvolvimento com Docker Compose

Como o tema desenvolvimento não é o foco do meu conteúdo, mas o design em si, eu vou recomendar um vídeo que mostra na prática como configurar o ambiente Docker para o Wordpress. E mais abaixo vou disponibilizar a configuração que eu uso para desenvolvimento local.

Como configurar o ambiente de desenvolvimento com Docker para Wordpress

Minha configuração local

Para a minha configuração local, eu criei um documento docker-compose.yml com as seguintes configurações:

O repositório completo já está configurado com variáveis de ambiente.

Se você não sabe trabalhar com variáveis de ambiente, junto ao repositório eu envio um arquivo .env.example. Basta renomear para .env e preencher os campos que faltam. O arquivo deve estar na mesma pasta que o docker-compose.yml.

Dentro da pasta do repositório tem a pasta configs onde eu guardo algumas configurações importantes para o Wordpress, como a quantidade permitida para uploads de arquivos.

Acesse o repositorio.

Como preparar o Wordpress para o desenvolvimento?

Configurando WP_DEBUG para TRUE

Esta opção poderá ser ativada no arquivo wp_config.php que é gerado no momento da instalação na pasta raiz do sistema.

Na linha 72 ou perto dela estará uma constante PHP chamada "WP_DEBUG" que estará definida com false. Devemos mudar para true.

image-1654878022417.png

Lembrando que esta opção somente deve estar ativada no ambiente de desenvolvimento. Em produção a instalação deverá estar como false.

Ao manter esta opção com true, o sistema irá exibir informações na tela quando houver algum erro de código.

OBS: Se você fez a instalação usando o meu arquivo docker-compose.yml basta preencher a variável de ambiente no arquivo .env na hora de rodar o comando do Docker Compose.

Alguns plugins úteis para desenvolvimento Wordpress

 

Estrutura do sistema

Estrutura do sistema

Como está organizado o banco de dados do Wordpress?

Ao instalar o Wordpress, ele cria por padrão algumas tabelas necessárias no banco de dados MySQL. Esta é uma imagem do PHPMyAdmin, um sistema de gerenciamento de bancos de dados MySQL com as tabelas geradas pelo Wordpress em sua instalação.

image-1654869740275.png

Descrição das tabelas

Posts, Páginas e Menus
Termos e taxonomias
Configurações
Usuários
Comentários

Documentação oficial: Database Description

Estrutura do sistema

Como funciona a hierarquia de tema Wordpress?

Hierarquia de modelos Wordpress

image-1654895750390.png

O diagrama acima pode até parecer assustador, mas não é. Funciona assim:

OBS: Atualizado para a versão 6.0 em diante (10/06/2022)

Na primeira coluna a esquerda, temos basicamente os tipos de conteúdo de um tema Wordpress que são:

Para entender o esquema de cores deste diagrama leve em conta esta parte da tabela:

image-1654896215754.png

Agora vamos a explicação...

Como funciona?

Apenas para exemplificar o básico, vamos mencionar as situações principais que podem ser percebidas neste diagrama:

Seguindo estes exemplos acima, é possível entender toda a hierarquia de modelos nos temas Wordpress.

Documentação oficial: Hierarquia de Arquivos de Tema WordPress

Estrutura do sistema

Como começar a criar um tema Wordpress?

O básico para começar a criar um tema, após todas as configurações de ambiente estarem implementadas e o Wordpress já instalado em um servidor local, devemos acessar a pasta dos temas.

Hierarquia de pastas do Wordpress

Dentro da pasta de temas (/wp_content/themes) o básico para começar será:

Apensa com isso já é possível visualizá-lo na área de temas do sistema e ativá-lo.

image-1654900138244.png

Mas é claro que não vamos conseguir ver nada na frente do site, porque estamos apenas começando.

Após isso deve colocar um arquivo chamado screenshot.png com o tamanho de 1200x900px na pasta raiz. Esta será a capa do tema.

image-1654900509689.png

Nada mal não é? Depois de colocar este arquivo screenshot.png e ativá-lo, veja como ficou. Note também que o Wordpress está exibindo o nome do tema como o nome da pasta que eu criei.

A seguir, o mais recomendado é modelar o front do site em um arquivo HTML. Depois, com o modelo pronto, podemos destrinchá-lo e ajustar aos padrões do Wordpress para deixá-lo dinâmico.

Estrutura do sistema

Como preencher as informações do tema

Acesso o codex Wordpress e busque por: Theme Stylesheet

image-1654901251607.png

Copie todas estas informações em forma de comentário. O Wordpress irá ler estes comentários e estas informações serão as informações do seu tema.

Copie e cole na sua folha de estilo (style.css). O exemplo a seguir é apenas com a finalidade de demonstração. Eu recomendo que você acesse o link acima e copie diretamente da documentação oficial, para se certificar de que estará utilizando o código mais atual.

/*
Theme Name: Twenty Thirteen
Theme URI: http://wordpress.org/themes/twentythirteen
Author: the WordPress team
Author URI: http://wordpress.org/
Description: The 2013 theme for WordPress takes us back to the blog, featuring a full range of post formats, each displayed beautifully in their own unique way. Design details abound, starting with a vibrant color scheme and matching header images, beautiful typography and icons, and a flexible layout that looks great on any device, big or small.
Version: 1.0
License: GNU General Public License v2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html
Tags: black, brown, orange, tan, white, yellow, light, one-column, two-columns, right-sidebar, flexible-width, custom-header, custom-menu, editor-style, featured-images, microformats, post-formats, rtl-language-support, sticky-post, translation-ready
Text Domain: twentythirteen

This theme, like WordPress, is licensed under the GPL.
Use it to make something cool, have fun, and share what you've learned with others.
*/

  E veja como fica depois que eu colei na minha folha de estilo e preenchi com os dados corretos:

image-1654902869440.png

Desenvolvimento do layout

Desenvolvimento do layout

Bootstrap e estilização no Wordpress

Para começar a projetar o tema vou utilizar o Bootstrap na versão 4.6.

Depois disso, irei usar uma personalização do Bootstrap através do site Bootswatch.

Como instalar o Bootstrap no meu tema

Para isso eu preciso copiar a folha de estilo do Bootstrap que eu posso copiar direto do site, ou baixar e linkar direto da minha pasta do tema. Para este projeto eu preferi linkar direto com o servidor Bootstrap seguindo as orientações do próprio site do Bootstrap (neste link):

image-1654903726688.png

Clicando em "Copy" e adicionando no cabeçalho do meu arquivo index.php antes do fechamento da tag </head>. Ficou assim:

image-1654903967101.png

Também precisamos adicionar a biblioteca JQuery, Popper e o arquivo JavaScript do próprio Bootstrap. Estes nós adicionamos ao final antes de fechar a tag </body>. Veja a documentação:

image-1654904262535.png

E como ficou no código do tema:

image-1654904322868.png

Agora já estamos prontos para utilizar o Bootstrap no tema Wordpress, mas antes vamos personalizar o tema.

Personalizando o Bootstrap com o Bootswatch

Acesse o Bootswatch (clique aqui) e escolha uma das opções de personalização que ele oferece na sua página. Eu escolhi o tema Vapor, que eu achei bem estiloso. Você pode baixar a opção bootstrap.min.css pois já está minificada e isto ajuda no desempenho.

image-1654904743484.png

Daí, crie uma pasta /css e dentro dela o arquivo que foi baixado, daí é só chamá-lo no cabeçalho do index.php desta forma: 

image-1654904975039.png

Agora sempre que quiser usar um componente Bootstrap, procure na aba Components do site do Bootstrap 4.6.

image-1654905084208.png

Todo o processo de desenvolvimento de layout deste tema será baseado no Bootstrap, então se você for acompanhar todo o desenvolvimento deste projeto, siga estas etapas para que você possa utilizar os mesmos componentes CSS.

Um DETALHE IMPORTANTE sobre folhas de estilo em pastas locais

Apenas por chamar a folha de estilo como na imagem acima, relacionada à instalação do Bootswatch, não irá trazer automaticamente a estilização no tema. Isto porque, como o arquivo está dentro da pasta do tema, nós precisamos usar uma função que irá identificar a pasta do tema como sendo a pasta raiz e o caminho relativo até a folha de estilo como o caminho que você apontou em seu arquivo index.php. Quando começarmos a usar as funções do Wordpress para deixar o tema dinâmico veremos como fazer esta configuração. 

Mostro isso na prática nesta página.

Desenvolvimento do layout

HTML da página principal

Para começar a construir o tema Wordpress, eu escrevi um código simples para a página principal do site. No arquivo index.php que se encontra na pasta raiz do tema (para tirar qualquer dúvida sobre a estrutura de pastas de um tema Wordpress consulte esta página). Eu simplesmente simulei o que seria o cabeçalho do site, o rodapé, os menus e as áreas em que entrarão os widgets do Wordpress.

Para o corpo da página, eu fiz uma divisão simples de barra lateral usando as próprias classes do Bootstrap 4.6. 

Segue o exemplo:

<!DOCTYPE html>
<html lang="pt-BR">

<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@4.6.1/dist/css/bootstrap.min.css" integrity="sha384-zCbKRCUGaJDkqS1kPbPd7TveP5iyJE0EjAuZQTgFLD2ylzuqKfdKlfG/eSrtxUkn" crossorigin="anonymous">
    <link rel="stylesheet" href="css/bootstrap.min.css" />
    <title>Wordpress Dev</title>
</head>

<body>
    <header>
        <div class="container">
            <div class="row">
                <div class="col py-5 text-center">
                    <h1 class="mb-4">Wordpress Dev</h1>
                    <p>Projeto público de desenvolvimento de temas para o Wordpress</p>
                </div>
            </div>
        </div>
        <nav class="navbar navbar-expand-lg navbar-dark bg-dark">
            <button class="navbar-toggler mx-auto" type="button" data-toggle="collapse" data-target="#navbarPrincipal" aria-controls="navbarPrincipal" aria-expanded="false" aria-label="Toggle navigation">
                <span class="navbar-toggler-icon"></span>
            </button>

            <div class="collapse navbar-collapse" id="navbarPrincipal">
                <ul class="navbar-nav mx-auto">
                    <li class="nav-item">
                        <a class="nav-link" href="#">Menu 1</a>
                    </li>
                    <li class="nav-item">
                        <a class="nav-link" href="#">Menu 2</a>
                    </li>
                    <li class="nav-item">
                        <a class="nav-link" href="#">Menu 3</a>
                    </li>
                </ul>
            </div>
        </nav>
    </header>

    <main>
        <div class="container">
            <div class="row py-5">
                <div class="col-md-9">
                    <article>
                        <h4>Este é o título de um artigo</h4>
                        <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris ullamcorper tellus in dolor mollis sagittis. Morbi at nibh lectus. Fusce tempor vel ipsum vitae maximus. Nulla eu placerat sapien. Fusce dignissim lectus sit amet quam condimentum, nec tempus massa auctor. Morbi suscipit blandit quam, ac aliquet tortor fermentum et.</p>
                    </article>
                </div>
                <div class="col-md-3">
                    <div class="widget mb-3">
                        <p>Este é um Widget</p>
                    </div>
                    <div class="widget mb-3">
                        <p>Este é um Widget</p>
                    </div>
                </div>
            </div>
        </div>
    </main>

    <footer class="bg-dark w-100">
        <div class="container">
            <div class="row py-5 text-light">
                <div class="col-md-4">
                    <h6>Widget 1</h6>
                </div>
                <div class="col-md-4">
                    <h6>Widget 2</h6>
                </div>
                <div class="col-md-4">
                    <h6>Widget 3</h6>
                </div>
            </div>
        </div>
        <div class="container border-top text-center text-light py-3">
            <p class="mb-0">
                <small>
                    Tema de estudo Wordpress | Desenvolvido por <a href="https://wiki.phototricks.art.br/books/desenvolvimento-de-temas-wordpress" target="_blank" class="text-light"><b>Phototricks</b></a>
                </small>
            </p>
        </div>
    </footer>

    <script src="https://cdn.jsdelivr.net/npm/jquery@3.5.1/dist/jquery.slim.min.js" integrity="sha384-DfXdz2htPH0lsSSs5nCTpuj/zy4C+OGpamoFVy38MVBnE+IbbVYUew+OrCXaRkfj" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@4.6.1/dist/js/bootstrap.bundle.min.js" integrity="sha384-fQybjgWLrvvRgtW6bFlB7jaZrFsaBXjsOMm/tB9LTS58ONXgqbR9W8oWht/amnpF" crossorigin="anonymous"></script>
</body>

</html>
Desenvolvimento do layout

Inserindo as primeiras funções PHP no Wordpress

Para que o tema fique dinâmico e traga informações que foram inseridas através do painel de administração do Wordpress, é preciso inserir algumas funções PHP que já vem por padrão do Wordpress. Não é necessário ter conhecimento em PHP para trabalhar com estas funções. Eu por exemplo, não sou desenvolvedor PHP. 

No entanto se você já tem conhecimento desta linguagem se sairá bem melhor.

Funções que vamos utilizar

"wp_head": esta função inserimos antes do fechamento da tag </head>. Esla injeta no nosso código algumas folhas de estilo, scripts e outras informações que vem do Wordpress, Como o título do site e as meta tags. Isso quer dizer, que se você instalar algum plugin que precisa acessar o cabeçalho do seu site, para trabalhar o SEO, por exemplo, como o Yoast SEO, ele terá acesso através desta função. Assim o trecho de código que estava usando até agora: <title>Wordpress Dev</title>, não será mais necessário, pois essa informação virá de forma dinâmica da administração.

Veja como inserir esta função:

image-1655411884440.png

"wp_footer": o mesmo se aplica ao rodapé do site. Para que ele receba conteúdo de plugins e outras informações do tema, necessitamos usar esta função, logo antes de fechar a tag </body>. 

Veja como ficou no meu código:

image-1655412443747.png

"language_attributes": trás as opções de idioma que o administrador selecionou nas opções do Wordpress. Esta se usa dentro das opções da tag de abertura do html: <html > como na imagem abaixo:

image-1655412703057.png 

"blog_info": esta função é utilizada com parâmetros adicionais. Ela é bastante utilizada, pois ela trás informações úteis sobre o nosso site. Alguns exemplos de parâmetros:

image-1655413144542.png

image-1655413384383.png

Injetando funções PHP no código

Se você não está familiarizado com PHP, entenda como injetar as funções no tema Wordpress:

Desenvolvimento do layout

Hooks (ganchos) do Wordpress

Quando o site Wordpress está carregando, ele vai executando alguns eventos dentro da sua programação. Esses eventos são o que determina o seu funcionamento e a ordem em que ocorrem as execuções no sistema. 

Nós podemos alterar os arquivos do sistema Wordpress em si, porém, toda vez que ele atualizar, ele irá sobrescrever os seus arquivos de sistema, ou seja, os que estão na pasta raiz e que carregam o sistema em si. No caso, o core do sistema, o Wordpress puro, sem contar a pasta de conteúdo, arquivos, plugins instalados e temas, que fica em /wp-content.

Assim, uma forma de acessar o sistema de dentro da pasta do tema que estamos criando, é por meio dos hooks ou ganchos, que permanecem inalterados, mesmo como atualizações e reinstalações do Wordpress.

Veja a documentação oficial dos hooks Wordpress.

Como usar os hooks

Até a versão 6 os hooks podem ser do tipo 'action' ou 'filter'. Esta é a sintaxe para usá-los:

add_action( 'nome-da-action', 'funcao-a-executar', 'prioridade', 'argumentos' );

Acima, um exemplo de action. A estrutura de um filter seria a mesma, com a diferença de que a função a ser executada sempre deve retornar um valor, e sempre vai esperar ao menos um argumento para sua execução.

add_filter( 'nome-da-action', 'funcao-a-executar', 'prioridade', 'argumentos' );

Para este momento, o único que vamos fazer é criar um arquivo na pasta raiz do tema com o nome de functions.php. Este arquivo é padrão para temas Wordpress, e será aqui que vamos configurar as funções do tema.

O arquivo functions.php

Os primeiros hooks que eu adicionei no arquivo de funções do tema, são algumas configurações básicas iniciais que todo o tema Wordpress deve ter. Para isso eu adicionei a action que trás uma função de carregamento junto com o tema, after_setup_theme. Com este hook eu consigo chamar uma função que eu criei, chamada de phototricks_setup_theme, em que eu adiciono todo o suporte ao tema através de várias outras funções padrão do Wordpress. Veja o código com a explicação de cada uma das funções:

<?php // Abre a tag PHP

function phototricks_setup_theme() { // Minha função personalizada
    $supports = [
        'search-form',
        'comment-form',
        'comment-list',
        'gallery',
        'caption'
    ]; // Array com algumas tags do html 5 que eu quero que o meu tema tenha suporte
    add_theme_support('html5', $supports); // Suporte para html 5
    add_theme_support('title-tag'); // Quero usar a tag title no título das páginas do site (dentro da <head>)
    add_theme_support('post-thumbnails'); // Suporte para adicionar imagens de capa nas páginas e posts
    add_theme_support('automatic-feed-links'); // Geração automática de links para leitores de Feed RSS

    $GLOBALS['content_width'] = 1130; // Largura total do conteúdo, para o ajuste de imagens e vídeos incorporados
}

add_action('after_setup_theme', 'phototricks_setup_theme'); // Chamada da função personalizada com as configurações de suporte do tema

function phototricks_enqueue_scripts() {
    wp_enqueue_style('phototricks-style', get_stylesheet_directory_uri() . '/css/bootstrap.min.css'); // Adição dinâmica da folha de estilo personalizada do tema
}

add_action('wp_enqueue_scripts', 'phototricks_enqueue_scripts'); // Chamada para a função de configuração da folha de estilo personalizada

Veja que agora, tornamos o carregamento da folha de estilo dinâmica, assim finalmente, o tema não está somente acessando o Bootstrap 4.6 online, mas também o arquivo local de estilização do Bootstrap que está na pasta css do tema:

image-1655477353203.png

Desenvolvimento do layout

Adicionando suporte para vários idiomas (internacionalização) no tema Wordpress

Em resumo o que devemos fazer é criar vários pacotes de idioma para que o tema possa ser apresentado em vários idiomas, conforme a configuração do sistema.

Nós fazemos isso por meio de algumas configurações no arquivo functions.php, por chamadas de funções PHP no html do site e com a ajuda de um plugin que irá gerar as tabelas de tradução numa pasta do tema que definiremos para isto.

Configurações no functions.php

Até agora, eu já criei uma função no arquivo functions.php que carrega configurações de suporte do Wordpres no tema. Você pode verificar isso aqui. Dentro desta função, eu vou adicionar uma outra função padrão que dirá para o Wordpress qual é o domínio do meu tema. Ele deve ser uma palavra exclusiva que identifique o tema que estamos fazendo para o Wordpress.

Para isso vou começar fazendo um ajuste no style.css da pasta raiz do tema. No comentário que colocamos neste arquivo tem uma entrada Text Domain: que eu vou ajustar para phototricks. Já vai ficar claro o porquê disso.

image-1655474918963.png

Agora, vou adicionar a função de internacionalização no carregamento do tema. Ela ficou assim:

load_theme_textdomain( 'phototricks', get_template_directory() . '/languages' );

A função load_theme_textdomain informa ao Wordpress qual é o domínio do tema e vincula o tema à sua pasta de traduções. A função get_template_directory trás o caminho da pasta raiz do tema, assim eu concatenei com a pasta /languages que eu criei para guardar as traduções. Veja como ficou a função:

image-1655475724629.png

Para mais informações eu criei esta função na página de hooks.

Aplicando as traduções

Vamos traduzir o texto que eu inseri no rodapé do site: "Tema de estudo Wordpress | Desenvolvido por Phototricks".

No lugar onde está o texto que eu quero que haja várias traduções, no arquivo index.php, vou substituir pelo seguinte código:

<?php _e( 'Wordpress Study Theme | Developed by', 'phototricks' ); ?> // O texto default em inglês, seguido do domínio do tema (o mesmo em functions.php e style.css)

Agora, no rodapé do site, eu já verei o texto default, em inglês. Veja:

image-1655475938859.png

Adicionando os pacotes de tradução

Vou usar o plugin Loco Translate para gerar automaticamente os pacotes de tradução. 

Após instalado eu entro na página do plugin, seleciono temas e seleciono o meu tema. Daí, eu clico em Criar modelo. Veja abaixo:

image-1655476195188.png

Isso vai fazer com que ele crie um modelo de tradução na pasta que já configuramos, a pasta /language. Veja:

image-1655476393954.png

Agora, voltamos às configurações deste plugin e escolhemos a opção Novo idioma.

image-1655476497487.png

Escolhemos o idioma que vamos inserir, e no local do arquivo escolhemos a opção de tema, pois dessa forma, quando o tema for finalizado, as opções de idioma estarão dentro de sua pasta. Quando ele for instalado em outro local, levará junto estas configurações.

image-1655476661535.png

Agora eu posso procurar os textos que marcamos com o domínio 'phototricks' e criar as traduções. Veja que o texto do rodapé já aparece aqui, agora, basta inserir o texto traduzido:

image-1655476920388.png

Agora, para todos os trechos de texto que eu quero que estejam sincronizados com a tradução do Wordpress, eu tenho que seguir o mesmo padrão que eu usei no texto do rodapé do site.

Desenvolvimento do layout

Adicionando Widgets ao tema Wordpress

Em breve