Tutorial: Como adicionar uma ação em massa personalizada no WordPress Admin

Acima da maioria das tabelas de elementos de administração do WordPress (por exemplo, posts, páginas, comentários, plugins e usuários), você encontrará a funcionalidade do WordPress para ações em massa. As ações em massa permitem que você marque vários elementos, escolha uma ação e execute essa ação para todos os elementos de uma só vez. Neste post, veremos como adicionar nossas próprias ações personalizadas em massa ao administrador do WordPress.

Adicionar uma ação em massa personalizada se tornou muito mais fácil nas versões recentes do WordPress (desde 4.7). Há um filtro para as opções disponíveis na lista suspensa; outro filtro para o que deve fazer quando sua opção for escolhida e outro gancho para mostrar opcionalmente um aviso do administrador. Vamos passar por cada um deles.

Adicionando uma ação em massa personalizada na lista suspensa

Vamos começar adicionando nossa escolha em massa personalizada à lista suspensa de ações em massa. Para isso, usamos o filtro bulk_actions_<screen>, onde você substitui por qualquer tela de administrador à qual deseja que sua opção seja adicionada. Aqui está uma visão geral completa das opções possíveis para a tela:

• bulk_actions-edit-post: Tela de edição do tipo de post ‘post’
• bulk_actions-edit-page: Tela de edição do tipo de postagem ‘página’
• bulk_actions-edit-<post-type-name>: Tela de edição de tipo de postagem personalizada
• bulk_actions-edit-<custom-taxonomy>: Tela de edição de taxonomia personalizada
• bulk_actions-edit-comments: Tela da lista de comentários
• bulk_actions-plugins: Tela da lista de plugins
• bulk_actions-users: Tela da lista de usuários
• bulk_actions-upload: Lista da biblioteca de mídia (só funciona no modo de exibição de lista, não no modo de exibição de grade)

O filtro é aplicado em uma matriz com pares de valores-chave; onde as chaves são uma chave exclusiva para ações e os valores são o rótulo que aparece na lista suspensa.

Vejamos um exemplo. Quero criar uma ação em massa para definir postagens como publicadas.

add_filter('bulk_actions-edit-post', function($bulk_actions) {
    $bulk_actions['change-to-published'] = __('Change to published', 'txtdomain');
    return $bulk_actions;
});

Se você salvar e atualizar a tela de edição de postagens, deverá ver sua opção no menu suspenso.

A partir de agora, nossa ação em massa personalizada está sendo absolutamente zip. Esse é o próximo passo.

Fazendo com que nossa ação em massa personalizada faça algo

Para acionar algo ao escolher nossa opção recém-adicionada no dropwon, conectamos o filtro handle_bulk_actions-<screen>. Consulte a visão geral acima para possíveis valores de tela. Obviamente, seu gancho de alça deve ser a mesma tela que a tela na qual você adicionou a ação em massa na primeira etapa.

Você tem três argumentos possíveis neste filtro. O primeiro – aquele que você retorna – é na verdade um URL para o qual o WordPress deve redirecionar depois de terminar com sua ação em massa. O segundo argumento é o nome da ação que foi escolhida na lista suspensa. E o terceiro é uma matriz de todos os IDs de elemento que foram verificados para a ação em massa. Estes são os elementos sobre os quais precisamos aplicar nossa ação.

Vamos ver o que o código acima faz passo a passo. Primeiro, precisamos verificar se a ação em massa executada foi realmente nossa ação personalizada; change-to-published. E então cabe a nós fazer o que quisermos com todos os IDs.

O código acima percorre todos os IDs de postagem e executa wp_update_post()em cada um para alterar seu status de postagem para publicado. (Se você quiser que isso seja eficiente, considere atualizar apenas aqueles que de fato ainda não foram publicados).

Depois que terminarmos de fazer nossa ação nos elementos selecionados, precisamos criar uma URL para redirecionar depois que o WordPress for concluído. Adicionamos um argumento personalizado ao URL de redirecionamento fornecido. Isso é opcional, mas necessário se quisermos mostrar um aviso do administrador. Podemos adicionar o que você quiser. Mas no exemplo acima estamos simplesmente adicionando um novo argumento de consulta com add_query_arg()a configuração ‘ changed-to-published‘ para o número de IDs de postagem que foram afetados. Esta é uma informação útil para um aviso.

Mostrar um aviso após a conclusão de nossa ação em massa personalizada

Se você executar nossa ação em massa personalizada agora, você notará que depois que o WordPress concluir a ação em massa, ele recarregará a página com o seguinte na URL: “wp-admin/edit.php?changed-to-published=2". “2" é o número de postagens nas quais aplicamos nossa ação. Isso nos permite adicionar um aviso de administração personalizado que é acionado se ‘alterado para publicado’ estiver definido.

Para mostrar os avisos do administrador, podemos usar a ação admin_notices. Verificamos a variável global do PHP, $_REQUEST, que é preenchida com os valores enviados pelo formulário se ‘ changed-to-published‘ existir. Se isso acontecer, isso significa que nossa ação em massa personalizada acabou de ser executada. Em seguida, exibiremos algum texto, incluindo o número de postagens aplicadas.

E é isso!

Outros usos da ação em massa personalizada

Tenha em mente que no handle_bulk_actions-<screen>gancho você pode fazer basicamente o que quiser nos elementos selecionados. Você pode atualizar meta de postagem personalizada, alterar funções nos usuários, enviar um e-mail ou postar uma solicitação HTTP para algum aplicativo de terceiros.

Por exemplo; se você quiser que uma ação em massa atualize uma meta de postagem personalizada que informa se as postagens são verificadas ou não, usando uma ação em massa personalizada com a chave ‘ mark-as-verified‘:

add_filter('handle_bulk_actions-edit-post', function($redirect_url, $action, $post_ids) {
    if ($action == 'mark-as-verified') {
        foreach ($post_ids as $post_id) {
            update_post_meta($post_id, 'verified', '1');
        }
        $redirect_url = add_query_arg('mark-as-verified', count($post_ids), $redirect_url);
    }
    return $redirect_url;
}, 10, 3);

Combine o acima com uma coluna personalizada que mostra o valor de ‘verified’ nas listas de posts – como fizemos neste post, e fica mais útil.