Como começar

Este artigo guia o leitor através das bases do AJAX e oferece dois exemplos práticos simples para poder começar.

O que é AJAX

AJAX (Asynchronous JavaScript and XML) é um termo criado recentemente para duas características poderosas dos browsers que existem há anos mas tem sido ignoradas por muitos criadores de páginas web até recentemente, quando aplicações como Gmail, Google suggest e Google Maps foram lançadas.

As duas principais características são a possibilidade de :

• efectuar pedidos ao servidor sem ter de recarregar a página
• analisar gramaticalmente e trabalhar com documentos XML

Passo 1 - Como fazer uma requisição HTTP

Para fazer uma requisição HTTP ao servidor usando JavaScript, você precisa de uma instância de uma classe que disponibilize essa funcionalidade. Tal classe foi primeiro introduzida no Internet Explorer sob a forma de um objecto ActiveX chamado XMLHTTP. Depois, o Mozilla, o Safari e outros browsers fizeram o mesmo, implementando uma classe de nome XMLHttpRequest que suporta os métodos e as propriedades do objecto ActiveX original da Microsoft.

Por isso, para criar uma instância (objeto) da classe pretendida compatível com multiplos navegadores, você pode fazer:

if (window.XMLHttpRequest) { // Mozilla, Safari, ...
    http_request = new XMLHttpRequest();
} else if (window.ActiveXObject) { // IE
    http_request = new ActiveXObject("Microsoft.XMLHTTP");
}

(só a título de exemplo, o código acima é uma versão simplificada do código a ser usado para a criação de uma instância XMLHTTP. Para um exemplo mais "vida real", dê uma olhada ao 3º passo deste artigo.)

Algumas versões de alguns browsers Mozilla não irão funcionar bem se a resposta do servidor não possuir um cabeçalho mime-type XML. Para satisfazer isto, você pode usar uma chamada extra a um método para ultrapassar o cabeçalho enviado pelo servidor, só no caso de não ser no formato text/xml.

http_request = new XMLHttpRequest();
http_request.overrideMimeType('text/xml');

A próxima coisa a ser feita é decidir o que quer fazer após receber a resposta do servidor ao seu pedido. Nesta etapa só precisa de dizer ao objecto pedido HTTP que função JavaScript irá processar a resposta. Isto é feito definindo a propriedade onreadystatechange do objeto ao nome da função JavaScript que pretende utilizar, por exemplo:

http_request.onreadystatechange = NomedaFunção;

Note-se que não existem chaves após o nome da função e não são passados parâmetros. Também, em vez de dar um nome a função, você pode usar a técnica JavaScript de definir funções na hora (chamadas funções anônimas) e definir as ações que vão processar a resposta logo, por exemplo:

http_request.onreadystatechange = function(){
    // processar resposta do servidor
};

Em seguida, após ter declarado o que vai acontecer mal receba a resposta, você precisa de consumar o pedido. Precisa de chamar os métodos open() e send() da classe pedido HTTP, por exemplo:

http_request.open('GET', 'https://www.dominio.com.br/arquivo.extensao', true);
http_request.send(null);

• O primeiro parâmetro da chamada do método open() é o método pedido HTML – GET, POST, HEAD ou outro método qualquer que queira usar e que seja suportado pelo seu servidor. Mantenha o nome do método em maiúsculas para obedecer às normas HTTP senão certos browsers (como o Firefox) podem não processar o pedido. Para obter mais informação sobre os possíveis métodos pedido HTTP pode dar uma olhadela em W3C specs
• O segundo parâmetro é a URL da página que está a pedir. Como medida de segurança, não pode efectuar pedidos de páginas de domínios externos. Certifique-se que usa o nome exacto do domínio em todas as suas páginas ou irá receber um erro "Permissão Negada" quando efectua uma chamada open(). Um erro comum é aceder ao seu domínio através de domínio.tld ao mesmo tempo que tenta chamar páginas com www.domínio.tld.
• O terceiro parâmetro define se o pedido é assíncrono. Se TRUE, a execução da função JavaScript irá continuar enquanto que a resposta do servidor ainda não foi recebida. Isto é o A de AJAX.

O parâmetro do método send() pode ser costituido por quaisquer dados que pretenda enviar ao servidor ao enviar (POST) o pedido. Os dados devem estar sob a forma de uma linha de texto de pergunta, tipo:

name=value&anothername=othervalue&so=on

ou em vários outros formatos, incluindo JSON, SOAP, etc.

Note-se que se pretende enviar (POST) dados, você deve alterar o tipo MIME do pedido usando a seguinte linha:

http_request.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');

De outra forma o servidor irá ignorar os dados (post).

Pode-se também colocar o charset desejado assim:

http_request.setRequestHeader('Content-Type',
                           "application/x-www-form-urlencoded; charset=iso-8859-1");

Outro ponto importante é controle do cache, pois caso haja necessidadde de reenviar a consulta, pode ser que o objeto retorne o que está no cache do navegador. Para evitar esse tipo de transtorno as linhas abaixo eliminam essas possibilidades:

 http_request.setRequestHeader("Cache-Control",
                               "no-store, no-cache, must-revalidate");
http_request.setRequestHeader("Cache-Control",
                              "post-check=0, pre-check=0");
http_request.setRequestHeader("Pragma", "no-cache");

Passo 2 - Manipulando a resposta do servidor

Lembre-se que quando estava a enviar o pedido, você providenciou o nome de uma função JavaScript que é criada para lidar com a resposta.

http_request.onreadystatechange = nameOfTheFunction;

Vamos a ver o que é que esta função deve fazer. Primeiro, a função precisa de verificar o estado do pedido. Se o estado possui o valor 4, isso significa que a totalidade da resposta do servidor foi recebida e que pode continuar a processá-la à vontade.

if (http_request.readyState == 4) {
    // everything is good, the response is received
} else {
    // still not ready
}

A lista completa dos valores readyState é a seguinte:

• 0 (não inicializado)
• 1 (a carregar)
• 2 (carregado)
• 3 (interativo)
• 4 (completo)

(Source)

A próxima coisa a verificar é o código do estado da resposta HTTP do servidor. Todos os códigos possíveis estão listados na página W3C. Para os nossos objectivos nós só estamos interessados na resposta 200 OK.

if (http_request.status == 200) {
    // perfect!
} else {
    // there was a problem with the request,
    // for example the response may be a 404 (Not Found)
    // or 500 (Internal Server Error) response codes
}

Depois de verificar o estado do pedido e o código do estado HTTP da resposta, compete-lhe a si fazer aquilo que quer fazer com os dados que o servidor lhe enviou. Tem duas opções para aceder a esses dados:

• http_request.responseText – irá devolver a resposta do servidor como uma linha de texto
• http_request.responseXML – irá devolver a resposta do servidor como um objecto XMLDocument que pode percorrer usando as funções DOM de JavaScript.

Passo 3 – Um simples exemplo

Vamos agora pôr tudo junto e efectuar um simples pedido HTTP. O nosso JavaScript vai pedir um documento HTML, teste.html, que contém o texto "Sou um teste." e então vamos alert() os conteúdos do ficheiro teste.html.

<script type="text/javascript" language="javascript">

    var http_request = false;

    function makeRequest(url) {

        http_request = false;

        if (window.XMLHttpRequest) { // Mozilla, Safari,...
            http_request = new XMLHttpRequest();
            if (http_request.overrideMimeType) {
                http_request.overrideMimeType('text/xml');
                // See note below about this line
            }
        } else if (window.ActiveXObject) { // IE
            try {
                http_request = new ActiveXObject("Msxml2.XMLHTTP");
            } catch (e) {
                try {
                    http_request = new ActiveXObject("Microsoft.XMLHTTP");
                } catch (e) {}
            }
        }

        if (!http_request) {
            alert('Giving up :( Cannot create an XMLHTTP instance');
            return false;
        }
        http_request.onreadystatechange = alertContents;
        http_request.open('GET', url, true);
        http_request.send(null);

    }

    function alertContents() {

        if (http_request.readyState == 4) {
            if (http_request.status == 200) {
                alert(http_request.responseText);
            } else {
                alert('There was a problem with the request.');
            }
        }

    }
</script>
<span
    style="cursor: pointer; text-decoration: underline"
    onclick="makeRequest('test.html')">
        Make a request
</span>

Neste exemplo:

• O utilizador clicka no atalho "efectuar pedido" no browser;
• Isto chama a função makeRequest() com um parâmetro -- o nome teste.html de um ficheiro HTML no mesmo directório;
• O pedido é feito e então (onreadystatechange) a execução é passada a alertContents();
• alertContents() verifica se a resposta foi recebida e se é um OK e então alerta (alert()) os conteúdos do ficheiro test.html.

Você pode testar o exemplo aqui e pode ver o ficheiro de teste aqui.

Passo 4 – Trabalhando com a resposta XML

No exemplo anterior, após termos recebido a resposta ao pedido HTTP, nós usamos a propriedade reponseText do objecto de pedido e continha os conteúdos do ficheiro test.html. Agora vamos experimentar a propriedade responseXML.

Antes de tudo, vamos criar um documento XML válido que vamos pedir mais à frente. O documento (test.xml) contém o seguinte:

<?xml version="1.0" ?>
<root>
    I'm a test.
</root>

No guião só precisamos de alterar a linha do pedido com:

...
onclick="makeRequest('test.xml')">
...

Então em alertContents() nós precisamos de substituir a linha de alerta (alert(http_request.responseText);) com:

var xmldoc = http_request.responseXML;
var root_node = xmldoc.getElementsByTagName('root').item(0);
alert(root_node.firstChild.data);

Este código pega o objeto XMLDocument obtido por responseXML e utiliza métodos DOM para acessar alguns dados contidos no documento XML. Você pode ver o test.xml aqui e o script de teste atualizado aqui.

Categorias

Interwiki Language Links

Passo 5 – Tabalhando com os dados

Finalmente, vamos enviar algum dado para o servidor e obter a resposta. Desta vez, nosso JavaScript solicitará um página dinâmica (test.php)  que receberá os dados que enviamos e retornará um string computada - "Hello, [user data]!" - visualizada através de alert().

Primeiro, vamos adicionar uma text box em nosso HTML de modo que o usuário possa digitar o seu nome:

<label>Your name: 
  <input type="text" id="ajaxTextbox" />
</label>
<span id="ajaxButton" style="cursor: pointer; text-decoration: underline">
  Make a request
</span>

Vamos, também, adicionar uma linha para nosso manipulador de eventos obter os dados do usuário da text box e enviá-lo para função makeRequest() juntamente com a URL do nosso script do lado do servidor (server-side):

document.getElementById("ajaxButton").onclick = function() { 
      var userName = document.getElementById("ajaxTextbox").value;
      makeRequest('test.php',userName); 
  };

Precisamos modificar makeRequest () para aceitar os dados do usuário e passá-lo para o servidor. Vamos mudar o método de requisição de GET para POST, e incluir nossos dados como um parâmetro na chamada para httpRequest.send():

function makeRequest(url, userName) {

    ...

    httpRequest.onreadystatechange = alertContents;
    httpRequest.open('POST', url);
    httpRequest.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
    httpRequest.send('userName=' + encodeURIComponent(userName));
  }

A função alertContents() pode ser escrita da mesma forma que se encontrava no Passo 3 para alertar (alert()) nossa string computada,  se isso for tudo o que o servidor retorna. No entanto, vamos dizer que  o servidor irá retornar tanto a sequência computada como o dados original do usuário. Portanto, se o usuário digitou "Jane" na text box, a resposta do servidor ficaria assim:

{"userData":"Jane","computedString":"Hi, Jane!"}

Para utilizar estes dados dentro de alertContents(), nós não podemos simplesmente exibir com alert()  a propriedade responseText. Temos que analisar (parse it)  computedString a propriedade que queremos:

function alertContents() {
    if (httpRequest.readyState === 4) {
      if (httpRequest.status === 200) {
        var response = JSON.parse(httpRequest.responseText);
        alert(response.computedString);
    } else {
      alert('There was a problem with the request.');
    }
}

Para mais métodos DOM, não deixe de conferir a documentação Mozilla's DOM implementation.