Personalizando as tabelas de administração do WordPress: Introdução

Todos que usam o WordPress estarão familiarizados com as tabelas de administração do WordPress que aparecem em todas as principais áreas de visão geral, como páginas e postagens. O mesmo formato é usado para esses tipos de tabelas em todo o WordPress, o que significa que você rapidamente se torna adepto de usá-las. Mas você sabia que pode modificar as tabelas de administração do WordPress e alterar as informações exibidas ou adicionar suas próprias colunas extras?

Neste artigo vamos explicar como você pode fazer isso. Vamos começar!

Os Ganchos

Para mostrar os dados das tabelas de administração, o WordPress estende a WP_List_Table . A classe WP_List_Table é introduzida como uma classe privada no arquivo wp-admin/includes/class-wp-list-table.php . As classes privadas são denominadas privadas, pois destinam-se apenas ao uso por outras classes e funções principais e não por desenvolvedores.

O WordPress oferece a capacidade de alterar tabelas de administração. Para manipular as colunas das tabelas você tem que usar um dos hooks de filtro que o WordPress fornece no arquivo wp-admin/includes/class-wp-posts-list-table.php .

Neste arquivo, a classe WP_Posts_List_Table estende a classe WP_List_Table e redefine suas propriedades e métodos para preencher as tabelas administrativas de acordo com seu tipo de postagem. Você pode usar o gancho manage_posts_columns para a tabela de postagens, o manage_pages_columns para as páginas e manage_{$post_type}_posts_columns se quiser manipular as colunas de uma tabela de tipo de postagem personalizada.

As colunas que são usadas por padrão para os dados da tabela também são descritas neste arquivo. Em torno da linha 616, o array $posts_columns é introduzido e as seguintes colunas são adicionadas:

• A coluna da caixa de seleção 'cb' para ações em massa
• A coluna 'título' do post
• A coluna 'autor' para o autor do Post
• A coluna 'categorias' para as categorias às quais a postagem pertence
• A coluna 'tags' da postagem
• A coluna "comentários"
• A coluna 'data' publicada

Adicionando uma coluna personalizada às tabelas de administração

Adicionar uma coluna personalizada a uma tabela é algo que os desenvolvedores precisam fazer com frequência. Além disso, poder classificar suas colunas também é muito útil na hora de organizar o conteúdo. Demonstraremos como uma coluna personalizada é implementada para postagens, páginas e tipos de postagem personalizados e como podemos tornar essas colunas personalizadas classificáveis.

As tabelas da lista de postagens

Como exemplo, vamos ver como podemos adicionar uma coluna que descreve quando uma postagem foi modificada pela última vez. Esse pode ser um recurso realmente útil, especialmente se você administra um blog com muitos posts e deseja verificar quando cada um foi atualizado pela última vez. Vamos ver como isso pode ser implementado.

Para começar, temos que adicionar o nome da nova coluna ao array de nomes de cabeçalho de coluna. Vamos dar uma olhada na linha 663 do arquivo class-wp-posts-list-table.php .

 if ( 'page' === $post_type ) { $posts_columns = apply_filters( 'manage_pages_columns', $posts_columns ); } else { $posts_columns = apply_filters( 'manage_posts_columns', $posts_columns, $post_type ); }

Nesta parte do código fica claro que devemos usar o filtro manage_posts_columns (veja aqui para mais informações sobre isso) já que queremos fazer as alterações na tabela da lista de posts. Para adicionar o nome da coluna ao array de cabeçalhos de coluna vamos editar o arquivo functions.php do nosso tema ativo e inserir este pedaço de código:

 add_filter('manage_posts_columns','add_custom_columns'); function add_custom_columns( $columns ) { $columns['last_modified'] = 'Last modified'; return $columns; }

Agora, se atualizarmos a página da lista de postagens do administrador, podemos ver a coluna extra. Não haverá dados nesta coluna nesta fase.

Em nossa próxima etapa, precisamos informar ao WordPress qual conteúdo será exibido na coluna. Para fazer isso, usaremos a ação manage_posts_columns que faz parte da função pública column_default que é responsável pela saída das colunas. Essa ação corresponde apenas a tipos de postagem não hierárquicos, como postagens, e você pode localizá-la em torno da linha 1258.

O que realmente faremos aqui para preencher o conteúdo é executar uma instrução switch para todas as colunas personalizadas e, como o nome do cabeçalho é 'last_modified' (como registramos em nossa etapa inicial acima), ecoaremos nosso conteúdo. Para ecoar o conteúdo, usaremos a função get_post_field integrada do WordPress e retornaremos o campo desejado, que pode ser qualquer coluna da tabela wp_posts no banco de dados. Em caso de falha, retornará uma string vazia.

Então no arquivo functions.php vamos adicionar o código abaixo:

 add_action( 'manage_posts_custom_column','custom_columns_content', 10, 2 ); function custom_columns_content ( $column_id, $post_id ) { switch( $column_id ) { case 'last_modified': echo get_post_field('post_modified', $post_id); break; } }

Você pode confirmar que está funcionando conforme o esperado atualizando a página novamente.

Observe que o valor de 'Última modificação' para o segundo post que nunca foi modificado após sua publicação inicial é o mesmo que a data de publicação.

A Tabela da Lista de Páginas

Para fazer a mesma coisa na tabela de lista de páginas, adicionamos o nome da coluna da mesma forma ao array de nomes de cabeçalho de coluna. A diferença desta vez é que usaremos o hook manage_pages_columns como mostrado abaixo:

 add_filter('manage_pages_columns','add_custom_page_columns'); function add_custom_page_columns( $columns ) { $columns['last_modified'] = 'Last modified'; return $columns; }

Em seguida, adicionaremos o conteúdo usando o gancho manage_pages_custom_column em vez do manage_posts_custom_column que usamos antes.

 add_action( 'manage_pages_custom_column','custom_columns_content', 10, 2 ); function custom_columns_content ( $column_id, $post_id ) { switch( $column_id ) { case 'last_modified': echo get_post_field('post_modified', $post_id); break; } }

Depois de inserir o código acima em nosso arquivo functions.php , podemos confirmar que as coisas estão funcionando conforme o esperado visitando a tabela de administração de páginas em nossa área de administração, onde agora devemos ver uma coluna 'Última modificação'.

A tabela de tipo de postagem personalizada

Vamos primeiro criar um tipo de postagem personalizado inserindo o código abaixo em nosso arquivo functions.php :

 function my_custom_post_type() { register_post_type( 'mycpt', array( 'labels' => array( 'name' => __( 'Custom Post Types' ), 'singular_name' => __( 'Custom Post Type' ) ), 'public' => true, 'has_archive' => true, 'rewrite' => array('slug' => 'mycpt'), 'show_in_rest' => true, ) ); } add_action( 'init', 'my_custom_post_type' );

Em nosso menu de administração, notamos que um novo item foi adicionado chamado 'Custom Post Type'.

Se você não sabe como os tipos de postagem personalizados são criados e deseja saber mais, confira nosso artigo relacionado sobre como criar tipos de postagem personalizados.

Agora que temos nossa configuração de tipo de postagem personalizada, continuaremos adicionando nosso novo cabeçalho de coluna com seu conteúdo. Como mencionado anteriormente, no caso de um CPT (Custom Post Type) temos que usar o manage_{$post_type}_posts_columns para adicionar nossa coluna personalizada.

O {$post_type} deve ser idêntico ao primeiro argumento da função register_post_type() que neste caso é 'mycpt'.

Assim, o trecho de código que usaremos no arquivo functions.php para adicionar nosso cabeçalho de coluna será o seguinte:

 add_filter( 'manage_mycpt_posts_columns','add_mycpt_custom_columns'); function add_mycpt_custom_columns( $columns ) { $columns['last_modified'] = 'Last modified'; return $columns; }

E para preencher o conteúdo da coluna:

 add_action( 'manage_mycpt_posts_custom_column','fill_mycpt_posts_custom_column'); function fill_mycpt_posts_custom_column( $column_id, $post_id ) { switch( $column_id ) { case 'last_modified': echo get_post_field('post_modified', $post_id); break; } }

Os resultados devem ser algo assim:

Tornar as colunas classificáveis

Para tornar a coluna classificável, precisamos definir quais colunas personalizadas podem ser classificadas. Para fazer isso, usamos o manage_edit-{post-type}_sortable_columns com uma função de retorno de chamada.

Portanto, em cada caso de tipo de postagem, anexaremos o mesmo código (com nomes de função exclusivos, é claro).

Para postagens:

 add_filter( 'manage_edit-post_sortable_columns', 'sortable_post_columns' ); function sortable_post_columns( $columns ) { $columns['last_modified'] = 'Last modified'; return $columns; }

Para páginas:

 add_filter( 'manage_edit-page_sortable_columns', 'sortable_page_columns' ); function sortable_page_columns( $columns ) { $columns['last_modified'] = 'Last modified'; return $columns; }

Para nossos posts personalizados, digite (mycpt):

 add_filter( 'manage_edit-mycpt_sortable_columns', 'sortable_mycpt_posts_columns' ); function sortable_mycpt_posts_columns( $columns ) { $columns['last_modified'] = 'Last modified'; return $columns; }

Agora, se você visitar uma de suas tabelas de administração, verá que o cabeçalho da coluna personalizada é exibido como um link. Se você clicar nele, ele deverá classificar por data de modificação.

Desativar classificação de colunas

Para remover o recurso de classificação de uma coluna, basta removê-lo do array. Se, por exemplo, quisermos fazer isso para a coluna 'date', adicionaríamos uma linha extra de código unset($columns['date']) . Isso ficaria assim:

Para postagens:

 add_filter( 'manage_edit-post_sortable_columns', 'sortable_post_columns' ); function sortable_post_columns( $columns ) { $columns['last_modified'] = 'Last modified'; unset($columns['date']); return $columns; }

Para páginas:

 add_filter( 'manage_edit-page_sortable_columns', 'sortable_page_columns' ); function sortable_page_columns( $columns ) { $columns['last_modified'] = 'Last modified'; unset($columns['date']); return $columns; }

Para nossos posts personalizados, digite (mycpt):

 add_filter( 'manage_edit-mycpt_sortable_columns', 'sortable_mycpt_posts_columns' ); function sortable_mycpt_posts_columns( $columns ) { $columns['last_modified'] = 'Last modified'; unset($columns['date']); return $columns; }

Agora, se você visitar a tabela apropriada, notará que o rótulo Data não é mais clicável (e, portanto, essa coluna não é mais classificável).

Nesse ponto, vale destacar um detalhe que muitas vezes confunde os desenvolvedores do WordPress. Dê uma olhada na tabela abaixo que mostra os ganchos que usamos para Posts, Páginas e Posts Personalizados.

Você deve ter notado que os ganchos que usamos para classificar as colunas não seguem o padrão. Você esperaria que eles fossem manage_posts_sortable_columns , manage_pages_sortable_columns e manage_mycpt_posts_sortable_columns respectivamente. Infelizmente, isso é apenas uma questão de má nomeação. No entanto, é muito útil manter uma tabela de resumo como esta como um lembrete fácil.

Alterando a largura das colunas

Para ajustar a largura de uma coluna, usaremos o gancho de ação admin_head que o WordPress fornece e executa na seção head para todas as páginas de administração que incluem CSS ou JS.

Como exemplo, tente inserir o código abaixo no arquivo functions.php :

 add_action('admin_head', 'my_column_width'); function my_column_width() { echo '<style type="text/css">'; echo '.table-view-list.posts .column-title { width:120px !important; overflow:hidden }'; echo '</style>'; }

Aqui, usamos a classe .column-title da coluna title que é comum para todas as tabelas de administração, e as .table-view-list.posts . Combinados, eles garantem que o CSS seja aplicado apenas na tabela de lista de posts.

Para conseguir o mesmo para nossas outras telas de administração (como Páginas), usaremos table-view-list.pages .

Conclusão

Existem muitas possibilidades quando se trata de manipular as colunas do WordPress Admin Tables. Em artigos futuros, veremos mais alguns exemplos e forneceremos alguns truques úteis que você pode usar para aproveitar melhor suas tabelas de administração!