Trabalhar com requisições AJAX no WordPress requer o uso de alguns procedimentos básicos. O processo para esse tipo de requisição deve ser seguido, pois com ele é possível carregar o WordPress e definir as instruções a serem processadas de dentro de um Tema ou Plugin.

Para exemplificar o processo foi criado um plugin que insere ao final do conteúdo dos posts um link para exibir o email do administrador do site (editável em Configurações > Geral > Endereço de email). Apenas um exemplo que pode ser expandido ou adptado para buscar e exibir qualquer informação que seja gerenciada pelo WordPress.

Requisição AJAX no WordPress

Uma requisição AJAX direcionada ao endereço do site ou diretamente a um arquivo do Tema ou de algum plugin não traria o efeito desejado ao desenvolvedor. No primeiro caso seriam executadas todas as rotinas de front-end e sem o devido tratamento o retorno seria o próprio HTML do Tema, sem muitas possibilidades. Já em requisições direcionadas a um arquivo específico, as rotinas do WordPress não seriam carregadas e assim não poderiam ser utilizadas por esse arquivo.

Por tais razões o WordPress disponibiliza um arquivo onde as requisições devem ser direcionadas. Esse arquivo é o wp-admin/admin-ajax.php. Apontando a requisição para esse endereço é preciso enviar em meio aos dados (pode ser via $_GET ou via $_POST, independente) a variável action.

O valor da variável action vai determinar a criação dos ganchos a serem usados dentro do Tema ou dos Plugins:

  • wp_ajax_[action]: para requisições privadas, onde o usuário está logado;
  • wp_ajax_nopriv_[action]: para requisições públicas, não logado.

Um pouco de código auxiliará o entendimento desse processo. A começar pela criação do plugin:

// Plugin Name: JavaScript no WordPress - Ajax
class WPJS_Ajax
{
    public static function setup()
    {
        add_action( 'wp_enqueue_scripts', array( 'WPJS_Ajax', 'ajax' ) );
    }

    public static function ajax()
    {
        wp_enqueue_script( 'wpjs-ajax-js', plugin_dir_url( __FILE__ ) . 'wpjs-ajax.js', array( 'jquery' ), null, true );
        wp_localize_script(
            'wpjs-ajax-js',
            'wp_obj',
            array(
                'ajax_url' => admin_url( 'admin-ajax.php' )
            )
        );
    }
}
add_action( 'plugins_loaded', array( 'WPJS_Ajax', 'setup' ) );

O registro do arquivo JS está sendo feito no mesmo momento em que é incorporado à página. Em seguida a função wp_localize_script é responsável por fazer a comunicação, transmitir variáveis do WordPress para o escopo do JavaScript. A função recebe o identificador do código ao qual está submetida, seguida de um objeto que será usado no arquivo .js e por fim um array com as propriedades desse objeto.

Do lado JavaScript para acessar esses valores basta referenciar o nome do objeto e o nome da propriedade. Com isso o código JS para a requisição ficará do seguinte modo:

$.ajax({
    url: wp_obj.ajax_url,
    type: 'post',
    data: {
        action: 'get_admin_email'
    },
    dataType: 'html',
    success: function ( r ) {
    }
});

Retomando o funcionamento do uso de AJAX no WordPress, devem ser criados os ganchos para receber os dados e processar a requisição no arquivo PHP. Dentro do método setup:

add_action( 'wp_ajax_get_admin_email', array( 'WPJS_Ajax', 'ajax_action' ) );
add_action( 'wp_ajax_nopriv_get_admin_email', array( 'WPJS_Ajax', 'ajax_action' ) );

O mesmo valor passado através da variável action está representado em wp_ajax_ e wp_ajax_nopriv_. Com isso, tanto usuários logados como deslogados, terão acesso ao recurso. E o método ajax_action, da classe do plugin, é o que será executado quando a requisição acontecer.

public static function ajax_action()
{
    printf(
        '<a href="mailto:%1$s" title="Fale com o administrador">%1$s</a>',
        get_option( 'admin_email' )
    );
    wp_die();
}

As informações do método devem ser exibidas em tela pelo PHP (echo, print, printf, etc). Ao final dos processos o script deve ser interrompido para que não apareça a string ‘0’ usada pelo WordPress como retorno caso a action não tenha sido encontrada ou executada devidamente.

Utiliza-se preferencialmente a função wp_die para que sejam disparadas as rotinas atribuídas ao filtro wp_die_ajax_handler. Caso isso não seja relevante a requisição, as instruções podem terminar com o uso de exit ou die do PHP.

Download da classe exemplo de requisições AJAX no WordPress