Desenvolvendo para WordPress com Twig: Passos Iniciais

Portuguese (Português) translation by Erick Patrick (you can also view the original English article)

Agora entendemos que o Twig—junto do plugin Timber para WordPress—pode ajudar desenvolvedores a escrever código modular ao criar temas para WordPress. Com essa abordagem modular, você pode lidar com a lógica e a visualização da sua aplicação web de forma separada. Pulemos para algo mais técnico: criar modelos Twig, converter arquivos HTML em Twig, e como renderizar os dados ou lógica com modelos do Twig.

Instalando Timber

Antes de tudo, instalaremos o Timber, um plugin para WordPress que ajuda a integrar o mecanismo de modelos Twig no WordPress. Então, façamos isso.

Acesse o painel da sua instalação WordPress.
Acesse Plugins > Adicionar Novo.
Procure por Timber plugin.
Instale e ative o plugin.

Quando o Timber estiver instalado, podemos dividir os arquivos de modelos em arquivos de dados e de visualização.

Criando um Modelo do Twig

Antes de começarmos a criar modelos de Twig, assumirei que você tem um ambiente de desenvolvimento local. Para esse tutorial, meu ambiente é:

Uma instalação local do WordPress (estou usando o DesktopServer, da ServerPress).
O plugin Timber instalado e ativado.
Opcional: Qualquer tema base/inicial (estou usando o meu próprio, o Neat).

UpStatement também construiu um Tema Inicial para o Timber.

Comecemos. Quero mostrar uma mensagem de boas vindas no topo da minha página inicial. Como eu faria sem o Twig? Provavelmente, incluiria algum código HTML em um arquivo PHP e imprimiria a mensagem, como no código abaixo. Meu arquivo index.php seria algo mais ou menos assim.

<?php
/**
 * Homepage
 */
get_header(); ?>

    <div> <?php echo "Welcome to my blog!"; ?> </div>

<?php get_footer(); ?>

Agora a página inicial da minha instalação de WordPress mostra a mensagem no canto direito superior. Eis uma captura de tela.

Problema

O problema dessa abordagem é que misturamos dados com lógica na visão. Quão mais complexo o arquivo ficar, mais difícil será de mantê-lo e entendê-lo—por exemplo, ao adicionar um loop do WordPress com alguns argumentos, filtros e paginação. Além disso, PHP dentro de HTML não é tão legal quando você tem certa quantidade de lógica nele.

Abordagem Modular

Para torná-la mais modular, podemos pensar no conteúdo da nossa página inicial na forma de blocos ou componentes. Pode ter dois, por padrão, as publicações vindas do The_Loop e a paginação. Como queremos adicionar um componente ao topo—a mensagem de boas vindas—criemos um arquivo Twig para ele.

Crie um novo arquivo em branco no seu editor, copie e cole o código abaixo.

1	<!-- Welcome Template -->
2	<section class="welcome_message">
3	<h2>Welcome to my website!</h2>
4	</section>

Crie um novo diretório na raiz do seu tema, chamado views e salve o arquivo com a extensão .twig. Por exemplo, salvei o arquivo como welcome.twig.

Renderizando o Modelo do Twig

Timber provê-nos com algumas funções úteis, como a função render. Você pode invocá-la dessa forma:

1	Timber::render();

Essa função pode receber até quatro argumentos. Como está fora do escopo desse artigo, você pode ler mais sobre na documentação do Timber. Podemos passar para essa função o nome de qualquer arquivo Twig do diretório views do seu tema.

Renderizemos a mensagem no arquivo index.php.

<?php
/**
 * Homepage
 */
get_header();

    // Timber Render.
  Timber::render( 'welcome.twig' );

get_footer();

Timber renderiza o arquivo welcome.twig, carrega o HTML e mostra a camada de visão modificada, no front-end, dessa forma:

A função render() leva como argumento welcome.twig e, automaticamente, carrega esse arquivo, desde que os modelos Twig estejam dentro do diretório views.

Se você quiser usar um nome ou caminho customizado para o diretório, você terá de provê-lo. Por exemplo, criei um diretório chamado Twig na raiz do meu tema e o adicionei ao argumento da função render.

1	<?php Timber::render('twig/welcome.twig'); ?>

A Ordem Oficial de Carregamento

Timber procurará, primeiro, no tema filho e depois no tema pai (assim como acontece no WordPress padrão). A ordem oficial de carregamento é:

Locais definidos pelos usuários
Diretório de chamada do script PHP (mas não do tema)
Tema filho
Tema pai
Diretório de chamada do script PHP (incluido o tema)

O Item 2 está acima dos outros para caso use o Timber em algum plugin, ele usará o arquivos Twig do diretório do plugin.

Assim, o arquivo index.php não tem qualquer HTML e está renderizando um modelo Twig.

Agora, enviemos algum dado dinâmico do index.php para o arquivo welcome.twig e renderizemos com o Timber.

Enviando Dados Pelo Timber para Arquivos Twig

Para enviar dados de um arquivo PHP para um arquivo Twig, você precisa definir um vetor de contexto. A função render recebe um vetor de dados e repassa para os modelos do Twig com uma espécie de contexto. Chamemos o vetor de $context, que será um vetor associativo, ou seja, recebe pares de chave-valor.

Adicionemos um par de chave-valor que seja uma mensagem dinâmica, o qual nosso arquivo PHP enviará para o arquivo Twig.

Arquivo de Dados

Meu arquivo index.php parece com isso, agora.

<?php
/**
 * Homepage
 */
get_header();

    // Context array.
	$context = array();

	// Dynamic message.
	$var = 'Dynamic Message';

	// Dynamic data.
	$context['the_message'] = $var;

	// Render twig file with the give $context array.
	Timber::render( 'welcome.twig', $context );

get_footer();

Assim, dentro do arquivo index.php, defini um vetor vazio $context na linha #8. Então, na linha #11, criei uma variável $var com o valor 'Dynamic Message'. Na linha #14, criei a chave the_message igual a $var.

Na linha #17, invoquei a função render com o arquivo welcome.twig, mas, dessa vez, ela levou um argumento adicional, o vetor $context. Esse novo argumento contém os dados que o Timber enviará do arquivo PHP para o arquivo Twig.

Então, definimos o vetor contextual e adicionamos uma mensagem dinâmica (você pode adicionar mensagens diferentes a usuários diferentes usando algum tipo de lógica, como, por exemplo, mostrando o nome inicial do usuário).

Arquivo Modelo

Precisamos usar esses dados—the_message—no arquivo Twig. Podemos imprimir a variável no arquivo Twig ao usar chaves duplas ao redor dela. Por exemplo, para imprimir $var em um arquivo Twig, podemos escrever {{ var }}. E foi o que fiz.

1	<!-- Message Template -->
2	<section class="message">
3	<h2>{{ the_message }}</h2>
4	</section>

O valor de the_message será impresso dentro dos elementos h2. Eu sei, é bem simples, e o código é bem direto.

E é isso! Salve o código e veja a mensagem dinâmica no front-end. Eis a captura de tela final.

Conclusão

Resumindo, agora pode usar arquivos PHP para a lógica e prover dados para o modelo Twig, que contém HTML e renderizará as variáveis ou funções dentro das chaves duplas.

Essa abordagem modular ajuda a separar os arquivos de modelo de todos componentes do seu tema. Imagine um componente message.twig que você pode usar onde quiser, para mostrar qualquer mensagem que queira, qualquer número de vezes.

Essa foi uma implementação básica do Twig com Timber. Contudo, nos próximos dois artigos, escreverei sobre planilha de atalhos, trabalhar com imagens no Timber e criar menus sem aquelas funções mirabolantes.

Se tiver quaisquer perguntas, publique-as nos comentários abaixo ou contate-me no Twitter. Você também pode dar uma olhada no código do meu tema nesse repositório do Github.