Guia definitivo para criar Custom Post Types – Parte 04

Esta série de artigos pretende ser um complemento de estudo tanto para iniciantes como para profissionais em como programar Custom Post Types no WordPress. Não esqueça de ler o primeiro, segundo e terceiro artigos desta série. Fique atento: todos os códigos desta série servem apenas como exemplo. Você pode e DEVE fazer as suas experiências ao modificar o código a seu gosto e necessidades.

Neste artigo da série iremos tratar de extender e usar de uma forma mais customizada as taxonomias nos nossos tipos de post.

Sumário

• Extender, acrescentando novos campos às taxonomias
• Apresentar as taxonomias personalizadas no website
• Criar um filtro a partir da taxonomia na página de listagem de Post Types

As taxonomias personalizadas foram iniciadas no ciclo da versão 2.8 do WordPress tendo a API sido acabada na versão 2.9, antes do lançamento dos Custom Post Types. Com esta nova funcionalidade, os desenvolvedores tiveram a possibilidade de criar novos tipos de categorias para as publicações e páginas, extendendo dessa forma o tipo de categorização disponível. Com isto iniciou-se um novo ciclo para o WordPress: de gestor de sites para um verdadeiro CMS personalizável.

É possível criar taxonomias para categorizar não só publicações e páginas mas também os nossos Post Types.

Pegando no nosso Post Type Filme, e na categoria personalizada que criamos no primeiro artigo, vamos extendê-la de modo a termos mais campos para além dos habituais.

Extender, acrescentando novos campos às taxonomias

Por padrão, as taxonomias apresentam apenas três campos – Título, Slug e Descrição – e sem a possibilidade de acrescentar ou retirar campos.

No entanto, com um plugin que cria a funcionalidade de metadata nas taxonomias, conseguimos atingir da mesma forma o pretendido.

No nosso caso, iremos criar um campo muito simples, uma caixa de input onde poderemos colocar a URL de uma imagem que será usada como imagem de destaque da categoria de filmes. Que tal? Vamos então!

Para começar, colocamos o código que está no primeiro artigo desta série para criar a nossa taxonomia. Agora que temos a nossa taxonomia instalada, vamos extendê-la.

Em seguida, fazemos o download do plugin e o instalamos da mesma forma como outro plugin qualquer.

Existem vários plugins para criar esta funcionalidade, no entanto este é aquele com que prefiro trabalhar e que recomendo.

Depois de instalado e configurado, já temos a estrutura necessária para trabalhar com estes campos das taxonomias personalizadas. Desta forma, basta mapear quatro ações para realizarem a tarefa de nos criar a interface visual entre os campos e o WordPress:

add_action( 'film_category_add_form_fields', 'film_category_add', 10, 2);
add_action( 'film_category_edit_form_fields', 'film_category_edit', 10, 2);
add_action( 'edited_film_category', 'film_category_save', 10, 2);
add_action( 'save_film_category', 'film_category_save', 10, 2);

Estas quatro ações irão, juntamente com as funções que chamam, criar os campos na página de adição de termos  – <taxonomia>_add_form_fields e save_<taxonomia> – e os campos na página de edição dos termos da taxonomia – <taxonomia>_edit_form_fields e save_<taxonomia>. Estes dois conjuntos existem pois as páginas de criação e de edição dos termos das categorias é diferente.

Agora que temos as ações mapeadas, vamos acrescentar as funções que são necessárias:

function film_category_add( $tag ) {
?>
<div class="form-field">
   <p style="color:#222;font-style:normal;">Imagem:</p>
   <input type="text" name="image" id="image" value="" />
   <p>Adicionar uma imagem de destaque para esta categoria.</p>
</div>
<?php
}
 
function film_category_edit( $tag, $taxonomy ) {
   $image = get_term_meta( $tag->term_id, '_category_image', true );
?>
<tr class="form-field">
   <th scope="row" valign="top">
      <p style="color:#222;font-style:normal;">Imagem:</p>
   </th>
   <td>
      <input name="image" id="image" type="text" value="<?php echo $image; ?>" />
      <p>Adicionar uma imagem de destaque para esta categoria.</p>
   </td>
</tr>
<?php
}

Estas funções são muito simples. A primeira apenas apresenta um HTML que desenha o campo de input para se colocar o URL da imagem.

A segunda função é mais complexa, pois é a função que é usada na edição dos termos das taxonomias. Primeiro, através da função get_term_meta() – uma das funções adicionadas pelo plugin que instalamos há pouco – retornamos para a variável $image o URL definido pelo usuário, apresentando-o em seguida no campo de input.

Neste momento os campos são apresentados na interface do WordPress, porém nenhum valor é guardado quando se salva um termo dessa taxonomia. Precisamos ainda definir a função que guarda os valores:

function film_category_save( $term_id ) {
  // Se foi inserido algum valor no campo...
  if ( isset( $_POST['image'] ) )
    // ...guarda esse valor
    update_term_meta( $term_id, '_film_category_image', strip_tags( $_POST['image'] ) );
 
  // senão...
  else
    // Remove esse valor
    delete_term_meta( $term_id, '_film_category_image' );
 
  return $term_id;
 
}

Esta função é muito simples: caso o valor ‘image’ exista (ou seja, caso o usuário preencha o campo de imagem) ela guarda esse valor, senão ela remove o valor anterior, pois, caso o campo esteja em branco, é provável que o usuário queria remover essa imagem do termo da taxonomia.

E estamos prontos! O nosso campo personalizado irá aparecer na interface.

Apresentar as taxonomias personalizadas no website

Como visto no segundo artigo desta série, a hierarquia de templates WordPress é bastante complexa, dando a possibilidade de se construir o que se quiser. No caso da apresentação de posts em taxonomias, só necessitamos de um template: taxonomy-<taxonomia>.php

No nosso caso, primeiro vamos criar um arquivo no nosso tema com o nome taxonomy-film_category.php para receber toda a lógica programática de apresentação dos nossos filmes:

<h1 class="entry-title">
  <?php single_tag_title(); ?>
</h1>
 
<div class="entry-thumbnail">
  <img src="<?php echo get_term_meta( $tag->term_id, '_category_image', true ); ?>" />
</div>
 
<?php if ( have_posts() ) : while( have_posts() ) : the_post(); ?>
 
<div class="entry-title"><?php the_title(); ?></div>
<div class="entry-content"><?php the_content(); ?></div>
 
<?php endwhile; endif; ?>

Este é o código responsável pela apresentação dos filmes dentro de cada termo da taxonomia. A diferença para com o código do artigo anterior prende-se com o uso de uma tag H1 e da função single_tag_title().

Esta é reponsável por apresentar o título da taxonomia que estamos a navegar – por exemplo, se estivermos a ver a categoria Drama, esta função imprime Drama na tela.

Novamente usamos a função get_term_meta() para retornar deste modo o URL da imagem que se definiu na administração para cada categoria de filmes.

Com alguns ajustes de HTML e CSS conseguimos atingir algo como isto, em que a imagem da esquerda é a que usámos colocando o seu URL na caixa de input:

É possível criar e extender muito este exemplo, que deve ser trabalhado e usado para os seus próprios fins. Basta dar uso à criatividade.

Criar um filtro por taxonomia na página de listagem de Post Types

Se você visualizar a página de listagem dos Posts na sua administração, verá que no topo existem uma série de filtros, sendo que um deles é filtrar os posts por categoria. É essa funcionalidade que iremos apresentar nesta seção, filtrando os filmes por categoria.

Com uma simples ação é possível colocar uma caixa dropdown com as categorias da taxonomia film_category. Desta forma atingimos algo parecido, apresentando no campo da filtragem a seguinte caixa:

Este é o código necessário:

add_action( 'restrict_manage_posts', 'film_retrict_categories' );
 
function film_retrict_categories() {
  // Acesso às variáveis do tipo de post atual e o array do pedido
  global $typenow, $wp_query;
 
  // Se o tipo de post for diferente de film não faz nada
  if ( $typenow != 'film' )
   return false;
 
  // Imprime uma select box com todos os termos da taxonomia film_category
  wp_dropdown_categories(array(
   'show_option_all' =>  'Mostrar tudo',
   'taxonomy'        =>  'film_category',
   'name'            =>  'film_category',
   'orderby'         =>  'name',
   'selected'        =>  $wp_query->query['term'],
   'hierarchical'    =>  true,
   'depth'           =>  3,
   'show_count'      =>  true,
   'hide_empty'      =>  true,
   )
  );
}

Ao chamarmos a ação restrict_manage_posts com a nossa função, temos a possibilidade de acrescentar HTML na zona de filtragem, no cabeçalho da tabela de listagem.

Primeiro, caso o Post Type não seja film, a função retorna sem continuar a sua atividade, assim apenas aplicamos este filtro nas páginas de listagem dos filmes.

A função wp_dropdown_categories é responsável pela impressão da dropdown das categorias da taxonomia passada como argumento, no nosso caso film_category. Não irei me delongar mais sobre os argumentos desta função pois dariam um artigo inteiro, porém deixo o link para estudo mais profundo.

Espero que este artigo tenha sido útil para criar seu plugin que tanto deseja!

Não esqueça de ler os outros artigos desta série:

• Guia definitivo para criar Custom Post Types – Parte 01 – Parte 02 – Parte 03

Até a próxima!