Desenvolvendo para WordPress com Twig: Blocos, Aninhamento e Planilha de Atalhos do WP

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

No artigo anterior, falamos da integração do Twig ao WordPress, usando o Timber, e como desenvolvedores podem passar dados dos arquivos PHP para arquivos Twig. Discutamos como criar um modelo base com Twig, os benefícios da técnica DRY e sobre a Planilha de Atalhos do WordPress.

Criando um Modelo Base com Twig

Twig usa o princípio DRY (Don't Repeat Yourself - Não se Repita). Um dos recursos mais importantes do Twig é o modelo base com aninhamento e herança múltipla. Enquanto a maioria das pessoas usa inclusões PHP linearmente, podemos criar aninhamentos infinitos de blocos para controlar os modelos.

Pense no modelo base como um modelo pai com conjuntos de blocos dentro dele. Um modelo filho pode estender um modelo pai e modificar qualquer bloco ou blocos sem precisar reescrever código que seriam similares em ambos os modelos.

Vejamos um exemplo de um modelo pai/base, o arquivo base.twig. Podemos colocá-lo junto dos outros modelos Twig, no diretório views. Invocamos essa arquivo de qualquer um dos modelos Twig, usando-o como modelo pai para aquele arquivo Twig. Digite o código abaixo e salve no diretório views. Esse modelo base proverá uma estrutura base para seu tema de WordPress. Eis o código de um arquivo base.twig simples.

{# Base Template: base.twig #}

{% block html_head_container %}

    {% include 'header.twig' %}

{% endblock %}

  <body class="{{body_class}}">

		<div class="wrapper">

			{% block content %}

			    <!-- Add your main content here. -->
			    <p>SORRY! No content found!</p>

			{% endblock %}

		</div>
		<!-- /.wrapper -->

	{% include "footer.twig" %}

	</body>

</html>

Comentários no Twig: `{# Base Template: base.twig #}`

Podemos escrever comentários no Twig usando {# comentário aqui #}. Para comentar parte de uma linha num modelo, use a sintaxe de comentário {# ... #}. Isso é útil para depuração ou para adicionar informação para outros projetistas de modelos ou você mesmo. Você encontra um comentário na linha #1.

Blocos: `{% block html_head_container %}` `{% endblock %}`

Toda a filosofia do Twig e do Timber gira em torno da abordagem de código modular no WordPress. Tenho escrito, repetidamente, que dados no Twig são lidados na forma de componentes ou blocos.

Blocos são usados para herança e agem como um espaço reservado e substituto ao mesmo tempo. Eles estão documentados em detalhes na parte do elemento extends, na documentação.

{% block adicionar_nome_do_bloco_aqui %} Conteúdo do bloco aqui {% endblock %}

No código acima, você encontra um bloco chamado html_head_container que vai da linha #3 à linha #7. Qualquer modelo que estenda o modelo base base.twig pode herdar o mesmo contúdo do bloco ou modificá-lo, adicionando algo mais. Há outro bloco chamado {% block content %} que vai da linha #13 à linha #18.

Similarmente, os blocos podem ser estendidos ainda mais, já que podemos criar níveis infinitos de blocos aninhados. Esse é o princípio DRY verdadeiro.

Declaração Include: `{% include "header.twig"` %}

Modelos Twig podem incluir outros modelos Twig, assim como no PHP. O arquivo base.twig será o envólucro geral e está incompleto sem seus arquivos header e footer. Assim, a sintaxe {% include "arquivo.twig" %} nos audará a incluir dois modelos Twig diferentes:

O modelo header {% include "header.twig" %} na linha #5.
O modelo footer {% include "footer.twig" %} na linha #23.

Estendendo o Modelo Base

Criamos o arquivo base.twig como modelo pai e mantivemos o bloco de conteúdo vazio. Esse bloco pode ser usado dentro de qualquer arquivo Twig customizado que o modificará, e o resto do modelo base será herdado sem alterações. Por exemplo, criemos o arquivo single.twig que estenderá o modelo base.twig e modificará o bloco content.

{# Single Template: `single.twig` #}

{% extends "base.twig" %}

{% block content %}

    <div class="single_content">
        <h1>{{ post.title }}</h1>
        <p>{{ post.get_content }}</p>
    </div>

{% endblock %}

Esse código mostra um arquivo customizado, o single.twig. Na linha #3, esse modelo usa o base.twig como modelo base/pai. O elemento extends pode ser usado para estender um modelo a partir de outro.

Aqui, os detalhes relacionados ao header e footer são herdados do arquivo base.twig, que é o modelo pai, enquanto o bloco content será substituido pelo título e conteúdo da publicação. Não é bem legal?

Planilha de Atalhos do WordPress para o Timber

Os desenvolvedores do Timber garantiram que ele complementa o WordPress em todas as formas possíveis, do núcleo aos usuários finais. Embora a conversão da sintaxe das funções do WordPress para o Timber seja um tanto diferente, ela é bem documentada. Ao final do artigo, compartilharei uma lista de algumas conversões entre funções do WordPress e os equivalentes do Timber. Recapitulemos.

Recapitulação Rápida

No artigo anterior, criamos uma mensagem de boas vindas que era populada através de uma string PHP na página inicial do site de demonstração. O código disso pode ser encontrado nessa ramificação, lá no Github. Repitamos esse procedimento outra vez, mas com uma abordagem diferente e mais técnica.

Agora, mostraremos a mesma mensagem mas, dessa vez, criando uma nova página que será o conteúdo a ser mostrado.

Recuperando Funções WordPress no Twig

Crie uma nova página com o título "Welcome to My Blog!" e adicione algum conteúdo antes de apertar o botão de publicação.

Agora, mostremos o conteúdo dela na página inicial. Para isso, mais uma vez, iremos ao arquivo index.php e adicionaremos as linhas de código a seguir.

<?php
/**
 * Homepage
 */

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

// Add the page ID which is 4 in my case.
$context[ 'welcome_page' ] = Timber::get_post( 4 );

// Timber render().
Timber::render( 'welcome.twig', $context );

Adicionei um vetor $context com uma chave welcome_page de valor do retorno da função get_post(), usada para buscar a página que acabei de criar. Para tanto, passei o ID da página, que nesse caso é 4.

Dentro do arquivo welcome.twig, usaremos print_r no elemento welcome_page e veremos que dados recebemos. Meu arquivo welcome.twig está mais ou menos assim, agora.

{# Message Template: `welcome.twig` #}
<section class="message">
        <pre>
            <code>{{ welcome_page | print_r }}</code>
        </pre>
</section>

Posso confirmar que esse elemento do vetor $context tem um objeto TimberPost da página com ID 4.

Com isso, temos todas as propriedades que podemos mostrar no front-end. Por exemplo, mostrar apenas title e content da página. Então, agora, meu arquivo welcome.twig parece com isso:

{# Message Template: `welcome.twig` #}
<section class="message">
        <h2>{{ welcome_page.title }}</h2>
        <p>{{ welcome_page.content }}</p>
</section>

E a página inicial tem a informação que precisamos.

Planilha de Atalhos do WordPress

Como disse antes, o Timber provê algumas conversões úteis de funções do WordPress. Essa funções podem ajudar a obter informações relacionadas a:

Blog
Classes do elemento Body
Header/Footer

Função `get_context()`

A função Timber::get_context() retorna várias informações do site que podem ser mostradas no front-end do mesmo. A documentação diz o seguinte:

Será retornado um objeto com várias coisas comuns e necessárias pelo site. Coisas como sua navegação, wp_head e wp_footer estarão lá (mesmo que você as sobrescreva depois). Você pode fazer $context = Timber::get_context(); print_r( $context ); para ver o que temos nele ou abrir o arquivo timber.php para inspecionar por conta própria.

1	<?php $context = Timber::get_context(); ?>

Não apenas isso mas você também pode adicionar seus próprios dados customizado a essa função através de um filtro.

<?php

/**
 * Custom Context
 *
 * Context data for Timber::get_context() function.
 *
 * @since 1.0.0
 */
function add_to_context( $data ) {
    $data['foo'] = 'bar';
	$data['stuff'] = 'I am a value set in your functions.php file';
	$data['notes'] = 'These values are available everytime you call Timber::get_context();';
	$data['menu'] = new TimberMenu();
	return $data;
}
add_filter( 'timber_context', 'add_to_context' );

Abaixo, você pode ver outras conversões como essa, que podem ser usadas com Timber.

Informações do Blog

blog_info('charset') => {{ site.charset }}
blog_info('description') => {{ site.description }}
blog_info('sitename') => {{ site.name }}
blog_info('url') => {{ site.url }}

Classes do Elemento Body

implode(' ', get_body_class()) => <body class="{{ body_class }}">

Tema

get_template_directory_uri() => {{ theme.link }} (para temas pais)
get_template_directory_uri() => {{ theme.parent.link }} (para temas filhos)
get_stylesheet_directory_uri() => {{ theme.link }}
get_template_directory() => {{ theme.parent.path }}
get_stylesheet_directory() => {{ theme.path }}

wp_functions

wp_head() => {{ wp_head }}
wp_footer() => {{ wp_footer }}

Experimentemos algumas funções, começando pelas informações do blog. No lugar de foo, escreva {{ site.name }}.

O front-end mostrará o título do site, assim:

Timber também tem algumas funções para mostrar as publicações e informações relacionadas a eles, via TimberPost(). Antes de explicar seu uso, listemos as funções convertidas relacionadas a ele.

Post

the_content() => {{ post.content }}
the_permalink() => {{ post.permalink }}
the_title() => {{ post.title }}
get_the_tags() => {{ post.tags }}

Uso

Use esse código no arquivo single.php.

<?php
$context = Timber::get_context();
$context[ 'post' ] = new TimberPost(); 
Timber::render( 'welcome.twig', $context );
?>

Agora, testemos a função {{ post.title }} dentro de nosso arquivo Twig.

1	<section class="single_post">
2	<h2>{{ post.title }}</h2>
3	</section>

Salve-o e o front-end mostrará o título da publicação, assim:

Sua Vez!

Hoje, você viu a implementação prática do princípio DRY, usando Timber e Twig, enquanto construia um tema para WordPress. Dê outra olhada no tutorial e tente implementá-lo, avise-me quando surgirem dúvidas. Você pode encontrar o código completo na ramificação Planilha de Atalhos WP, nesse repositório do Github.

No próximo e último artigo, falarei sobre como lidar com imagens e menus em um modelo Twig para WordPress. Até lá, contate-me via Twitter para ter suas dúvidas sanadas ou publique uma aqui.