Este é o Guia Definitivo sobre Custom Post Types, criado pela Escola WordPress para ajudar todos os developers e begginers. Faz parte de uma série de Tutoriais WordPress divididos em quatro partes, que abrange toda a API dos tipos de posts e categorias customizados. Iremos explicar-lhe passo-a-passo como criar diferentes Custom Post Types no WordPress e estratégias para utilizar este fantástico recurso do WordPress para melhorar os seus Temas WordPress e/ou torná-los ainda mais eficientes.

CONTEÚDOS DE CADA PARTE:

Parte 1: Criar tipos de posts e de categorias customizados:

  • O que são tipos de posts e categorias customizados?
  • Criar tipos de posts customizados
  • Criar categorias costumizadas
  • Extender o URL com o parâmetro rewrite
  • Adicionar as Tags ao tipo de post

Parte 2: Estrutura e apresentação dos tipos de posts customizados

  • Preparar o seu tema para receber os seus tipos de posts
  • Acrescentar campos usando metaboxes
  • Embeber ficheiros javascript e folhas de estilo CSS no cabeçalho da página da Administração

Parte3: Extender as capacidades dos tipos de post

  • Definir mensagens de atualização customizadas
  • Criar texto de ajuda contextualizada para o tipo de post
  • Modificar e  acrescentar colunas na página de listagem do tipo de post
  • Editar e acrescentar “Ações em Massa”

Parte 4: Tipos de post e taxonomias

  • Extender, acrescentando novos campos as taxonomias
  • Apresentar as taxonomias customizadas no website
  • Criar um filtro a partir da taxonomia na página de listagem de tipos de post

Parte 5: URL Rewrites, Roles e Segurança nos tipos de post

  • Extender as URLs permanentes através da Rewrite API
  • Adicionar um novo papel de utilizador e novas meta capacidades ao tipo de post
  • Validar e segurar os inputs dos seus usuários

Neste primeiro artigo iremos mostrar como é que se pode criar um tipo de post customizado e associar novas categorias aos tipos de post existentes. Ao longo do artigo iremos extendendo o conhecimento da API e mostrar os truques que os developers usam para criar tipos de post customizados com várias funcionalidades.

O QUE SÃO OS TIPOS DE POSTS E CATEGORIAS CUSTOMIZADOS?

Antes do WordPress 3.0, o utilizador e os developers só podiam usar os tipos de post definidos pelo WordPress:

Posts, Páginas, Mídia e Links eram os únicos tipos de posts que existiam e não era possível criar novos. Assim os developers, quando necessitavam de criar novos tipos de conteúdos tinham que se suportar nas Categorias para realizar conteúdos diferentes para cada post.

Com as novas versões do WordPress é possível criar novos tipos de conteúdos separados dos Posts para gerir estes conteúdos diferentes. Por exemplo, é possível criar um tipo de conteúdo para albergar uma base de dados de filmes, criando esse tipo de post e chamando-lhe Filmes. Para isso basta chamar a função register_post_type() e o WordPress irá encarregar-se por nós de criar o menu na administração, criar toda a interface de edição e listagem e todas as relações necessárias.

Porém, não são só os tipos de posts que nós podemos criar. Tipos de categoria customizados também é possível. Para a tipo Filmes podemos associar, por exemplo, um tipo de categoria: Categoria de Filmes.

Se assim o fizermos, este tipo de categoria irá aparecer na interface de edição dos filmes, assim como aparecem Categorias e Tags para os Posts.

No nosso ficheiro para download temos os exemplos que apresentamos aqui. Para conveniencia é preferível ir seguindo este tutorial com o ficheiro de exemplos. O ficheiro encontra-se no rodapé deste artigo.

CRIAR TIPOS DE POSTS CUSTOMIZADOS

Para adicionar um tipo de post customizado, é preciso usar a função register_post_type. Esta função permite que você defina o tipo de post e como ele se comporta dentro doWordPress. Esta função é responsável por, passando-lhe os parâmetros pretendidos, fazer as associações necessárias e a criação de toda a interface para este tipo de post.

Assim, para criar o tipo de post mais simples colocamos o seguinte no ficheiro functions.php:

add_action( 'init', 'create_post_type_film' );
function create_post_type_film() {
    register_post_type( 'film',
        array(
            'labels' => array(
                'name' => __( 'Films' ),
                'singular_name' => __( 'Film' )
            ),
            'public' => true,
        )
    );
}

Esta função regista um tipo de post film (parâmetro passado no primeiro argumento da função) que é público, ou seja, pode ser mostrado no blog, e que tem como nome plural Films e nome singular Film. As funções de tradução __() foram incluídas neste exemplo, uma vez que é normal os tipos de post estarem preparados para tradução. Pode encontrar um bom artigo sobre o sistema de traduções no WordPress aqui.

Obviamente, estes não são os únicos parâmetros de registo dos tipos de post, se assim fosse, serviria para muito pouco não acham? :)

Podemos controlar todo o comportamento deste tipo de post passando-lhe os parâmetros que achamos necessários:

DEFININDO NOVAS LABELS

Para modificar as labels associadas ao tipo de post film, ou seja, as strings usadas na administração para mostrar este tipo de post, basta passar à função um array com todas as labels modificadas. De outro modo, irá aparecer post em vez de film aquando da visualização na administração:

$labels = array(
    'name' => _x('Films', 'post type general name'),
    'singular_name' => _x('Film', 'post type singular name'),
    'add_new' => _x('Add New', 'film'),
    'add_new_item' => __('Add New Film'),
    'edit_item' => __('Edit Film'),
    'new_item' => __('New Film'),
    'all_items' => __('All Films'),
    'view_item' => __('View Film'),
    'search_items' => __('Search Films'),
    'not_found' =>  __('No Films found'),
    'not_found_in_trash' => __('No Films found in Trash'),
    'parent_item_colon' => '',
    'menu_name' => 'Films'
);

Este array deverá ser incluído dentro da função no lugar de ‘labels’ para que surta efeito:

'labels' => $labels,

CONTROLANDO O COMPORTAMENTO

Novos parâmetros podem ser passados à função de modo a controlar o comportamento deste tipo de post. Para isso podemos criar um array com esses parâmetros:

$args = array(
    'labels' => $labels,
    'public' => true,
    'publicly_queryable' => true,
    'show_ui' => true,
    'show_in_menu' => true,
    'rewrite' => true,
    'capability_type' => 'post',
    'has_archive' => true,
    'hierarchical' => false,
    'menu_position' => null,
    'supports' => array('title','editor','author','thumbnail','excerpt','comments')
  );

Este array apresenta os parâmetros essênciais e mais importantes. Existem mais, e você pode vê-los todos aqui no Codex do WordPress e explorar os tipos de post à sua vontade. Tenha sempre em atenção para não o fazer no seu blog de produção, use uma instalação local no seu computador para fazer esses testes.

Parâmetros aceites pela função:

  • public – apresenta ou não o tipo de post na administração do WordPress
  • public_queryable – se este tipo de post pode ou não ser visto no front-end do blog
  • show_ui – se deve ou não ser construída uma interface por defeito
  • show_in_menu – se é ou não adicionado um link no menu da asministração
  • rewrite – estando os links permamentes ligados, se deve este post type ter um URL próprio
  • capability_type – capacidades que os usuários deverão ter para poder editar este tipo de post
  • has_archive – se o tipo de post deve ou não ter uma listagem no front-end
  • hierarchical – deve ou não este tipo de post ter a funcionalidade de associar hierarquias como nas páginas
  • menu_position – passando um número a este parâmetro, controlamos a localização do link no menu (nota: os números devem ser passados de 5 em 5. Exemplo: 5, 10, 15, 20, ….
  • supports – o que este tipo de post deve conter ou não

No ficheiro para download encontra-se este código incorporado.

CRIAR CATEGORIAS CUSTOMIZADAS

O processo é exatamente o mesmo, mas agora com a função register_taxonomy(). Esta função aceita como parâmetros o ID da categoria que estamos a adicionar, um array com os tipos de posts associados e um array com os parâmetros que alteram o seu comportamento:

add_action( 'init', 'create_taxonomy_film_category' );
function create_taxonomy_film_category() {
    register_taxonomy( 'film_category', array( 'film' ), array(
        'hierarchical' => true,
        'label' => __( 'Film Category' ),
        'show_ui' => true,
        'show_in_tag_cloud' => true,
        'query_var' => true,
        'rewrite' => true,
        )
    );
}

Neste trecho de código dissemos à função para registar um tipo de categoria chamado ‘film_category’, que se associa ao tipo de post ‘film’ e que recebe uns quantos parâmetros para controlo do seu comportamento. Estes são os parâmetros:

  • hierarchical – se esta categoria customizada deve conter hierarquia, semelhante às Categorias do Posts. Caso seja passado false a categoria será idêntica às Tags dos Posts.
  • label – o nome da categoria que será visível na administração.
  • show_ui – se deve ou não ser mostrada no menu da administração.
  • show_in_tag_cloud – conhece aquele widget que produz um núvem das tags mais usadas? este parâmetro define se deve ou não aparecer nessa núvem.
  • query_var – se esta categoria pode ser visualizada a partir do front-end.

Estes são os parâmetros mais importantes e usuais. Se quiser aprofundar o seu conhecimento, poderá dirigir-se ao Codex do WordPress e ver todos os parâmetros que esta função aceita.

DEFININDO NOVAS LABELS

Tal como nos tipos de post, é possível definir novas labels para as categorias customizadas. Para isso procedemos da mesma maneira, passando à função um array com os labels pretendidos:

'labels' => array(
    'name' => _x( 'Categories', 'taxonomy general name' ),
    'singular_name' => _x( 'Category', 'taxonomy singular name' ),
    'search_items' =>  __( 'Search Categories' ),
    'all_items' => __( 'All Categories' ),
    'parent_item' => __( 'Parent Category' ),
    'parent_item_colon' => __( 'Parent Category:' ),
    'edit_item' => __( 'Edit Category' ),
    'update_item' => __( 'Update Category' ),
    'add_new_item' => __( 'Add New Category' ),
    'new_item_name' => __( 'New Category Name' ),
    'menu_name' => __( 'Category' ),
  ),

EXTENDER AS URLS COM O PARÂMETRO REWRITE E ADICIONAR TAGS AOS TIPOS DE POSTS

Entender o ciclo interno das ligações permanentes (rewrite links) é algo complicado e será matéria para um dos próximos capítulos da série, porém, sem termos que nos preocupar com as questões desse ciclo, podemos já começar por alterar e mudar o comportamento das URLs para os nossos tipos de posts e de categorias. Para isso passamos um array ao parâmetro rewrite para controlar algumas das suas propriedades.

REWRITE NOS TIPOS DE POSTS

Para controlar as URLs dos tipos de posts deve-se passar estes parâmetros da seguinte forma:

'has_archive' => 'films',
'rewrite' => array(
    'slug' => 'films',
    'with_front' => false,
),

Se for passado uma string ao parâmetro has_archive, esta será usada como URL da página de listagem dos filmes, aparecendo como http://o-seu-site.com/films/.

Para manter uniforme, passamos também ao parâmetros slug dentro do rewrite a mesma string. Desta maneira o seu site terá a seguinte estrutura de URL para o tipo de post filme:

Listagem de Filmes: http://o-seu-site.com/films/

Página de detalhe de um Filme: http://o-seu-site.com/films/o-nome-do-filme/

REWRITE DE CATEGORIAS CUSTOMIZADAS

Para controlar os URLs das categorias customizadas, passamos os parâmetros do rewrite da seguinte forma:

'rewrite' => array(
   'slug' => 'films/categories',
   'with_front' => false,
),

Normalmente uso uma estrutura de URLs adequada, neste caso a todas as categorias de filmes estão sobre a URL http://o-seu-site.com/films/categories/nome-da-categoria

Em ambos os casos, se o parâmetro with_front for verdadeiro, prefixa a estrutura de URLs com o parâmetro de acesso ao blog de posts, por exemplo http://o-seu-site.com/blog/films/o-nome-do-filme/

ADICIONAR TAGS AO TIPO DE POSTS

Para associar as categorias de Tags ao tipo de post, isto é, para aparecerem na administração como tipo de categoria associada aos FIlmes, existe uma função que o faz facilmente e direitinho:

register_taxonomy_for_object_type( 'tags', 'film' );

Esta função deve ser chamada após o registo dos tipos de posts e das categorias envolvidas.

Faça o Download do código deste tutorial!

Por enquanto é tudo, espero que gostem desta nova série aqui no Escola WordPress.

Até breve e bons estudos!

Vitor