Num artigo anterior vimos como trabalhar facilmente com categorias no WordPress. Nós abordamos como podemos classificar nossas postagens em diferentes categorias, que podem então ser editadas ou excluídas.

Cobrimos o básico, agora é hora de dar uma olhada em algo que será de maior interesse para os desenvolvedores: a API Categories, e como recuperar e exibir dados de categoria.

Como a API Links Manager, a API Categories é um grande tópico, ainda maior em termos do número de funções disponíveis. Neste artigo, vamos cobrir uma função que é útil quando queremos listar nossas categorias.

Listing Categories

Na API do Gerenciador de Links encontramos uma função importante que nos permite listar nossos links. Não é surpresa, portanto, que encontremos a mesma coisa na API de Categorias: wp_list_categories(), esta é a função com a qual vamos trabalhar aqui.

Basicamente, você tem que chamar esta função no lugar que você quer ver suas categorias listadas.

wp_list_categories();

Como você pode imaginar, este resultado é totalmente personalizável. Para moldá-lo às nossas necessidades, podemos passar um argumento para esta função: um array contendo valores para as opções que queremos definir. Vamos dar uma olhada em algumas das opções disponíveis.

Escolhendo as Categorias a Exibir

Antes de ver como personalizar a saída, vamos começar com algumas opções que nos permitem escolher o que exibir.

Incluir e Excluir Categorias

Primeiro encontramos a opção include que aceita uma lista de IDs de categoria a exibir. Quando você usar esta opção, wp_list_categories() exibirá apenas as categorias com os IDs que você passou. Você pode indicar um ou mais IDs. Se você quiser indicar dois ou mais IDs, você deve separar estes números com uma vírgula.

$args = array('include' => '15,16,9');wp_list_categories($args);

Se por outro lado você não quiser escolher o que exibir, mas sim o que não exibir, a opção exclude é para você. Ela pode ser usada exatamente como include .

$args = array('exclude' => '15,16,9');

Note que se você quiser usar a opção exclude, include deve estar vazia (seu valor padrão). Caso contrário, a opção include ganha e apenas as categorias passadas para ela serão exibidas.

Outra opção para excluir categorias é exclude_tree. Mais uma vez, ela aceita uma lista separada por vírgulas de IDs de categorias a serem excluídas. A diferença é que ela irá excluir as categorias selecionadas e todos os seus filhos. Note que, para ver esta opção funcionando, você deve definir a opção hierarchical para 0 (veremos abaixo o que esta opção faz).

// 14 is the ID of "My life", parent of "My goldfish" and "My garden" which will also be hidden$args = array('exclude_tree' => '14','hierarchical' => 0);

Ordenando a Saída

Por padrão, as categorias são listadas em ordem alfabética. Você pode modificar este comportamento graças à opção orderby, que aceita uma string. Você pode escolher a partir das seguintes opções: ID para ordenar as categorias pelo seu ID (não, realmente?), name para ordená-las alfabeticamente (o valor padrão), slug para ordená-las na ordem alfabética das suas lesmas, e count para ordená-las pelo número de posts que contêm.

A ordem escolhida pode ser revertida definindo DESC (descendente) como um valor para a opção order (por padrão esta opção está definida para ASC (ascendente)).

No exemplo abaixo, listamos as categorias pelo número de posts que elas contêm: como a ordem é invertida, a categoria contendo o maior número de posts será a primeira a ser exibida.

$args = array('orderby' => 'count','order' => 'DESC');

Limite o número de categorias exibidas

Após termos ordenado nossas categorias, podemos querer limitar o número de itens listados. Isto pode ser conseguido usando a opção number. Por padrão, esta opção está definida para null e não há limite para que todas as categorias sejam mostradas. Ao especificar um número, você pode definir o número máximo de categorias a serem exibidas. Por exemplo, podemos listar as cinco categorias mais usadas.

$args = array('orderby' => 'count','order' => 'DESC','number' => 5);

Este exemplo lista as categorias com o maior número de posts. Outra solução é ocultar as categorias não utilizadas. Para fazer isso podemos usar hide_empty, um conjunto booleano para 1 por padrão: as categorias vazias não são mostradas. Você pode optar por exibi-las definindo isto como 0.

// Show me all the categories, even the empty ones$args = array('hide_empty' => 0);

Detalhes especificados a serem exibidos

Detalhes são importantes, e há sempre alguns que queremos incluir.

Contadores!

Por exemplo, você pode querer exibir o número de posts contidos em cada categoria. Para exibir isto você pode usar a opção show_count e defini-la como 1. Por defeito, este booleano está definido para 0 e esta contagem não é mostrada.

$args = array('show_count' => 1);

Note que uma mensagem numa categoria infantil também será adicionada ao número total de mensagens do seu pai. Por exemplo, a captura de tela abaixo é feita com três posts na categoria “Minha vida”: enquanto há apenas um post nesta categoria, os outros dois estão nas categorias filho.

Você pode modificar este comportamento graças à opção pad_counts. Se você definir isso para 0, a contagem dos pais só exibirá o número de posts nas categorias desses pais e não incluirá os posts nas suas categorias de filhos.

$args = array('show_count' => 1,'pad_counts' => 0);

Descrições das Categorias

Como vimos no nosso artigo anterior, podemos definir uma descrição para as nossas categorias. Esta descrição pode ser exibida com a opção use_desc_for_title. É um conjunto booleano para 1 por padrão: as descrições são exibidas no atributo title dos links da lista. Se você não quiser ver esta descrição você pode definir isto para 0.

$args = array('use_desc_for_title' => 1);

Feeds

Apenas como o WordPress gera um feed para seus posts, ele também cria um para cada categoria. Os visitantes podem escolher seguir apenas as atualizações das categorias em que estão interessados, se não gostarem de todo o seu conteúdo.

Os links para esses feeds podem ser mostrados na lista de nossas categorias, graças à opção feed. Por defeito esta opção está definida para uma string vazia e os links não são mostrados. O código abaixo mostra como ativar esta opção.

$args = array('feed' => 'RSS');

Por padrão, o feed vinculado é o RSS2. Mas o WordPress pode gerar mais tipos de feed. Se você preferir Atom, por exemplo, você pode forçar o WordPress a mostrar este tipo de feed em vez do RSS2 um.

Para selecionar o tipo de feed que você quer ver exibido, você pode especificar qualquer uma das seguintes opções : atom, rss, rss2 e rdf.

$args = array('feed' => 'Atom','feed_type' => 'atom');

Finalmente, se você preferir usar uma imagem para vincular ao seu feed RSS, você pode indicar a URL da imagem que você quer ver na opção feed_image. O texto na opção feed tornar-se-á então o texto alternativo para a imagem.

$args = array('feed' => 'RSS','feed_image' => 'http://website.org/my-awesome-rss-image.png');

Is This Category the Current One?

If you use wp_list_categories() on an archive page (in the archive.php template), you can see that the current category (the one displayed by the archive page) is highlighted: the li tag enclosing the link to this category has one more class than the other, named current-cat. Você não precisa fazer nada para ativar esse comportamento, e não pode desativá-lo (mas você é livre para não usá-lo em seu CSS!).

Entretanto, talvez seja um comportamento que você queira ver em mais páginas, como aquelas que exibem um post. A boa notícia é que você pode, graças à opção current_category. Este booleano está definido como 0 por padrão. Ao configurá-lo para 1 a categoria atual será destacada com a classe previamente citada.

$args = array('current_category' => 1);

Por exemplo, vamos assumir que exibimos a lista das nossas categorias no template single.php. Então, com o array anterior, a categoria do post atual será destacada graças à classe current-cat. Tudo que temos que fazer agora para exibi-la é adicionar o CSS.

Showing the Hierarchy

Se você tem muitas categorias, é uma boa idéia organizá-las em hierarquias lógicas, onde encontramos categorias dos pais e seus filhos por baixo delas. Existem várias opções para lidar com a exibição das hierarquias.

Vemos primeiro hierarchical. É um booleano definido por padrão para 1, onde wp_list_categories() mostra a hierarquia entre as categorias (com pais e filhos), exatamente como nas capturas de tela desde o início deste artigo. Se você não quiser mostrar sua hierarquia você pode defini-la como 0: suas categorias serão então listadas em uma coluna sem recuar as categorias dos filhos.

Note o efeito colateral de hierarchical: se você optar por exibir a hierarquia, então as categorias dos pais serão sempre mostradas, mesmo que estejam vazias e a opção hide_empty esteja definida para 1.

// Don't show me the hierarchy$args = array('hierarchical' => 0);

Você também pode usar a hierarquia para fazer outras coisas como exibir os filhos de uma determinada categoria usando child_of . Poderíamos descrevê-lo como o oposto de exclude_tree: damos-lhe o ID de uma categoria e wp_list_categories() exibirá apenas os seus filhos. No entanto, o nome da categoria dos pais não é exibido.

// Show me all the children of this category$args = array('child_of' => 14);

Não é como exclude_tree, só podemos passar um único ID para child_of.

A opção depth permite controlar o número de níveis que podem ser exibidos na lista. Pode ser útil se você adora categorias e tem uma árvore complexa com muitas gerações. Por defeito está definida para 0 e mostra todas as gerações. O exemplo abaixo mostra apenas dois níveis de categorias: os pais e seus filhos de primeiro nível. Se essas crianças tiverem suas próprias categorias de filhos, elas não serão mostradas.

$args = array('depth' => 2);

Nota que depth está ligada a hierarchical. Na verdade, se você definir hierarchical para 0, dando um valor para depth será inútil: todas as categorias serão mostradas, independentemente dos seus níveis na árvore. Pelo contrário, você também pode anular o valor de hierarchical com depth em um caso: você define depth para -1. O efeito deste valor é exibir todas as categorias sem qualquer relação. Todas as categorias serão mostradas em uma coluna, mesmo que hierarchical esteja definido como 1.

Controlando a Saída

Por padrão, wp_list_categories() mostra a lista das nossas categorias. Se você não quiser isso e preferir armazenar o resultado em uma variável para exibi-la mais tarde, você pode definir echo para 0.

$args = array('echo' => 0);$cats = wp_list_categories($args);

Isso pode ser útil se você quiser modificar a lista antes de exibi-la.

Próximo, vamos olhar para show_option_none. Por padrão, se wp_list_categories() não encontrar nenhuma categoria (pode acontecer se as outras opções forem muito restritivas, por exemplo), ele exibe o texto “Sem categorias”. Você pode alterar isto para o texto que você quer usando esta opção.

$args = array('show_option_none' => 'Nothing found :(');

Next title_li. Em nossos testes, você deve ter notado que a lista de categorias está encapsulada em um item de outra lista. Isto pode ser útil se você usar wp_list_categories() em um menu, por exemplo. Além disso, o WordPress exibe um título para esta lista, que é por padrão “Categorias”.

Você pode modificar este título padrão ou mesmo desabilitá-lo jogando com title_li. Ele aceita uma string, que é o título a ser exibido. Se você der a esta opção uma string vazia, a lista de categorias não será encapsulada em outra lista.

$args = array('title_li' => 'My awesome categories');

Tenha cuidado: se você desabilitar a exibição da lista com uma string vazia você deve incluir sua lista em ul tags!

Você não gosta de listas? Você vai adorar a opção style: por padrão ela está definida como list e wp_list_categories() exibe categorias como itens da lista. Se você definir style para none, suas categorias serão separadas por br tags.

$args = array('style' => 'none');

Finalmente, você pode pedir ao WordPress para exibir um link para todas as suas categorias graças à opção show_option_all. Você dá uma string a esta opção, e o WordPress exibirá um novo link, apontando para todas as suas categorias.

$args = array('show_option_all' => 'All categories');

Conclusion

É isso para wp_list_categories(). O número de opções disponíveis para esta função é bastante grande, como você pode ver.

Obviamente, a API de Categorias não está limitada a esta função. No entanto, é uma importante: se você não tem nenhuma necessidade específica e apenas quer uma lista básica de categorias, não procure por outra função, esta é sua opção mais simples!

Nota que não falamos neste artigo sobre wp_dropdown_categories(). Esta função exibe nossas categorias em um elemento HTML dropdown. Como wp_list_categories(), sua saída pode ser totalmente personalizada graças a um conjunto de opções. Estas opções são semelhantes às disponíveis com wp_list_categories() , por isso não as vamos descrever aqui. A única dificuldade é que algumas opções têm outros valores padrão. Para saber mais sobre wp_dropdown_categories(), você pode ir para o Codex WordPress.

Mas ainda existem outros casos: e se quisermos exibir nossas categorias de uma forma especial? Neste caso, wp_list_categories() não é suficientemente flexível, pois precisamos de construir a nossa própria árvore DOM. É por isso que, no próximo artigo, vamos dar uma olhada em algumas outras funções úteis na API Categories API.