Esta função carrega uma página remota usando uma requisição HTTP. Trata-se de uma implementação AJAX em nível inferior que oferece um vasto conjunto de funcionalidades não disponíveis em funções mais fáceis de entender e usar, chamadas de alto nível, tais como as funções $.get() e $.post(). Esta função admite um argumento que é um objeto constituído de um conjunto de pares chave/valor (ou nome/valor) a ser usado para iniciar e manipular a requisição. O conjunto chave/valor e seus significados são mostrados a seguir. Não se preocupe se os conceitos a seguir soarem estranhos e confusos para você. Faça uma leitura atenta para se familiarizar com os nomes e finalidade de cada chave/valor. Mais adiante você estudará as funções de alto nível, mais fáceis de entender e usar como foi dito anteriormente. E então poderá reler e entender os conceitos a seguir.
Chave | Valor e Descrição |
---|---|
async | O valor default é true. Por definição, requisições AJAX são assíncronas e esta chave configurada para false torna a requisição síncrona. É quase certeza que você não encontrará uma razão para fazer uma requisição AJAX síncrona. |
beforeSend | O valor é uma função para modificar o objeto XMLHttpRequest antes do seu envio. É usada, por exemplo, para enviar cabeçalhos HTTP personalizados. A função admite como argumento único o objeto XMLHttpRequest. |
cache | O valor default é true e evita que a página requisitada vá para o cache do navegador. Para requisições JSONP ou com uso do elemento script esta chave deve ser configurada para false. |
complete | O valor é uma função chamada quando a requisição termina. A função admite dois argumentos: o objeto XMLHttpRequest e uma string definindo o status de como terminou a requisição. |
contentType | O valor é uma string descrevendo o tipo de conteúdo que está sendo enviado para o servidor. O valor default é application/x-www-form-urlencoded. |
data | O valor desta chave são os dados a serem enviados ao servidor. Os dados são automaticamente convertidos em uma query string e apensos à URL quando se trata de requisição pelo método GET. Caso não se deseje a transformação automática dos dados em uma query string podemos usar a chave processData conforme mostrada adiante. Se o valor dos dados for um array jQuery serializa os valores do array em uma mesma chave. Por exemplo: {dados:["v1", "v2"]} transforma-se em: '&dados=v1&dados=v2'. |
dataFilter | O valor é uma função usada para tratar os dados brutos retornados pelo objeto XMLHttpRequest. A função admite dois argumentos os dados e o tipo de dados retornado pelo servidor. |
dataType | O valor é o tipo dos dados que é esperado como retorno pelo servidor. Os tipos de dados disponíveis são: xml, html, script, json, jsonp,text |
error | O valor é uma função a ser chamada quando ocorre uma falha na requisição. A função admite três argumentos: o objeto XMLHttpRequest, uma string descrevendo o tipo de erro cujos valores possíveis são: "null", "timedout", error, "notmodified" e "parsererror". O último argumento é um objeto opcional, caso ocorra. Exemplo: function (XMLHttpRequest, textStatus, errorThrown) {...} . Convém notar que o tratamento de erros em requisições AJAX com jQuery somente está disponível nesta função, isto é, funções callback para tratar erros não são possíveis nas implementações de alto nível, tais como, $.get() e $.post(). global O valor default é true e habilita o uso de funções globais durante a requisição. Configurada para false esta chave evita, por exemplo, que as globais ajaxStart e ajaxStop tenham efeito. ifModified Destina-se a completar a requisição somente no caso de a resposta ter sido modificada desde a última requisição. A verificação é feita com a inspeção do cabeçalho HTTP Last-Modified. O valor default é false não fazendo a verificação do cabeçalho. jsonp Sobrescreve a função callback em uma requisição JSON. password O valor é uma senha para possibilitar acesso a um recurso que exija autenticação. processData O valor default é true o que faz com que os dados sejam processados e passados como uma query string do tipo application/x-www-form-urlencoded. Havendo necessidade de passar dados não processados configure esta chave para false. |
scriptCharset | Usado somente para requisições de dados do tipo jsonp ou script com método HTTP GET, nos casos em que haja diferenças entre o conjunto de caracteres remoto e o do conteúdo local. success O valor é uma função a ser executada quando a requisição se completa com sucesso. A função admite dois argumentos: os dados retornados, formatados de acordo com o parâmetro dataType e uma string descrevendo o status. |
timeout | O valor deve ser definido em milisegundos e se destina a estabelecer um tempo mínimo de espera para a requisição a partir do qual ela deverá ser abortada. |
type | O valor default é GET e define o tipo de requisição. Normalmente as requisições são do tipo GET ou POST, contudo outros tipos como PUT e DELETE são também possíveis, embora tais tipos possam apresentar problemas por não serem suportados por determinados navegadores. |
url | O valor é a URL para a qual a requisição é feita. |
username | O valor é uma nome de usuário para possibilitar acesso a um recurso que exija autenticação. xhr Sobrescreve a funcionalidade nativa de criação do objeto AJAX. Usado para personalizar ou incrementar a criação do objeto XMLHttpRequest. |
Notas gerais | Conforme vimos, uma das chaves para requisições AJAX é a dataType ou tipo dos dados que estão transitando em uma requisição. É importante que o servidor retorne o MIME type correto quando devolve uma resposta ao cliente. Desta forma, certifique-se de definir corretamente a dataType em suas requisições, caso contrário não será possível manipular os dados retornados ou até mesmo a requisição ser completamente ignorada, e, pior ainda, você não ser alertado do que está acontecendo com sua requisição não completada e ficar completamente perdido. Requisições $.ajax() para arquivos JSON transformam responseText em um objeto que é passado como primeiro argumento para uma função callback de sucesso na requisição. Você pode então manipular a resposta diretamente como um objeto JavaScript. Ao carregar arquivos XML locais, tais como a partir de um CD-ROM lembre-se que o navegador Internet Explorer trata XML como dados do tipo txt e não txt/xml. |
Esta função destina-se especificamente a uma requisição HTTP com uso do método GET. Trata-se de uma maneira simplificada de requisição type: GET sem a complexidade das requisições com uso da função $.ajax(). Admite apenas uma função callback a ser executada ao término da requisição e somente se esta for bem sucedida. Se você pretende definir funções para detecção de erros ou funções para serem executadas antes da requisição ter sido completada deverá usar $.ajax(), pois $.get() não admite callback para erros ou success.
É consagrada pelo uso a convenção de se envolver por sinal de chaves os parâmetros facultativos de uma função. Na notação desta função os parâmetros [data], [callback] e [tipo] são facultativos e o parâmetro url é obrigatório.
Parâmetro | Descrição |
---|---|
url | O URL do arquivo requisitado. |
data | Dados no formato de um conjunto chave/valor a ser enviado ao servidor. |
callback | Função a ser executada após o carregamento do arquivo requisitado. |
tipo | Tipo de dado transitando na requisição. Valores possíveis: "xml", "html", "script", "json", "jsonp", ou "text". |
Para entender o funcionamento de uma requisição AJAX com uso da função $.get() vamos desenvolver um simples exemplo prático que está disponível no site do livro.
A proposta para construção do nosso exemplo demonstrativo é a de solicitar ao usuário um nome e o nome de uma cidade para serem enviados ao servidor e processados por um programa PHP que retornará uma reposta ao usuário. Usarei a linguagem PHP nos exemplos deste livro, por ser aquela com a qual me sinto mais confortável. Use a linguagem de sua preferência.
Por se tratar de uma demonstração do funcionamento de uma requisição não estamos preocupados com a utilidade e a funcionalidade da requisição que iremos desenvolver. Nossa requisição vai enviar dados ao servidor e o programa PHP vai recebê-los e retorná-los ao usuário. Isto não tem valor prático algum, porém vai mostrar como enviar, como processar, como retornar e como apresentar os dados retornados. Conhecendo como funcionam estas quatro ações ficaremos em condições de desenvolver requisições mais elaboradas e práticas, como veremos nos próximos capítulos.
Em uma primeira etapa do desenvolvimento do exemplo iremos enviar os dados; nome: "Maujor", cidade: "Rio de Janeiro" diretamente no script da requisição sem a interferência do usuário. A seguir faremos nossa requisição mais flexível acrescentando dois campos de texto na página, que faz a requisição, para que o usuário entre com os dados. O arquivo PHP requisitado, que contém o programa que irá tratar os dados enviados, foi denominado exemplo-get.php e é mostrado a seguir.
PHP: 1. Este é o conteúdo requisitado para demonstrar a função \$.get( )</h2>\n"; 6. $html.= "<p>Os dados enviados foram:</p>\n"; 7. $html.= "<ul>\n"; 8. $html.= "<li>Nome: <span class=\"destaque\">$nome</span></li>\n"; 9. $html.= "<li>Cidade: <span class=\"destaque\">$cidade</span>$</li>\n"; 10. $html.= "</ul>"; 11. echo $html; 12. } else { 13. echo "<script type='text/javascript'>alert('Por favor preencha os dois campos')</script>"; 14. } 15. ?>
Se você conhece PHP fique à vontade para pular os comentários sobre estes códigos que farei ao longo de todo o livro. A finalidade destes comentários não é ensinar PHP, mas esclarecer a lógica do programa para que os leitores que usam outras linguagens de programação possam desenvolver códigos equivalentes.
Linha(s) | Descrição |
---|---|
linha 2 | Qualquer que seja a natureza dos dados entrados pelo usuário é indispensável que se faça a validação. O grau de sofisticação da validação dos dados entrados é função de cada caso. Nesta linha verificamos, simplesmente, se o usuário forneceu um nome e uma cidade e se o valor fornecido é ou não vazio. |
linhas 3 e 4 | Outra técnica indispensável em entrada de dados pelo usuário aqui, por questões de segurança, extirpamos qualquer tentativa de entrada de tags HTML. |
linha 5 a 10 | Criamos a variável $html para armazenar a marcação HTML com o conteúdo da requisição. |
linha 5 | Um cabeçalho h2 com respectivo texto. |
linha 6 | Um parágrafo explicativo. |
linha 7 | Inicia uma lista não ordenada. |
linha 8 | Coloca no primeiro item da lista o nome fornecido pelo usuário. |
linha 9 | Coloca no segundo item da lista a cidade fornecida pelo usuário. |
linha 10 | Termina a lista não ordenada. |
linha 11 | Escreve a marcação HTML criada anteriomente. Atenção: esta marcação HTML é retornada como resultado caso a requisição tenha sido bem sucedida. |
linha 12 | Se a condição de verificação dos dados não for satisfeita o programa pula para a linha seguinte. |
linha 13 | Escreve a marcação HTML contendo uma mensagem ao usuário informando que houve erro no preenchimento dos dados. |
Notar que usamos uma caixa de alerta JavaScript para passar a mensagem de erro. Atenção: esta marcação HTML é retornada como resultado caso a requisição tenha falhado.
Na figura 2.1 mostramos a renderização da marcação HTML gerada pelo programa PHP contido no arquivo exemplo-get.php. Na tela superior a simulação do resultado da requisição bem sucedida (notar, em destaque na barra de endereços do navegador que passamos os dois parâmetros da requisição nome e cidade) e na tela inferior o resultado da requisição falha (notar, em destaque na barra de endereços do navegador, que não passamos parâmetros).
Esta função destina-se especificamente a uma requisição HTTP com uso do método POST. Trata-se de uma maneira simplificada de requisição type: POST sem a complexidade das requisições com uso da função $.ajax().
Admite apenas uma função callback a ser executada ao término da requisição e somente se esta for bem sucedida. Se você pretende definir funções para detecção de erros ou funções para serem executadas antes da requisição ter sido completada deverá usar $.ajax(), pois $.post() não admite callback para erros ou success.
Parâmetro | Descrição |
---|---|
url | O URL do arquivo requisitado. |
data | Dados no formato de um conjunto chave/valor a ser enviado ao servidor. |
callback | Função a ser executada após o carregamento do arquivo requisitado. |
tipo | Tipo de dado transitando na requisição. Valores possíveis: "xml", "html", "script", "json", "jsonp", ou "text". |
Exemplo: 1. $.post(exemplo-post.php, { 2. nome: "Maujor", email: "maujor@maujor.com", comentário: "Texto..."}, 3. function(data) { 4. // manipular os dados retornados 5. }, 6. "html")
Linha(s) | Descrição |
---|---|
linha 1 | Requisita o arquivo denominado exemplo-post.php. |
linha 2 | Envia os dados nome, email e comentario com os valores "Maujor", "maujor@maujor.com" e "Texto do comentário", para o servidor. |
linha 3 | Cria uma função callback para apresentar os dados da requisição. |
linha 6 | Tipo de dado transitando na requisição. |
Para entender o funcionamento de uma requisição AJAX com uso da função $.post() vamos desenvolver um simples exemplo prático que está disponível no site do livro no arquivo [arquivo-2.1c.php].
O exemplo que escolhemos para demonstrar este tipo de requisição é uma funcionalidade presente na maioria dos sites. Trata-se de um formulário para envio de uma mensagem ao administrador do site. No formulário proposto o usuário preenche os campos para enviar seu nome, e-mail e mensagem, sendo todos eles de preenchimento obrigatório. Reduzimos ao mínimo a quantidade de campos no formulário, para não alongar desnecessariamente a quantidade de código a ser mostrado.
Os conceitos estudados para os três campos são suficientes para o perfeito entendimento do funcionamento dos scripts e você poderá facilmente estender as técnicas estudas para um formulário com maior quantidade de campos e mais complexo. No desenvolvimento deste exemplo vamos considerar a metodologia HIJAX partindo de um formulário funcional cujos dados serão processados por um programa PHP. Uma vez que não é do escopo deste livro estudar o desenvolvimento de um programa PHP (ou outra linguagem qualquer) para enviar dados de um formulário iremos preparar a estrutura HTML do formulário e a programação para receber os códigos de envio dos dados, mas não detalharemos tais códigos. Ou seja, omitiremos no script PHP o redirecionamento para mensagens de erro, o direcionamento para uma página de sucesso, as função de envio do email ao administrador e todos os scripts que não dizem respeito direto ao AJAX, em fim, aqueles que fazem a página funcionar sem AJAX.
Na figura 2.5 mostramos o resultado do envio bem sucedido dos dados e a respectiva mensagem retornada para o usuário, via AJAX.