diff options
Diffstat (limited to 'files/pt-pt/web/guide/ajax/getting_started/index.html')
| -rw-r--r-- | files/pt-pt/web/guide/ajax/getting_started/index.html | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/files/pt-pt/web/guide/ajax/getting_started/index.html b/files/pt-pt/web/guide/ajax/getting_started/index.html new file mode 100644 index 0000000000..f57095e504 --- /dev/null +++ b/files/pt-pt/web/guide/ajax/getting_started/index.html @@ -0,0 +1,306 @@ +--- +title: Primeiros Passos +slug: Web/Guide/AJAX/Getting_Started +tags: + - AJAX + - API + - Avançado + - JavaScript + - Mecânica da Web + - XMLHttpRequest +translation_of: Web/Guide/AJAX/Getting_Started +original_slug: Web/Guide/AJAX/Como_começar +--- +<p class="summary">Este artigo guia-o através do essencial do AJAX e oferece-lhe dois exemplos práticos simples para poder começar.</p> + +<h3 id="O_que_é_AJAX">O que é AJAX?</h3> + +<p>AJAX (JavaScript Assíncrono e XML) em poucas palavras, é a utilização do objeto <code><a href="/pt-PT/docs/Web/API/XMLHttpRequest">XMLHttpRequest</a></code> para comunicar com os servidores. Este pode enviar e receber informação em vários formatos, incluindo JSON, XML, HTML e ficheiros de texto. A característica mais atraente do AJAX é a sua natureza 'assíncrona', o que significa que este pode comunicar com o servidor, trocar dados, e atualizar a página sem ter que recarregar a página.</p> + +<p>As duas principais funcionalidades do AJAX são as seguintes:</p> + +<ul> + <li>Efetuar pedidos ao servidor sem ter de recarregar a página</li> + <li>Receber e trabalhar com dados a partir do servidor</li> +</ul> + +<h3 id="Passo_1_-_Como_efetuar_um_pedido_de_HTTP">Passo 1 - Como efetuar um pedido de HTTP</h3> + +<p>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 <code>XMLHTTP</code>. Depois, o Mozilla, o Safari e outros browsers fizeram o mesmo, implementando uma classe de nome <code>XMLHttpRequest</code> que suporta os métodos e as propriedades do objecto ActiveX original da Microsoft.</p> + +<p>Por isso, para criar uma instância (objeto) da classe pretendida compatível com multiplos navegadores, você pode fazer:</p> + +<pre>if (window.XMLHttpRequest) { // Mozilla, Safari, ... + http_request = new XMLHttpRequest(); +} else if (window.ActiveXObject) { // IE + http_request = new ActiveXObject("Microsoft.XMLHTTP"); +} + +</pre> + +<p>(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.)</p> + +<p>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 <code>text/xml</code>.</p> + +<pre>http_request = new XMLHttpRequest(); +http_request.overrideMimeType('text/xml'); +</pre> + +<p>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 <code>onreadystatechange</code> do objeto ao nome da função JavaScript que pretende utilizar, por exemplo:</p> + +<p><code>http_request.onreadystatechange = NomedaFunção;</code></p> + +<p>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:</p> + +<pre>http_request.onreadystatechange = function(){ + // processar resposta do servidor +}; +</pre> + +<p>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 <code>open()</code> e <code>send()</code> da classe pedido HTTP, por exemplo:</p> + +<pre>http_request.open('GET', 'http://www.dominio.com.br/arquivo.extensao', true); +http_request.send(null); +</pre> + +<ul> + <li>O primeiro parâmetro da chamada do método <code>open()</code> é 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 <a class="external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html">W3C specs</a></li> + <li>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 <code>open()</code>. 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.</li> + <li>O terceiro parâmetro define se o pedido é assíncrono. Se <code>TRUE</code>, 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.</li> +</ul> + +<p>O parâmetro do método <code>send()</code> 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:</p> + +<p><code>name=value&anothername=othervalue&so=on</code></p> + +<p>ou em vários outros formatos, incluindo JSON, SOAP, etc.</p> + +<p>Note-se que se pretende enviar (POST) dados, você deve alterar o tipo MIME do pedido usando a seguinte linha:</p> + +<pre>http_request.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded'); +</pre> + +<p>De outra forma o servidor irá ignorar os dados (post).</p> + +<p>Pode-se também colocar o charset desejado assim:</p> + +<pre>http_request.setRequestHeader('Content-Type', + "application/x-www-form-urlencoded; charset=iso-8859-1"); +</pre> + +<p>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:</p> + +<pre> 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"); +</pre> + +<h3 id="Passo_2_-_Manipular_a_resposta_do_servidor">Passo 2 - Manipular a resposta do servidor</h3> + +<p>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.</p> + +<p><code>http_request.onreadystatechange = nameOfTheFunction;</code></p> + +<p>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.</p> + +<pre>if (http_request.readyState == 4) { + // everything is good, the response is received +} else { + // still not ready +} +</pre> + +<p>A lista completa dos valores <code>readyState</code> é a seguinte:</p> + +<ul> + <li>0 (não inicializado)</li> + <li>1 (a carregar)</li> + <li>2 (carregado)</li> + <li>3 (interativo)</li> + <li>4 (completo)</li> +</ul> + +<p>(<a class="external" href="http://msdn.microsoft.com/workshop/author/dhtml/reference/properties/readystate_1.asp">Source</a>)</p> + +<p>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 <a class="external" href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">página W3C</a>. Para os nossos objectivos nós só estamos interessados na resposta <code>200 OK</code>.</p> + +<pre>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 +} +</pre> + +<p>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:</p> + +<ul> + <li><code>http_request.responseText</code> – irá devolver a resposta do servidor como uma linha de texto</li> + <li><code>http_request.responseXML</code> – irá devolver a resposta do servidor como um objecto <code>XMLDocument</code> que pode percorrer usando as funções DOM de JavaScript.</li> +</ul> + +<p> </p> + +<h3 id="Passo_3_–_Um_exemplo_simples">Passo 3 – Um exemplo simples</h3> + +<p>Vamos agora pôr tudo junto e efectuar um simples pedido HTTP. O nosso JavaScript vai pedir um documento HTML, <code>teste.html</code>, que contém o texto "Sou um teste." e então vamos <code>alert()</code> os conteúdos do ficheiro <code>teste.html</code>.</p> + +<pre><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> +</pre> + +<p>Neste exemplo:</p> + +<ul> + <li>O utilizador clicka no atalho "efectuar pedido" no browser;</li> + <li>Isto chama a função <code>makeRequest()</code> com um parâmetro -- o nome <code>teste.html</code> de um ficheiro HTML no mesmo directório;</li> + <li>O pedido é feito e então (<code>onreadystatechange</code>) a execução é passada a <code>alertContents()</code>;</li> + <li><code>alertContents()</code> verifica se a resposta foi recebida e se é um OK e então alerta (<code>alert()</code>) os conteúdos do ficheiro <code>test.html</code>.</li> +</ul> + +<p>Você pode testar o exemplo <a class="external" href="http://www.w3clubs.com/mozdev/httprequest_test.html">aqui</a> e pode ver o ficheiro de teste <a class="external" href="http://www.w3clubs.com/mozdev/test.html">aqui</a>.</p> + +<div class="note"><strong>Nota</strong>: <span id="result_box" lang="pt"><span class="hps"><span id="result_box" lang="pt"><span class="alt-edited hps">Se você está enviando</span> <span class="alt-edited hps">uma solicitação para um</span> <span class="hps">pedaço de código</span> <span class="alt-edited hps">que retornará</span> <span class="hps">XML</span><span>, ao invés de</span> <span class="hps">um arquivo</span> <span class="hps">XML</span> <span class="hps">estático</span><span>, é necessário definir</span> <span class="hps">alguns</span> <span class="hps">cabeçalhos de resposta</span> <span class="hps">se a sua página</span> <span class="alt-edited hps">deve trabalhar</span> <span class="alt-edited hps">com o Internet Explorer</span><span>, além de</span> <span class="hps">Mozilla.</span> <span class="hps">Se</span> <span class="hps">você não definir</span> <span class="hps">cabeçalho</span> <code><span class="hps">Content-Type</span><span>: application /</span> <span class="hps">xml</span></code><span>, o IE irá</span> <span class="hps">lançar um erro</span> <span class="hps">JavaScript,</span> <span class="atn hps">"</span><span>Objeto esperado</span><span>"</span><span>,</span> <span class="hps">após a linha</span> <span class="hps">onde você tentar</span> <span class="hps">acessar um elemento</span> <span class="hps">XML.</span></span>.</span></span></div> + +<div class="note"><strong>Nota 2</strong>: <span id="result_box" lang="pt"><span class="hps">Se</span> <span class="hps">você não definir</span> <span class="hps">cabeçalho</span> <code><span class="atn hps">Cache-</span><span>Control: no</span><span>-cache</span></code> <span class="alt-edited hps">o navegador</span> <span class="alt-edited hps">armazenará em cache</span> <span class="hps">a resposta</span> <span class="alt-edited hps">e jamais</span> <span class="alt-edited hps">voltará a submeter</span> <span class="hps">o pedido</span><span>, tornando</span> <span class="hps">a depuração</span> <span class="atn hps">"</span><span class="alt-edited">desafiadora".</span> <span class="alt-edited hps">Também é</span> <span class="alt-edited hps">possível acrescentar</span> <span class="hps">um parâmetro</span> <span class="hps">GET</span> <span class="hps">adicional</span> <span class="hps">sempre</span> <span class="hps">diferente,</span> <span class="hps">como o</span> <span class="hps">timestamp</span> <span class="hps">ou</span> <span class="hps">um número aleatório</span> <span class="atn hps">(</span><span>veja</span> <a href="https://developer.mozilla.org/en/DOM/XMLHttpRequest/Using_XMLHttpRequest#Bypassing_the_cache" title="https://developer.mozilla.org/En/XMLHttpRequest/Using_XMLHttpRequest#Bypassing_the_cache">bypassing the cache</a><span class="hps">).</span></span></div> + +<div class="note"><strong>Nota 3</strong>: <span id="result_box" lang="pt"><span class="hps">Se a variável</span> <span class="hps">httpRequest</span> <span class="alt-edited hps">é utilizada</span> <span class="hps">globalmente</span><span class="alt-edited">, funções</span> <span class="alt-edited hps">concorrentes</span> <span class="hps">chamando</span> <code><span class="hps">makeRequest</span> </code><span class="alt-edited hps"><code>()</code> podem</span> <span class="alt-edited hps">sobrescrever</span> <span class="hps">o outro,</span> <span class="hps">causando</span> <span class="hps">uma condição de corrida</span><span>.</span> <span class="hps">Declarando</span> <span class="hps">o</span> <span class="hps">httpRequest</span> <span class="hps">variável local para</span> <span class="hps">um <a href="https://developer.mozilla.org/en/JavaScript/Guide/Closures" title="https://developer.mozilla.org/en/JavaScript/Guide/Closures">closure</a></span> <span class="hps">contendo as funções</span> <span class="hps">AJAX</span> <span class="hps">impede</span> <span class="hps">a condição de corrida</span><span>.</span></span></div> + +<div class="note"><strong>Nota 4</strong>: Caso ocorra um erro de comunicação (tal como a queda de do servidor web), uma exceção será lançada no método <code>onreadystatechange</code> quando o campo <code>status</code> for acessado. Tenha a certeza de envolver sua declaração <code>if..then</code> dentro de um bloco <code>try...catch</code>. (Veja: {{ Bug(238559) }}).</div> + +<h3 id="Passo_4_–_Trabalhar_com_a_resposta_XML">Passo 4 – Trabalhar com a resposta XML</h3> + +<p>No exemplo anterior, após termos recebido a resposta ao pedido HTTP, nós usamos a propriedade <code>reponseText</code> do objecto de pedido e continha os conteúdos do ficheiro <code>test.html</code>. Agora vamos experimentar a propriedade <code>responseXML</code>.</p> + +<p>Antes de tudo, vamos criar um documento XML válido que vamos pedir mais à frente. O documento (test.xml) contém o seguinte:</p> + +<p> </p> + +<pre><?xml version="1.0" ?> +<root> + I'm a test. +</root> +</pre> + +<p>No guião só precisamos de alterar a linha do pedido com:</p> + +<pre>... +onclick="makeRequest('test.xml')"> +... +</pre> + +<p>Então em <code>alertContents()</code> nós precisamos de substituir a linha de alerta (<code>alert(http_request.responseText);</code>) com:</p> + +<pre>var xmldoc = http_request.responseXML; +var root_node = xmldoc.getElementsByTagName('root').item(0); +alert(root_node.firstChild.data); +</pre> + +<p>Este código pega o objeto <code>XMLDocument</code> obtido por <code>responseXML</code> e utiliza métodos DOM para acessar alguns dados contidos no documento XML. Você pode ver o <code>test.xml</code> <a class="external" href="http://www.w3clubs.com/mozdev/test.xml">aqui</a> e o script de teste atualizado <a class="external" href="http://www.w3clubs.com/mozdev/httprequest_test_xml.html">aqui</a>.</p> + +<p><span class="comment">Categorias</span></p> + +<p><span class="comment">Interwiki Language Links</span></p> + +<h3 id="Passo_5_–_Tabalhar_com_dados">Passo 5 – Tabalhar com dados</h3> + +<p>Finalmente, vamos enviar algum dado para o servidor e obter a resposta. Desta vez, nosso JavaScript solicitará um página dinâmica (<code>test.php</code>) que receberá os dados que enviamos e retornará um string computada - "<code>Hello, [user data]!</code>" - visualizada através de <code>alert().</code></p> + +<p>Primeiro, vamos adicionar uma text box em nosso HTML de modo que o usuário possa digitar o seu nome:</p> + +<pre class="brush: html"><label>Your name: + <input type="text" id="ajaxTextbox" /> +</label> +<span id="ajaxButton" style="cursor: pointer; text-decoration: underline"> + Make a request +</span></pre> + +<p>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 <code>makeRequest()</code> juntamente com a URL do nosso script do lado do servidor (server-side):</p> + +<pre class="brush: js">document.getElementById("ajaxButton").onclick = function() { + var userName = document.getElementById("ajaxTextbox").value; + makeRequest('test.php',userName); + };</pre> + +<p><span id="result_box" lang="pt"><span class="hps">Precisamos</span> <span class="hps">modificar</span> <code><span class="hps">makeRequest</span> </code><span class="hps"><code>()</code> para aceitar</span> <span class="hps">os dados do usuário</span> <span class="hps">e</span> <span class="hps">passá-lo para</span> <span class="hps">o servidor</span></span>. Vamos mudar o método de requisição de <code>GET</code> para <code>POST</code>, e incluir nossos dados como um parâmetro na chamada para <code>httpRequest.send()</code>:</p> + +<pre class="brush: js">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)); + } +</pre> + +<p>A função <code>alertContents()</code> pode ser escrita da mesma forma que se encontrava no <strong>Passo 3</strong> para alertar (<code>alert()</code>) 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:</p> + +<p><code>{"userData":"Jane","computedString":"Hi, Jane!"}</code></p> + +<p><span class="short_text" id="result_box" lang="pt"><span class="hps">Para utilizar</span> <span class="hps">estes dados</span> <span class="hps">dentro de </span></span><code>alertContents()</code>, nós não podemos simplesmente exibir com <code>alert()</code> a propriedade <code>responseText</code>. Temos que analisar (parse it) <code>computedString</code> a propriedade que queremos:</p> + +<pre class="brush: js">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.'); + } +}</pre> + +<p><code>Para mais métodos DOM, certifique-se que consulta os documentos sobre a <a class="external" href="/pt-PT/docs/DOM/DOM_Reference">implementação de DOM da Mozilla</a></code></p> |