Tutorial de jQuery

Tradução de Getting Started with jQuery

Esse tutorial é uma introdução à biblioteca jQuery. É necessário conhecimento básico de Javascript e document object model (DOM). Partiremos bem do começo e explicaremos detalhes quando necessário. Abrangiremos um simples exemplo de olá mundo, seletores e eventos básicos, AJAX, FX, e uso e confecção de plugins.

O tutorial não tem “clique aqui” para ver as funcionalides. A intenção é que você copie o código e tente você mesmo. Copiar, ver o quê faz, e modificar.

  1. Instalação
  2. Olá jQuery
  3. Me ache: Usando seletores e eventos
  4. Me qualifique: Usando Ajax
  5. Me anime: Usando Efeitos
  6. Me ordene: Usando o plugin tablesorter
  7. Me abrace: Escrevendo seus próprios plugins

Instalação

Para começar, precisamos de uma cópia da biblioteca jQuery, disponível no site oficial. O jQuery Starterkit já vem com algum código e CSS para facilitar. Depois de puxar e extrair o arquivo escolhido, colocamos o arquivo jquery.js no mesmo diretório, e basta abrir starterkit.html no e custom.js no seu editor preferido, e starterkit.html com o navegador.

Já temos tudo para começar com o famigerado exemplo “Olá Mundo”.

Olá jQuery

Nós começamos com um esqueleto de página html:


 
 
 
 
 
   <--- adicionaremos nosso conteúdo HTML aqui -->
 
 

Essa página esqueleto apenas carrega a biblioteca jquery.js (tenha certeza que a URL, a parte dentro do atributo src, aponta para sua cópia local do arquivo jquery.js! Nesse exemplo assumimos que ele está no mesmo diretório dessa página exemplo). Os dois comentários indicam onde iremos adicionar novo código.

Como quase tudo feito com jQuery lê ou manipula o document object model (DOM), precisamos ter certeza que adicionaremos eventos (ou outras ações) assim que o DOM estiver pronto.

Para fazer isso, registramos um evento ready no document:

$(document).ready(function() {
   // fazer algo quando o DOM estiver pronto
 });

Colocar apenas um alert() nessa função não faz muito sentido, já que o alert() não requer o carregamento do DOM. Então vamos tentar algo mais sofisticado: Chamar alert() quando um link é clicado.

Adicione o seguinte dentro de <body>:
[html]Link[/html]

Agora modifique a função $(document).ready:

$(document).ready(function() {
   $("a").click(function() {
     alert("Olá Mundo!");
   });
 });

E assim você deve ver o alerta assim que clicar no link.

Vamos ver melhor o quê estamos fazendo: $(“a”) é um seletor jQuery, e nesse caso, ele seleciona todos os elementos a. $ é um apelido para a função jQuery, então $() constrói um novo objeto jQuery. A função click(); chamada em seguida é um método do objeto jQuery. Ele gruda um evento click para todos os elementos selecionados (no caso do nosso exemplo, uma única ligação/link) e executa a função especificada quando o evento ocorre.

Tudo isso é similar ao seguinte código:
[html]Link[/html]

Mas da nossa maneira, não precisamos escrever onclick() para cada elemento. Nós separamos a estrutura (HTML) do comportamento (JS), assim como separamos estrutura e apresentação utilizando CSS.

Isso posto, vamos explorar seletores e eventos mais longe.

Me ache: Usando seletores e eventos

jQuery nos dá duas maneiras de selecionar elementos. A primeira usa uma combinação de CSS e seletores XPath passados como texto para o construtor jQuery (ex: $(“div > ul a”)). A segunda maneira usa diversos métodos do objeto jQuery. E as duas maneiras podem ser misturadas.

Para experimentar com alguns desses seletores, vamos escolher e modificar a primeira lista ordenada do starterkit.

Para começar, queremos selecionar a lista em si. A lista tem o id “orderedlist”. No puro Javascript, você poderia selecioná-la usando document.getElementById(“orderedlist”). Com jQuery, fazemos assim:

$(document).ready(function() {
   $("#orderedlist").addClass("red");
 });

O starterkit vem com uma folha de de estilos (CSS) com uma classe chamada “red” que simplesmente especifica uma cor de fundo vermelha. Logo, quando você recarregar a página no seu navegador, você deverá ver a primeira lista com uma cor de fundo vermelha. E a segunda lista, sem modificações.

Agora vamos adicionar mais algumas classes aos elementos filhos dessa lista:

$(document).ready(function() {
   $("#orderedlist > li").addClass("blue");
 });

O código acima seleciona todos os filhos lis do elemento com o id orderedlist e neles adiciona a classe “blue”.

Agora algo um pouco mais sofisticado. Nós queremos adicionar e remover a classe quando o usuário passar o mouse em cima do elemento li, mas apenas no último elemento da lista.

$(document).ready(function() {
   $("#orderedlist li:last").hover(function() {
     $(this).addClass("green");
   },function(){
     $(this).removeClass("green");
   });
 });

Para cada evento onXYZ, como onclick, onchange, onsubmit, existe um equivalente jQuery. Alguns outros elementos, como ready e hover, são disponibilizados como métodos convenientes para certas tarefas.

Com esses seletores e eventos você já pode fazer um monte de coisas, mas tem mais.

$(document).ready(function() {
   $("#orderedlist").find("li").each(function(i) {
     $(this).append( " BAM! " + i );
   });
 });

O método find() permite procurar em descendentes do elemento já selecionado, portanto $(“#orderedlist”).find(“li”) é similar a $(“#orderedlist li”).

O método each() itera em cada elemento e permite processamento futuro. Muito métodos, como addClass(), usam each() eles mesmos.

No exemplo anterior, append() é usando para concatenar algum texto no elemento.

Outra tarefa comumente encontrada é chamar métodos em elementos DOM que não existem no jQuery. Imagine um formulário que você gostaria de recomeçar após submetê-lo com sucesso via AJAX.

$(document).ready(function() {
   // use isso para recomeçar um único formulário
   $("#reset").click(function() {
     $("form")[0].reset();
   });
 });

O código acima seleciona o primeiro elemento form e chama reset() nele. Caso você tivesse mais de um formulário na página, você também poderia fazer assim:

$(document).ready(function() {
   // use isso para recomeçar vários formulários de uma vez
   $("#reset").click(function() {
     $("form").each(function() {
       this.reset();
     });
   });
 });

O exemplo anterior seleciona todos os formulário no seu document, itera eles e chama reset() para cada um. Note que dentro da função each(), this faz referência ao elemento atual. Também note o seguinte, já que a função reset() pertence ao elemento form e não ao objeto jQuery, não podemos simplesmente chamar $(“form”).reset() para recomeçar todos os formulários da página.

Um desafio comum é selecionar apenas elementos de um grupo de similares ou idênticos. jQuery tem os métodos filter() e not() para isso. Enquanto filter() reduz a seleção de elementos aos encontrados na expressão de filtro utilizada, not() faz o contrário e remove todos os elementos encontrados na expressão. Imagine uma lista não ordenada onde você quer selecionar todos os elementos li que não tenham filhos ul.

$(document).ready(function() {
   $("li").not(":has(ul)").css("border", "1px solid black"); 
 });

Esse código seleciona todos os elementos li, remove os que tenham filhos ul, e aplica uma borda preta neles.

A sintaxe [expression] é derivada do XPath e pode ser usada para filtrar por atributos. Talvez você queira selecionar todos os links que tenham o atributo name:

$(document).ready(function() {
   $("a[@name]").css("background", "#eee" );
 });

Provavelmente mais comum que selecionar links por name, você queira selecionar links pelo atributo “href” deles. Isso pode ser um problema, já que os navegadores inconsistentemente tratam o que é “href” cada um à sua maneira. Para selecionar parte de um valor, podemos usar o seletor contém “*=” ao invés de igual “=”:

$(document).ready(function() {
   $("a[@href*=/content/gallery]").click(function() {
     // faça algo com todos os links que tenham /content/gallery
   });
 });

Até agora, todos os seletores foram usados para escolher filhos ou filtrar a escolha atual. Existem situações onde você precisa escolher os elementos anteriores ou próximos, conhecidos como irmãos. Imagine uma página de FAQ, onde as perguntas estão inicialmente escondidas, mas são mostradas quando a pergunta é clicada. O código jQuery para isso é:

$(document).ready(function() {
   $('#faq').find('dd').hide().end().find('dt').click(function() {
     $(this).next().slideToggle();
   });
 });

Aqui nós usamos cascateamento para reduzir o tamanho do código e melhorar a performance, já que ‘#faq’ é apenas selecionado uma única vez. Ao usar end(), o primeiro find() é desfeito, para procurarmos com o próximo find() no elemento #faq, ao invés dos filhos de dd.

Dentro de click(), usamos $(this).next() para procurar o próximo irmão do atual dt. Isso nos permite rapidamente selecionar a resposta seguinte à questão clicada.

Além de irmãos, você também pode selecionar elementos pais. Talvez você queira destacar o parágrafo pai do link que o usuário está passando o mouse em cima. Tente o seguinte:

$(document).ready(function(){
   $("a").hover(function(){
     $(this).parents("p").addClass("highlight");
   },function(){
     $(this).parents("p").removeClass("highlight");
   });
 });

Vamos voltar um passo antes de continuar: jQuery foca em fazer o código menor e portanto mais fácil de ler e manter. A linha seguinte é um atalho para $(document).ready(callback):

$(function() {
   // code to execute when the DOM is ready
 });

Aplicando ao exemplo Olá Mundo!, temos isso:

$(function() {
   $("a").click(function() {
     alert("Olá Mundo!");
   });
 });

Coberto o básico, exploraremos outros aspectos, começando com AJAX.

Me qualifique: Usando Ajax

Nessa parte escreveremos uma pequena aplicação Ajax, para dar notas a alguma coisa, igual é feito com os vídeos em youtube.com.

Nós não desejamos que esse exemplo funcione sem Ajax, apesar de ser possível, então geraremos o código e texto com jQuery a concatenaremos ele em um div com id “rating”.

$(document).ready(function() {
   // gerar código
   $("#rating").append("Por favor dê nota: ");
   
   for ( var i = 1; i <= 5; i++ )
     $("#rating").append("" + i + " ");
   
   // adicionar código no div e aplicar gerenciadores de cliques nos links
   $("#rating a").click(function(e){
     // prevenir click normal em links
     e.preventDefault();
     
     // enviar requisição
     $.post("exemplo.php", {rating: $(this).html()}, function(xml) {
       // formatar e mostrar resultado
       $("#rating").html(
         "Obrigado pela nota, médio atual: " +
         $("average", xml).text() +
         ", número de votos: " +
         $("count", xml).text()
       );
     });
   });
 });

Esse pedaço de código gera cinco elementos a e concatena eles no elemento com id “rating”. Depois, para cada link no div, um gerenciador de clique é adicionado. Quando o link é clicado, uma requisição post é enviada para exemplo.php com o conteúdo do link como parâmetro. O resultado retornado como XML é adicionado ao div, substituindo os links.

Um problema encontrado com frequência ao carregar conteúdo via Ajax é o seguinte: Ao adicionar gerenciadores de eventos no document que também deveriam ser aplicados no conteúdo, você deve aplicá-los depois do carregamento do conteúdo. Para prevenir duplicação de código, você pode delegar à uma função. Exemplo:

function addClickHandlers() {
   $("a.remote", this).click(function() {
     $("#target").load(this.href, addClickHandlers);
   });
 }
 $(document).ready(addClickHandlers);

Agora addClickHandlers é chamado apenas uma vez quando o DOM estiver pronto e toda vez que o usuário clicar em um link com a classe remote e o conteúdo já terminou de carregar.

Atenção ao $(“a.remote”, this), isso é passado como um contexto: Para o evento ready do document, this refere-se ao documento, e portanto procura no document inteiro por links com a classe remote. Quando addClickHandlers é usado como callback para load(), this refere-se a um elemento diferente: No nosso exemplo, o elemento com id “target”. Isso previne que o evento click seja aplicado diversas vezes aos mesmos links.

Outro problema comum com callbacks são parâmetros. Você especificou seu callback mas precisa passar um parâmetro adicional. A maneira mais fácil de fazer isso é colocar o callback dentro de outra função:

// pegar dados
 var foobar = ...;
 
 // especificar gerenciador, precisa de data como parâmetro
 function handler(data) {
   //...
 }
 
 // adicionar click() e passar foobar
 $('a').click(function(){
   handler(foobar);
 });
 
 // se você precisar do contexto do gerenciador original, use apply():
 $('a').click(function(){
   handler.apply(this, [foobar]);
 });

Agora que vimos um pouco de Ajax, vamos adicionar um pouco de simples efeitos e animações à página.

Me anime: Usando Efeitos

Simples animações com jQuery são realizadas com show() e hide():

$(document).ready(function(){
   $("a").toggle(function(){
     $(".stuff").hide('slow');
   },function(){
     $(".stuff").show('fast');
   });
 });

Você pode criar qualquer combinação de animações com animate(), ex: deslize com opacidade:

$(document).ready(function(){
   $("a").toggle(function(){
     $(".stuff").animate({ height: 'hide', opacity: 'hide' }, 'slow');
   },function(){
     $(".stuff").animate({ height: 'show', opacity: 'show' }, 'slow');
   });
 });

Muitos outros efeitos legais podem ser feitos com a coleção de plugins Interface. Apesar de Interface estar no topo da lista de plugins para jQuery, existem muitos outros. A próxima parte usa o plugin tablesorter.

Me ordene: Usando o plugin tablesorter

O plugin tablesorter permite ordenar tabelas direto no navegador. Você inclui a biblioteca jQuery e o arquivo do plugin, bastando falar quais tabelas você quer ordenar.

Para esse exemplo funcionar você precisa puxar o plugin tablesorter e adicionar a seguinte linha em starterkit.html (abaixo da qual inclui o jquery):

Depois de incluir o plugin, você pode chamá-lo assim:

$(document).ready(function(){
   $("#large").tablesorter();
 });

Tente clicar nos cabeçalhos da tabela do arquivo de exemplo e veja como ela é ordenada de maneira ascendente no primeiro clique e descendente na segunda.

A tabela pode ter as linhas destacadas, e podemos fazer isso passando algumas opções:

$(document).ready(function() {
   $("#large").tablesorter({
     // visual listras
     widgets: ['zebra']	
   });
 });

A maioria dos plugins pode ser usada assim. Inclua o arquivo do plugin e chama seus métodos em alguns elementos, passando configurações adicionais para customização.

Uma lista atualizada de plugins pode ser encontrado no site jQuery Plugin.

Quando você estiver usando jQuery com frequência, você pode achar útil empacotar seu código como um plugin, ou para reusá-lo você mesmo ou na sua empresa, ou para compartilhá-lo com a comunidade. O próximo capítulo dá algumas dicas sobre como estruturar um plugin.

Me abrace: Escrevendo seus próprios plugins

Escrever seu próprio plugin para jQuery é bem fácil. E atendo-se às seguintes regras, facilitará para outras pessoas integrarem o seu plugin.

Nome do plugin

Ache um nome para ele, chamaremos o nosso de “foobar”. Crie um arquivo chamado jquery.nomedoplugin.js, ex: jquery.foobar.js

Adicione métodos próprios

Crie um ou mais métodos do plugins extendendo o objeto jQuery, ex:

jQuery.fn.foobar = function() {
   // fazer algo
 };

Que estará disponível executando:

$(...).foobar();

Confirguração padrão

Crie configurações padrões que podem ser modificadas pelo usuários, ex:

jQuery.fn.foobar = function(options) {
   var settings = jQuery.extend({
     value: 5, name: "pete", bar: 655
   }, options);
 };

Você pode chamar o plugin sem opções, usando as padrões:

$("...").foobar();

Ou com algumas opções:

$("...").foobar({ value: 123, bar: 9 });

Documentação

Se você disponibilizar seu plugin, você pode dar alguns exemplos e documentação. Existem vários plugins disponíveis que você pode usar como referência.

O conhecimento básico para escrever plugins é esse. Vamos escrever um nosso.

Plugin checkbox

Muita gente, ao manipular formulários com jQuery, pergunta como marcar e desmarcar botões radio ou checkboxes. O código sai assim:

$("input[@type='checkbox']").each(function() {
   this.checked = true;
   this.checked = false; // ou, para desmarcar
   this.checked = !this.checked; // ou, para inverter
 });

Como plugin, é bem direto:

jQuery.fn.check = function() {
   return this.each(function() {
     this.checked = true;
   });
 };

E agora ele pode ser usado:

$("input[@type='checkbox']").check();

Você também poderia escrever plugins para uncheck() e inverterCheck(). Mas ao invés disso vamos extender nosso plugins para aceitar algumas opções.

jQuery.fn.check = function(mode) {
   // se mode não está definido, usaremos 'on' como padrão
   var mode = mode || 'on';
   
   return this.each(function() {
     switch(mode) {
       case 'on':
         this.checked = true;
         break;
       case 'off':
         this.checked = false;
         break;
       case 'toggle':
         this.checked = !this.checked;
         break;
     }
   });
 };

Permitindo um padrão para a opção, o usuário pode omitir a opção ou passar outra: “on”, “off” e “toggle”, ex.:

$("input[@type='checkbox']").check();
 $("input[@type='checkbox']").check('on');
 $("input[@type='checkbox']").check('off');
 $("input[@type='checkbox']").check('toggle');

Configurações opcionais

Com mais de uma opção opcional, dessa maneira fica complicado, pois o usuário precisaria passar valores nulos nos quais ele deseja omitir.

O uso de tablesorter anteriormente demonstra a aplicação de um objeto para resolver esse problema. O usuário pode omitir todos os parâmetros ou passar um objeto com chave/valor para cada configuração a ser sobrescrita.

Como exercício, você pode tentar reescrever o código de Nota anterior como plugin. O esqueleto do código seria parecido com:

jQuery.fn.rateMe = function(options) {
   // ao invés de selecionar um container fixo com 
   // $("#rating"), usaremos o contexto jQuery
   var container = this;
   
   var settings = jQuery.extend({
     url: "exemplo.php"
     // mais padrões iriam aqui
   }, options);
   
   // ... resto do código ...
   
   // se possível, retorne "this" para não quebrar o cascateamento
   return this;
 });

Permitindo você executar o plugin da seguinte maneira:

$(...).rateMe({ url: "test.php" });

Posted

in

by

Comments

One response to “Tutorial de jQuery”

  1. Anderson Avatar
    Anderson

    Olá, achei mt interessante seu tutórial e tenho uma dúvida…

    Eu tenho um e nesse select tenho q chamar uma mesma função tanto nos eventos onclick e onchage, atualmente ela está assim:

    $(“#profissao”).change(function(){
    $.post(‘buscaEspecialidade.php’, { especialidade : $(this).val() }, function(resposta){
    if ( !resposta == “” ){
    $(“#especialidade”).show();
    $(“#conteudo”).html(resposta);
    } else {
    $(“#especialidade”).hide();
    $(“#conteudo”).html(“”);
    }
    });
    })

    mas preciso associar a mesma função ao evento click, dá para usar a mesma função referenciando os 2 eventos CHANGE e CLICK???

    Aguardo sua resposta!!!

    Valeuuu

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.