O porquê e como dos eventos personalizados do jQuery

Já na versão 1.0, o jQuery forneceu uma função de gatilho que nos permite:

Execute todos os manipuladores e comportamentos anexados aos elementos correspondentes para o tipo de evento fornecido.

Mas não foi até 1.3 que essa função específica se tornou significativamente mais útil, pelo menos no que me diz respeito. Digo isso porque foi quando ganhamos a capacidade de definir eventos personalizados e, em seguida, definir manipuladores para eles.

No entanto, qual é um caso de uso provável em que os eventos personalizados do jQuery são úteis no contexto do WordPress? De cabeça, você pode criar muitos. Ou talvez não.

Não foi até recentemente que eu os tenho usado significativamente mais do que o habitual. Então, pensei em compartilhar como estou usando-os se por agora outra razão além de mostrar como conectá-los ao seu trabalho.

Eventos jQuery personalizados

Se você tem experiência com JavaScript – vanilla ou não – provavelmente está familiarizado com manipuladores de eventos básicos. Ou seja, quando alguém clica em um elemento, temos uma função definida para disparar que faz algo.

Os eventos personalizados do jQuery são muito parecidos com isso, exceto que são eventos que definimos. Isso significa que não precisamos depender de quando alguém move o mouse sobre um elemento ou quando clica em um elemento.

Em vez disso, podemos acionar um evento e, em seguida, ter um manipulador configurado para responder adequadamente. Aqui está um exemplo.

Preparando-se para um evento personalizado

Digamos que você esteja trabalhando em um projeto e ele tenha uma página de administração responsável por recuperar dados de uma API de terceiros. O fluxo de controle ficaria assim:

1. O usuário clica em um botão,
2. Uma solicitação Ajax é iniciada e solicita informações de terceiros,
3. Enquanto a requisição está acontecendo, os botões na tela devem estar desabilitados,
4. Depois que a solicitação for concluída, os botões podem ser reativados,
5. Opcionalmente, uma mensagem de status pode ser gravada na tela.

Para que isso aconteça, espera-se que haja pelo menos um botão (como em um elemento de entrada) e um campo de texto ou área de texto opcional em que o status da solicitação possa acontecer.

Assim que o usuário clicar no evento, podemos acionar um evento personalizado. Podemos chamar esse evento de acme.ajax.processing. Em seguida, podemos usar a função done fornecida pelo jQuery para lidar com qualquer coisa que queiramos limpar posteriormente ou podemos usar nossa função personalizada se houver algo que queremos manipular no final também.

Para este ambos, vamos olhar para ambos. Então também teremos um evento chamado acme.ajax.complete.

Então estamos preocupados com:

• criando um evento personalizado,
• acionando-o,
• configurando um manipulador de eventos para ele,
• terminando assim que o pedido for concluído.

E é isso que faremos.

Definindo um evento personalizado

Então, quando um usuário clica em um botão, uma solicitação Ajax está fazendo para ser feita. Ao mesmo tempo, isso também acionará o evento acme.ajax.processing que terá seu manipulador de eventos.

Então, primeiro, vamos criar a solicitação Ajax. Para isso, vou assumir que o botão responsável por acionar a solicitação Ajax é simplesmente chamado de $button:

$button.on('click', function(evt) {
  evt.preventDefault();
  $(document).trigger('acme.ajax.processing');

  $.get(ajaxurl, {
    // Your action and security measures here.
  }, function(response) {
    // Your response behavior here.
  });
});

Observe que a primeira coisa que queremos fazer é acionar o evento de processamento e então fazemos a requisição.

Manipulando um evento personalizado

Em seguida, queremos ter certeza de que temos um manipulador de eventos configurado para desabilitar o botão enquanto a solicitação está acontecendo.

Isso é fácil de fazer e manter isso simples, e vou desabilitar o botão:

$(document).on('acme.ajax.processing', function() {
  $button.attr('disabled', 'disabled');
});

Fácil, certo?

Lidando com outro evento personalizado

Em seguida, precisamos lidar com a situação quando a solicitação Ajax for concluída. Portanto, precisamos ter certeza de acionar o evento e, em seguida, precisamos lidar com o evento.

Acionar o evento é fácil:

$button.on('click', function(evt) {
  evt.preventDefault();
  $(document).trigger('acme.ajax.processing');

  $.get(ajaxurl, {
    // Your action and security measures here.
  }, function(response) {
    // Your response behavior here.
  })
  .done(function() {
     $(document).trigger('acme.ajax.complete');
  });
});

E a manipulação do evento pode ser alterada para o código que já temos:

$(document)
  .on('acme.ajax.processing', function() {
    $button.attr('disabled', 'disabled');
  })
  .on('acme.ajax.complete', function() {
    $button.removeAttr('disabled');
  });

Ele pode ser encadeado porque está acontecendo no objeto do documento – não em um elemento separado.

Para esse fim, por isso é muito mais fácil de manusear.

Apenas um exemplo

Claro, este é apenas um exemplo de como lidar com eventos jQuery personalizados.

Existem muitas outras maneiras de fazer isso, e você pode fazer algumas coisas bem complicadas com isso; no entanto, isso deve fornecer informações suficientes para o que você precisa sobre como trabalhar com eventos personalizados em um nível fundamental.