Desenvolvendo para WordPress com Twig: Timber Image, Menu e Usuário

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

Estando aqui, você já leu os conceitos básicos do uso do Twig através do Timber, ao criar temas modulares para WordPress. Também vimos aninhamento de blocos e herança múltipla com Twig, em cima do princípio DRY. Hoje, exploraremos como mostrar imagens de anexos, menus do WordPress e usuários com Twig, através do plugin Timber.

Imagens no Timber

Imagens são elementos vitais para qualquer tema do WordPress. No padrão de código do WordPress, imagens são integradas com PHP, dentro de elementos img normais do HTML. Contudo, Timber oferece uma forma bem interessante, modular e limpa de lidar com o elemento img (imagem).

Existem imagens anexas ao campo thumbnail da publicação. Elas podem ser obtidas pelos arquivos Twig, facilmente, através de {{ post.thumbnail }}. Simples assim!

Uso

Comecemos com um exemplo prático. Nosso arquivo single.php parece com isso:

<?php
/**
 * Single Template
 *
 * The Template for displaying all single posts.
 *
 * @since 1.0.0
 */

// Context array
$context         = Timber::get_context();
$post            = new TimberPost();
$context['post'] = $post;

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

Aqui, usei a função TimberPost() por razões óbvias. Ela é usada pelo Timber para representar publicações obtidas do WordPress, disponibilizando-as nos modelos Twig.

Como a imagem destaque está anexada aos dados da publicação, agora precisamos mostrá-la no front-end. Assim, o arquivo Twig single.twig ficará desse jeito:

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

{% extends "base.twig" %}

{% block content %}

    <div class="single_content">

        <img src="{{ post.thumbnail.src }}" />

    </div>

{% endblock %}

Na linha #9, {{ post.thumbnail.src }} retorna a imagem destaque (thumbnail) da publicação e mostra dessa forma:

Você pode usar esse código para retornar quantos thumbnails quiser.

Ainda há muito mais em relação a imagens, usando Timber. Por exemplo, você também pode redimensioná-las, via:

1	<img src="{{ post.thumbnail.src \| resize ( 900, 500 ) }}" />
2

Ao usar a função resize(), você pode dar novas dimensões à image onde o primeiro parâmetro é a largura e o segundo é a altura. Se quiser dimensionar a imagem proporcionalmente, omita o parâmetro da altura. Agora, a sintaxe vira:

1	<img src="{{ post.thumbnail.src \| resize ( 900 ) }}" />

O front-end mostra a mesma imagem, assim:

Se quiser explorar mais, tente o livro de dicas para Imagens.

Usando `TimberImage()`

Considere o cenário em que o desenvolvedor quer obter imagens através do ID delas, ou quer mostrar imagens externas via URL, etc. Para tais abordagens, o Timber oferece a classe TimberImage() para representar imagens que podem ser obtidas do WordPress.

Uso

Façamos um exemplo para o arquivo single.php, que parece com isso, agora:

<?php
/**
 * Single Template
 *
 * The Template for displaying all single posts.
 *
 * @since 1.0.0
 */

// Context array
$context         = Timber::get_context();
$post            = new TimberPost();
$context['post'] = $post;

// Using the TimberImage() function 
// to retrieve the image via its ID i.e 8
$context['custom_img'] = new TimberImage( 8 );

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

Dessa vez, usei a classe TimberImages() que recebe 8 (ID da imagem) como parâmetro. O resto do código é o mesmo. Obtenhamos essa imagem através do Twig no arquivo single.twig.

1	<img src="{{ custom_img }}" />

O valor salvo na chave custom_img de $context ({{ custom_imd }}), retornará a imagem através do seu ID para mostrá-la no front-end, dessa forma.

Para retornar uma image via URL externa, você pode usar a sintaxe abaixo:

1	<?php $context[ 'img' ] = new TimberImage( 'https://domain.com/link/image.jpg' ); ?>
2

Agora, ao invés do ID da imagem, há uma URL de imagem, que será mostrada no front-end, assim:

Para saber mais capacidades dessa função, cheque a documentação.

Menus no Timber

Agora, como faria para renderizar um menu do WordPres com modelos Twig? Eis algo complicado. Mas, espere! Timber provê a classe TimbeMenu(), que pode ajudá-lo a renderizar menus WordPress dentro de arquivos Twig em um laço completo. Vejamos.

Uso

Todo o conceito da obtenção dos menus gira em torno do objeto menu. Há duas formas de definir seu contexto. A primeira é disponibilizar o objeto menu em todas as páginas, adicionando-o à função global get_context(), como fiz no arquivo function.php. Segundo, você pode adicionar um menu específico, através do seu ID, para um modelo PHP em particular.

Independente de qual método, uma vez que o menu esteja disponível no vetor $context do Timber, você pode obter todos os items de menu de lá. Porém, prefiro definí-lo globalmente. Vá até o arquivo functions.php e cole o código abaixo:

<?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' );

Então, defini uma chamada de função customizada add_to_context. Dentro dessa função há alguns dados que tornarei disponível em todos modelos PHP através da função get_context(). Na linha #13 pode-se ver uma instância de TimberMenu() como valor da chave 'menu' no vetor $data.

Isso tornará disponível um menu WordPress padrão para o modelo Twig como um objeto que podemos iterar. A função TimberMenu() pode receber parâmetros como slug do menu ou ID.

Criemos um modelo Twig chamado menu.twig.

{# Menu Template: `menu.twig` #}

<nav>
    <ul class="main-nav">
        {% for item in menu.get_items %}
                <li class="nav-main-item {{ item.classes | join(' ') }}">
                    <a class="nav-main-link" href="{{ item.get_link }}">{{ item.title }}</a>
                </li>
        {% endfor %}
    </ul>
</nav>

O código acima executa um laço dentro do modelo Twig. A linha #5 executa um laço for para cada item do menu e mostra o titulo de cada item do menu em uma lista não ordenada. O laço executa até que todos os pares chave-valor do objeto menu sejam iterados e listados no front-end.

Adiantei-me e inclui o modelo menu.twig no modelo base.twig na linha #11.

{# Base Template: `base.twig` #}

{% block html_head_container %}

    {% include 'header.twig' %}

{% endblock %}

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

		{% include "menu.twig" %}

		<div class="wrapper">

			{% block content %}

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

			{% endblock %}

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

	{% include "footer.twig" %}

	</body>

</html>

Pré-visualizemos o painel administrativo (Aparência > Menus) do meu site demo, onde seu menu contém dois itens pais e um item filho.

Vejamos uma publicação do tipo página—uma vez que nosso single.twig estende base.twig, nosso meu aparecerá automagicamente na página.

Veja no topo da nossa página um menu com ambos os items pais do menu nela.

E quanto aos items filho do menu? Atualizemos o arquivo menu.twig para incluir os itens filhos também.

{# Menu Template: `menu.twig` #}

<nav>
    <ul class="main-nav">
        {% for item in menu.get_items %}
                <li class="nav-main-item {{ item.classes | join(' ') }}">
                    <a class="nav-main-link" href="{{ item.get_link }}">{{ item.title }}</a>

						{% if item.get_children %}

							<ul class="nav-drop">

								{% for child in item.get_children %}

								<li class="nav-drop-item">
									<a href="{{ child.get_link }}">{{ child.title }}</a>
								</li>

								{% endfor %}

							</ul>

						{% endif %}

                </li>
        {% endfor %}
    </ul>
</nav>

Linhas #9 à #23, imprimimos os items filho do menu, caso existam. Agora, o front-end mostra o item filho existente.

Para maiores detalhes sobre TimberMenu(), cheque a documentação.

Usuários no Timber

Usuários podem ser obtidos da base de dados do WordPress usando a classe TimberUser(). A classe recebe um ID de usuário ou slug como argumentos para obter o usuário.

Como usuários ou autores dos blogs são associados a publicações do WP, modificarei o modelo single.php:

<?php
/**
 * Single Template
 *
 * The Template for displaying all single posts.
 *
 * @since 1.0.0
 */

// Context array
$context         = Timber::get_context();
$post            = new TimberPost();
$context['post'] = $post;

// Using the TimberImage() function
// to retrieve the image via its ID i.e 8
$context['custom_img'] = new TimberImage( 8 );

// Get the user object.
$context['user'] = new TimberUser();

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

Na linha #20, inicializamos a classe TimberUser() e atribuimos ao elemento user do vetor $context. Mostremos o nome do autor no modelo Twig.

Meu modelo single.twig tem uma linha de código bem no final, na linha #21.

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

{% extends "base.twig" %}

{% block content %}

    <div class="single_content">

        <img src="{{ post.thumbnail.src }}" />

    	{# <img src="{{ post.thumbnail.src | resize ( 900, 500 ) }}" /> #}

    	{# <img src="{{ post.thumbnail.src | resize ( 900 ) }}" /> #}

    	{# <img src="{{ custom_img }}" /> #}

        <h1>{{ post.title }}</h1>

        <p>{{ post.get_content }}</p>

        <p>Author: {{ user }} </p>
    </div>

{% endblock %}

O código busca o nome do autor da publicação atual e o mostra no front-end. Você pode usar {{ user | print_r }} para ver o que mais está disponível no objeto TimberUser.

Para ler mais sobre essa classe, veja a documentação. Você pode achar o código desse tutorial no repositório do Github na ramificação ImagesMenusUsers.

Conclusão

Esse artigo finaliza a série. Nesses quatro artigos, exploramos o uso do Timber para integrar o mecanismo de modelagem do Twig a um tema do WordPress.

O repositório final dessa série pode ser encontrado no Github, com ramificações específicas para cada tutorial:

Você pode consultar a documentação do Timber para mais.

Reveja a série inteira e implemente cada exemplo explicado e aposto que curtirá o Twig. Deixe suas perguntas nos comentários abaixo. Você também pode me achar no Twitter.