jQuery Cookbook

Comunidade de Desenvolvedores jQuery

Novatec

Authorized Portuguese translation of the English edition of titled jQuery Cookbook ISBN 9780596159771 2009, Cody Lindley. This translation is published and sold by permission of O'Reilly Media, Inc., the owner of all rights to publish and sell the same. Traduo em portugus autorizada da edio em ingls da obra jQuery Cookbook ISBN 9780596159771 2009, Cody Lindley. Esta traduo publicada e vendida com a permisso da O'Reilly Media, Inc., detentora de todos os direitos para publicao e venda desta obra. Novatec Editora Ltda. 2011. Todos os direitos reservados e protegidos pela Lei 9.610 de 19/02/1998. proibida a reproduo desta obra, mesmo parcial, por qualquer processo, sem prvia autorizao, por escrito, do autor e da Editora. Editor: Rubens Prates Traduo: Gustavo Cssio de Moraes e Rafael Zanolli Reviso tcnica: Thiago Galesi Reviso gramatical: Dbora Facin Editorao eletrnica: Camila Kuwabata e Carolina Kuwabata ISBN: 978-85-7522-227-0 Histrico de impresses: Dezembro/2010 Primeira edio

Novatec Editora Ltda. Rua Lus Antnio dos Santos 110 02460-000 So Paulo, SP Brasil Tel.: +55 11 2959-6529 Fax: +55 11 2950-8869 Email: novatec@novatec.com.br Site: www.novatec.com.br Twitter: twitter.com/novateceditora Facebook: facebook.com/novatec LinkedIn: linkedin.com/in/novatec
Dados Internacionais de Catalogao na Publicao (Cmara Brasileira do Livro, SP, Brasil) (CIP)

jQuery Cookbook / Comunidade de Desenvolvedores jQuery. [traduo Gustavo Cssio de Moraes / Rafael Zanolli] . -- So Paulo : Novatec Editora, 2010. ISBN 978-85-7522-227-0 1. JavaScript (Linguagem de programao para computadores) 2. jQuery 3. Web sites Desenvolvimento 4. Web sites - Design I. Comunidade de Expert em jQuery.

10-08737

CDD-005.133 ndices para catlogo sistemtico: 1. jQuery : Biblioteca JavaScript de cdigo aberto : Programao Web : Computadores : Processamento de dados 005.133

OGF20101202

captulo 1

Noes bsicas de jQuery

Cody Lindley

1.0 Introduo
Uma vez que voc est diante de um livro cookbook (de receitas) sobre jQuery, os autores desta obra, em sua maioria, presumem que voc tem uma vaga ideia sobre o que exatamente a jQuery e o que ela faz. Para falar a verdade, livros cookbook em geral, normalmente so escritos para um pblico que procura reforar uma base de conhecimento j estabelecida. Assim, o formato de receita-soluo-discusso utilizado para que voc rapidamente encontre solues a problemas comuns. No entanto, se voc novato em jQuery, no jogue este livro contra a parede, tampouco o maldiga. Dedicamos este captulo a voc. Se estiver precisando de uma reviso ou comeando este livro de receitas com pouco ou nenhum conhecimento funcional da jQuery, este primeiro captulo (os outros presumem que voc saiba o bsico) vai ajud-lo a compreender os fundamentos da jQuery. Agora, se por outro lado voc no tem absolutamente nenhum conhecimento de JavaScript e DOM, pode ser interessante dar um passo atrs e questionar se abordar a jQuery sem uma compreenso bsica da linguagem JavaScript e de sua relao com o DOM plausvel. Minha recomendao seria estudar o fundamental sobre o DOM e sobre JavaScript antes de se aproximar da jQuery. Recomendo JavaScript: The Definitive Guide (http://oreilly.com/catalog/9780596000486), de David Flanagan (OReilly), como uma prvia, mas no deixe minha humilde opinio impedi-lo de aprender jQuery antes de aprender sobre o DOM e JavaScript. Muitos tm alcanado um conhecimento prtico dessas tecnologias por meio da jQuery. E, embora no seja ideal, honestamente falando, isso ainda pode ser feito. Dito isso, veremos a definio formal da jQuery em uma breve descrio de sua funcionalidade:
jQuery uma biblioteca JavaScript de cdigo aberto que simplifica as interaes entre um documento HTML, ou, mais precisamente, o Document Object Model (tambm conhecido como DOM), e o JavaScript.

24

Captulo 1 Noes bsicas de jQuery

25

Simplificando, e para os hackers JavaScript da velha-guarda, a jQuery torna o HTML dinmico (DHTML) incrivelmente fcil. Mais especificamente, ele simplifica a manipulao e o percurso no documento HTML, o tratamento de eventos do navegador, as animaes do DOM, as interaes com Ajax e o desenvolvimento de JavaScript para mltiplos navegadores. Depois dessa explicao formal, exploraremos os porqus de voc optar pela jQuery.

Por que jQuery?

Pode parecer um pouco tolo falar sobre os mritos da jQuery, uma vez que, se voc est lendo este livro, provavelmente j os conhece. Ainda assim, mesmo que possa parecer repetitivo, faremos uma prvia acerca dos motivos pelos quais um desenvolvedor deve optar pela jQuery, com o intuito de promover seu conhecimento bsico da jQuery, primeiramente explicando o porqu e, aps, analisando o como . Na defesa da jQuery, no vou compar-la aos seus concorrentes para aumentar sua importncia. Isso porque simplesmente no acredito que ela realmente tenha um concorrente direto. Alm disso, creio que a nica biblioteca disponvel atualmente que atende s necessidades tanto dos designers quanto dos programadores a jQuery. Nesse contexto, a jQuery est em uma categoria prpria. Das notrias bibliotecas e frameworks de JavaScript no mercado, acredito que cada uma tenha seu prprio nicho e valor. Uma comparao ampla bobagem, mas, ainda assim, tentada o tempo todo. At mesmo eu sou culpado desse crime. No entanto, aps muita reflexo sobre o tpico, acredito que todas as bibliotecas JavaScript tm algo de bom. Todas tm valor. O que faz com que uma seja mais valiosa do que a outra depende mais de quem a utiliza, e de como ela utilizada, e no do que ela realmente faz. Alm disso, tenho observado que as microdiferenas entre bibliotecas JavaScript so geralmente banais, considerando-se os objetivos mais amplos do desenvolvimento JavaScript. Assim, sem maiores divagaes filosficas, segue uma lista de atributos que justifica por que voc deve usar a jQuery: de cdigo aberto e o projeto est licenciado sob as licenas GNU General Public License (GPL) e MIT. Ela gratuita, meu amigo, e de vrias maneiras!; pequena (18 KB minificado1), em formato gzip (114 KB, sem compactao);
1 N.T.: A minificao (ou tambm minimizao), nas linguagens de programao de computadores e especialmente em JavaScript, o processo de remoo de todos os caracteres desnecessrios do cdigo-fonte, sem alterar sua funcionalidade. Esses caracteres normalmente incluem caracteres de espao em branco, de nova linha, comentrios e, s vezes, delimitadores de bloco; que so utilizados para conferir legibilidade ao cdigo, mas que no so necessrios para sua execuo.

26

jQuery Cookbook

incrivelmente popular, o que significa que h uma grande comunidade de usurios e uma boa quantidade de colaboradores que participam como programadores e evangelistas; normaliza as diferenas entre os navegadores web para que voc no tenha de faz-lo; tem intencionalmente um footprint2 leve, com uma arquitetura de plugin simples, mas inteligente; seu repositrio de plugins (http://plugins.jquery.com/) vasto e apresenta constante crescimento desde o lanamento da jQuery; sua API amplamente documentada, incluindo exemplos de cdigo inline, o que, no mundo das bibliotecas JavaScript, um luxo. Podemos dizer que, durante anos, a presena de qualquer tipo de documentao foi considerada um luxo; amigvel, o que significa que fornece meios teis para evitar conflitos com outras bibliotecas JavaScript; o apoio que tem da comunidade realmente til, incluindo a existncia de vrias listas de discusso, canais IRC e uma quantidade incomum e insana de tutoriais, artigos e posts em blogs da comunidade jQuery; tem desenvolvimento aberto, o que significa que qualquer um pode contribuir para as correes de bugs, em melhorias e ajudando a desenvolv-la; seu desenvolvimento constante e consistente, o que denota que a equipe de desenvolvimento no tem medo de lanar atualizaes; sua adoo pelas grandes organizaes proporcionou e continuar estimulando a longevidade e estabilidade (por exemplo, Microsoft, Dell, Bank of America, Digg, CBS, Netflix); est incorporando especificaes da W3C antes dos navegadores, por exemplo, a jQuery suporta a maioria dos seletores CSS3; encontra-se atualmente testada e otimizada para desenvolvimento nos navegadores modernos (Chrome 1, Chrome Nightly, IE 6, IE 7, IE 8, o Opera 9.6, Safari3.2, o WebKit Nightly, Firefox 2, Firefox 3, Firefox Nightly); absolutamente poderosa nas mos tanto de designers quanto de programadores. jQuery no discrimina; sua elegncia, metodologia e filosofia de mudar a forma como o JavaScript escrito est se tornando um padro. Pense em quantas outras solues emprestaram os padres de seletor e de encadeamento;
2 N.T.: O termo footprint originrio do conceito biolgico de Ecological Footprint (ou Pegada ecolgica). Quando aplicado a empresas, refere-se aos recursos naturais usados por uma organizao para viabilizar suas operaes. (Fonte: Wikipdia)

Captulo 1 Noes bsicas de jQuery

27

sua facilidade entusiasmante contagiosa; at mesmo os crticos parecem se apaixonar por aspectos da jQuery; sua documentao est disponvel em diversas formas (por exemplo, o navegador da API, aplicaes para o dashboard, cheat sheets), incluindo um navegador offline da API (aplicao AIR); foi planejada para ser usada com tcnicas de JavaScript no obstrutivas; manteve-se, primariamente, como uma biblioteca JavaScript (em oposio a um framework), ao mesmo tempo em que fornece um projeto-irmo para widgets de interface do usurio e desenvolvimento de aplicaes (jQuery UI); sua curva de aprendizagem acessvel, pois se baseia em conceitos que a maioria dos desenvolvedores e designers j entende (por exemplo, CSS e HTML). Sou da opinio de que a combinao dos pontos positivos da jQuery, e no cada atributo por si s, que a coloca em uma posio destacada. O pacote completo da jQuery simplesmente incomparvel como uma ferramenta de JavaScript.

Filosofia jQuery
A filosofia da jQuery Escreva menos, faa mais. Essa filosofia pode ser subdividida em trs conceitos: selecionar alguns elementos (por meio de seletores CSS) e fazer algo com eles (utilizando os mtodos da jQuery); encadear vrios mtodos jQuery em apenas um conjunto de elementos; utilizar o encapsulador jQuery e as iteraes implcitas. Entender essas trs definies detalhadamente fundamental para escrever seu prprio cdigo jQuery ou estender as receitas encontradas neste livro. Analisaremos cada um desses conceitos detalhadamente.

Selecionar alguns elementos e fazer algo com eles

Ou, mais especificamente, localizar um conjunto de elementos no DOM e fazer algo com esse conjunto. Por exemplo, examinaremos um cenrio no qual voc deseja ocultar uma <div> do usurio, carregar algum novo contedo de texto na <div> oculta, alterar um atributo da <div> selecionada, e finalmente tornar a <div> escondida visvel novamente. Essa ltima frase traduzida em cdigo jQuery seria mais ou menos assim:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html>

28

jQuery Cookbook
<head> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> </head> <body> <div>old content</div> <script> // ocultar todas as divs da pgina jQuery('div').hide(); // atualizar o texto contido em todas as divs jQuery('div').text('new content'); // adicionar uma classe com um valor de updatedContent a todas as divs jQuery('div').addClass("updatedContent"); // mostrar todas as divs da pgina jQuery('div').show(); </script> </body> </html>

Vamos observar essas quatro sentenas jQuery: esconder a <div> na pgina, isto , escond-la da vista do usurio; substituir o texto dentro da <div> oculta com algum texto novo (new content); atualizar a <div> com um novo atributo (class) e valor (updatedContent); mostrar a <div> na pgina de modo que seja novamente visvel para o usurio. Se o cdigo jQuery, neste momento estiver com uma sintaxe obscura, no se preocupe. Abordaremos o essencial com a primeira receita deste captulo. Novamente, o que voc precisa para entender esse exemplo de cdigo o conceito de encontrar alguns elementos e fazer algo com eles. Em nosso exemplo, encontramos todos os elementos <div> na pgina HTML utilizando a funo jQuery (jQuery()), em seguida, utilizando mtodos do jQuery, fizemos algo com eles (por exemplo, hide(), text(), addClass(), show()).

Encadeamento
A jQuery construda de forma a permitir que seus mtodos possam ser encadeados. Por exemplo, por que no encontrar um elemento uma s vez e depois encadear as operaes feitas nele? Nosso exemplo anterior de cdigo demonstrou como selecionar alguns elementos e fazer algo com eles conceito que poderia ser reescrito em uma , nica instruo JavaScript usando encadeamento. Esse cdigo, usando encadeamento, seria alterado desta forma:

Captulo 1 Noes bsicas de jQuery

// ocultar todas as divs da pgina jQuery('div').hide(); // atualizar o texto contido em todas as divs jQuery('div').text('new content'); // adicionar uma classe com um valor de updatedContent a todas as divs jQuery('div').addClass("updatedContent"); // mostrar todas as divs da pgina jQuery('div').show();

29

para esta:
jQuery('div').hide().text('new content').addClass("updatedContent").show();

ou, com endentao e quebras de linhas, para esta:

jQuery('div') .hide() .text('new content') .addClass("updatedContent") .show();

O encadeamento simplesmente permite que voc aplique uma sequncia interminvel de mtodos jQuery sobre os elementos selecionados (encapsulados atualmente com as funcionalidades jQuery) usando a funo jQuery. Nos bastidores, os elementos previamente selecionados, antes de um mtodo jQuery ser aplicado, so sempre retornados para que a cadeia possa continuar. Como voc ver nas receitas a seguir, os plugins tambm so construdos dessa maneira (retornando elementos encapsulados), de modo que o uso de um plugin no quebre a corrente. Se no estiver imediatamente bvio com base no cdigo em questo, o encadeamento tambm reduz a sobrecarga (overhead) de processamento, selecionando um conjunto de elementos DOM apenas uma vez e depois operando nele vrias vezes pelos mtodos jQuery por meio de encadeamento. Evitar percursos desnecessrios pelo DOM uma parte crtica das melhorias no desempenho da pgina. Sempre que possvel, reutilize ou coloque em cache um conjunto de elementos DOM selecionados.

Conjunto encapsulador da jQuery

Na maioria das vezes, se a jQuery estiver envolvida, voc ter um encapsulador (wrapper). Em outras palavras, voc estar selecionando elementos DOM de uma pgina HTML, os quais sero encapsulados com a funcionalidade da jQuery. Pessoalmente, refiro-me a isso como um conjunto encapsulador ou conjunto encapsulado , porque trata-se de um conjunto de elementos encapsulado com a funcionalidade jQuery. s vezes, esse conjunto encapsulador conter um elemento DOM; outras vezes, vrios. H ainda casos em que o conjunto encapsulador no conter elementos. Nessas

30

jQuery Cookbook

situaes, os mtodos/propriedades que a jQuery oferece, falharo silenciosamente se mtodos forem chamados em um conjunto encapsulador vazio, o que pode ser til para evitar sentenas if desnecessrias. Agora, com base no cdigo que utilizamos para demonstrar o conceito de como Encontrar alguns elementos e fazer algo com eles o que voc acha que aconteceria , se acrescentssemos vrios elementos <div> pgina web? No exemplo seguinte, com o cdigo atualizado, acrescentei mais trs elementos <div> pgina HTML, para um total de quatro elementos <div>:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.0/jquery.min.js"></script> </head> <body> <div>old content</div> <div>old content</div> <div>old content</div> <div>old content</div> <script> // ocultar todas as divs da pgina jQuery('div').hide().text('new content').addClass("updatedContent").show(); </script> </body> </html>

Voc at pode no ter escrito explicitamente nenhum loop programtico aqui, mas adivinhem: a jQuery far a varredura da pgina e colocar todos os elementos <div> no conjunto encapsulador, de modo que os mtodos da jQuery, aqui utilizados, sejam aplicados (tambm conhecido como iterao implcita) em cada elemento DOM do conjunto. Por exemplo, o mtodo .hide(), na verdade aplica-se a cada elemento do conjunto. Portanto, se voc observar nosso cdigo, ver que cada mtodo ser aplicado a cada elemento <div> na pgina. como se voc tivesse escrito um loop para invocar cada mtodo jQuery em cada elemento DOM. O exemplo com cdigo atualizado far com que cada <div> da pgina seja escondido, preenchido com texto atualizado, alterado com um novo valor de classe e, em seguida, exibido novamente. Compreender o conjunto encapsulador e seu sistema padro de looping (tambm conhecido como iterao implcita) fundamental para a construo de conceitos avanados em torno do looping. Basta compreender que um loop simples est ocorrendo aqui, antes de realmente fazer qualquer looping adicional (por exemplo, jQuery('div').each(function(){}). Outra forma de olhar para isso pensar que cada

Captulo 1 Noes bsicas de jQuery

31

elemento do encapsulador ser normalmente alterado pelo(s) mtodo(s) jQuery(s) que so chamados. Apenas lembre-se de que h cenrios, como os que voc conhecer nos prximos captulos, nos quais apenas o primeiro elemento, e no todos os elementos do conjunto encapsulador, afetado pelo mtodo jQuery (por exemplo, attr()).

Como a API da jQuery organizada

No h dvida de que, quando dei meus primeiros passos na jQuery, o principal motivo para selecion-la como minha biblioteca JavaScript foi simplesmente por ela ter sido devidamente documentada (e pelo nmero enorme de plugins!). Mais tarde, percebi que outro fator que fortaleceu meu caso de amor com a jQuery foi o fato de sua API ter sido organizada em categorias lgicas. Examinando a forma como ela foi organizada, poderia especificar a funcionalidade de que precisava. Antes de voc realmente comear seu trabalho com a jQuery, sugiro que visite a documentao online (http://docs.jquery.com/Main_Page) e assimile como a API est organizada. Ao compreender sua organizao, voc navegar mais rapidamente na documentao at a informao exata de que precisa, o que uma vantagem significativa, uma vez que, na verdade, h uma srie de maneiras diferentes de codificar uma soluo jQuery. Ela to completa que fcil ficar preso na implementao devido ao nmero de solues distintas a um nico problema. Reproduzi aqui como a API est organizada. Sugiro que voc memorize seu esboo, ou, pelo menos, as categorias de nvel superior: Ncleo da jQuery A funo jQuery Acessores de objeto jQuery Dados Plugins Interoperabilidade Seletores Conceitos bsicos Hierarquia Filtros bsicos Filtros de contedo Filtros de visibilidade Filtros de atributos Filtros de filhos

32

jQuery Cookbook

Formulrios Filtros de formulrios Atributos Attr Class HTML Text Value Percurso Filtragem Busca Encadeamento Manipulao Modificao de contedo Insero interna (inside) Insero externa (outside) Insero em torno (around) Substituio Remoo Cpia CSS CSS Posicionamento Altura e largura Eventos Carregamento da pgina Manipulao de eventos Eventos dinmicos Auxiliares de interao Auxiliares de eventos Efeitos Conceitos bsicos

Captulo 1 Noes bsicas de jQuery

33

Deslizamento Esmaecimento (fading) Personalizados Configuraes Ajax Requisies AJAX Eventos AJAX Diversos Utilitrios Deteco de caractersticas e de navegadores Operaes com array e com objetos Operaes de teste Operaes de string URLs Antes de avanarmos para uma srie de receitas bsicas da jQuery, gostaria de mencionar que as receitas encontradas neste captulo evoluem progressivamente; ou seja, h uma formao lgica de conhecimento, conforme voc avana a partir da primeira e em direo ltima receita. Sugiro que a sua primeira leitura dessas receitas seja realizada na ordem de 1.1 a 1.17.

1.1 Incluindo o cdigo da biblioteca jQuery em uma pgina HTML

Problema
Voc quer utilizar a biblioteca JavaScript jQuery em uma pgina web.

Soluo
Atualmente h duas solues ideais para incorporar a biblioteca jQuery em uma pgina web: usar a rede de fornecimento de contedo (Content Delivery Network, CDN) hospedada no Google para incluir uma verso da jQuery (mtodo utilizado neste captulo); baixar sua verso da jQuery em jQuery.com e hosped-la em seu servidor ou sistema de arquivos local.

34

jQuery Cookbook

Discusso
Incluir a biblioteca JavaScript jQuery no um processo diferente da incluso de qualquer outro arquivo JavaScript externo. Voc simplesmente usa o elemento HTML <script>, fornece um valor (URL ou o path de diretrio) para seu atributo src="", e o arquivo externo que voc est vinculando ser includo na pgina web. A seguir, temos um modelo que inclui a biblioteca jQuery, que voc pode utilizar para iniciar qualquer projeto jQuery:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> </head> <body> <script type="text/JavaScript"> alert('jQuery ' + jQuery.fn.jquery); </script> </body> </html>

Observe que estou usando e recomendo que voc tambm o faa para pginas web pblicas a verso minificada da jQuery hospedada no Google. No entanto, a depurao de erros de JavaScript em cdigo minificado no ideal. Durante o desenvolvimento do cdigo, ou na produo do site, pode ser melhor utilizar a verso no minificada do Google, com a finalidade de depurar possveis erros de JavaScript. Para obter mais informaes sobre como usar a verso hospedada no Google da jQuery, voc pode visitar o site da API das bibliotecas Ajax na web: http://code.google.com/ apis/ajaxlibs/. Tambm possvel, e isso no nenhuma novidade, hospedar uma cpia do cdigo jQuery consigo. Na maioria dos casos, porm, seria desnecessrio faz-lo, j que o Google teve a bondade de hosped-la para voc. Ao utilizar uma verso hospedada no Google da jQuery, voc se beneficia de uma cpia estvel, confivel, de alta velocidade e globalmente disponvel. Assim, beneficia-se de uma diminuio da latncia, de um aumento do paralelismo e de um melhor armazenamento em cache. Isso, obviamente, poderia ser realizado sem o uso da soluo do Google, mas seu custo seria provavelmente maior do que apenas alguns trocados. Ainda, pode acontecer de voc no querer usar a verso hospedada no Google da jQuery, mas sim uma verso personalizada, ou sua utilizao pode no exigir/ter acesso a uma conexo de Internet ou ainda, por ser obcecado por controle e um

Captulo 1 Noes bsicas de jQuery

35

fantico por conspiraes, voc pode simplesmente acreditar que o Google seja um Todo poderoso e no desejar se submeter a ele. Portanto, aqueles que no precisam, ou simplesmente que no querem, usar uma cpia hospedada no Google do cdigo jQuery, podem baixar um verso direto do site jQuery.com (http://docs.jquery.com/ Downloading_jQuery) e hosped-la localmente no prprio servidor ou no sistema local de arquivos. Com base no modelo fornecido nesta receita, basta substituir o valor do atributo src com uma URL ou o path do diretrio para a localizao do arquivo Javascript jQuery que voc baixou.

1.2 Executando cdigo jQuery/JavaScript depois de carregar o DOM, mas antes do carregamento completo da pgina
Problema
As modernas aplicaes JavaScript que utilizam metodologias no obstrutivas normalmente executam cdigo JavaScript somente depois de o DOM ser completamente carregado. A realidade da situao que qualquer operao no DOM exigir que ele esteja carregado antes de ser operado. Nesse caso, necessria uma maneira de determinar quando o cliente, na maioria das vezes um navegador web, carregou completamente o DOM, mas sem ter ainda carregado completamente todos os recursos, como imagens e arquivos SWF. Se usssemos o evento window.onload nessa situao, o documento inteiro, incluindo todos os recursos, deveria estar completamente carregado antes de o evento onload ser disparado. Isso consome tempo demais para a maioria dos usurios. Precisamos de um evento que nos avise quando o DOM, por si, estiver pronto para ser percorrido e manipulado.

Soluo
A jQuery fornece o mtodo ready(), que um manipulador de eventos personalizado tipicamente vinculado ao objeto do documento do DOM. Ao mtodo ready() passado um nico parmetro, uma funo que contm o cdigo JavaScript, que deve ser executado assim que o DOM estiver pronto para ser percorrido e manipulado. A seguir, temos um exemplo simples desse evento, que abre uma janela de alert() assim que o DOM estiver pronto, mas antes que a pgina esteja totalmente carregada:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script>

36

jQuery Cookbook
<script type="text/JavaScript"> jQuery(document).ready(function() { // DOM no carregado, deve utilizar o evento ready alert(jQuery('p').text()); }); </script> </head> <body> <p>The DOM is ready!</p> </body> </html>

Discusso
O mtodo de manipulao de eventos ready() o substituto da jQuery para o uso do evento window.onload do JavaScript core. Pode ser utilizado quantas vezes voc quiser. Ao utilizar esse evento personalizado, aconselhvel que ele seja includo em suas pginas, aps a incluso de declaraes de folhas de estilo e de includes. Fazendo isso, voc garante que todas as propriedades do elemento estejam corretamente definidas antes de qualquer cdigo jQuery ou cdigo JavaScript ser executado pelo evento ready(). Alm disso, a prpria funo jQuery oferece um atalho para uso do evento personalizado ready da jQuery. Com esse atalho, o seguinte exemplo de alert() pode ser reescrito desta forma:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> jQuery(function() { // DOM no carregado, deve utilizar o evento ready alert(jQuery('p').text()); }); </script> </head> <body> <p>The DOM is ready!</p> </body> </html>

A utilizao desse evento jQuery personalizado necessria somente se o JavaScript for usado e esteja na parte superior da pgina e encapsulado no elemento <head>. Pessoalmente, apenas evito o uso do evento ready() colocando todos os cdigos

Captulo 1 Noes bsicas de jQuery

37

JavaScript, inclusive os cdigos inline, antes do fechamento do elemento <body>. Fao isso por dois motivos. Em primeiro lugar, as tcnicas modernas de otimizao declaram que as pginas carregam mais rapidamente quando o JavaScript carregado pelo navegador no fim da leitura da pgina. Em outras palavras, se voc colocar o cdigo JavaScript ao final de uma pgina web, o navegador carregar tudo antes que carregue o JavaScript. Isso algo bom, porque a maioria dos navegadores normalmente para o processamento de outras iniciativas de carregamento at que o engine de JavaScript tenha compilado o JavaScript contido em uma pgina web. uma espcie de gargalo, visto que voc tem o JavaScript no topo de um documento de uma pgina web. Sei que, para algumas situaes, mais fcil colocar o JavaScript no elemento <head>. Porm, honestamente, nunca vi uma situao em que isso fosse absolutamente necessrio. Todos os obstculos que encontrei no meu desenvolvimento colocando o JavaScript ao final da pgina foram facilmente superados, e os ganhos de otimizao valeram a pena. Em segundo lugar, se pginas web rpidas so nosso objetivo, por que encapsular mais funcionalidades em torno de uma situao que pode ser melhorada simplesmente movendo o cdigo para a parte inferior da pgina? Quando temos a escolha entre ter mais cdigo ou menos cdigo, escolho sempre menos cdigo. No usar o evento ready() resulta na utilizao de menos cdigo, especialmente porque um volume menor de cdigo sempre roda mais rpido do que um volume maior. Tendo apresentado minhas justificativas, aqui est um exemplo do nosso cdigo de
alert() que no utiliza o evento ready(): <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <p>The DOM is ready!</p> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> alert(jQuery('p').text()); // v em frente, o DOM est carregado </script> </body> </html>

Reparem que coloquei todo meu JavaScript antes do elemento </body> de fechamento. Qualquer marcao adicional deve ser colocada acima do JavaScript no documento HTML.

38

jQuery Cookbook

1.3 Selecionando elementos DOM utilizando seletores e a funo jQuery

Problema
Voc precisa selecionar um nico elemento DOM e/ou um conjunto de elementos DOM, a fim de operar no(s) elemento(s) utilizando mtodos jQuery.

Soluo
A jQuery oferece duas opes quando voc precisa selecionar o(s) elemento(s) do DOM. Ambas as opes requerem o uso da funo jQuery (jQuery() ou do alias $()). A primeira opo, que utiliza seletores CSS e seletores customizados, , de longe, a mais utilizada e a soluo mais eloquente. Ao passar funo jQuery uma string contendo uma expresso seletora, a funo percorrer o DOM e localizar os ns do DOM definidos pela expresso. Como exemplo, o cdigo a seguir selecionar todos os elementos <a> no documento HTML:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <a href='#'>link</a> <a href='#'>link</a> <a href='#'>link</a> <a href='#'>link</a> <a href='#'>link</a> <a href='#'>link</a> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> // alerta que h 6 elementos alert('Page contains ' + jQuery('a').length + ' <a> elements!'); </script> </body> </html>

Se fosse executar esse cdigo HTML em um navegador web, voc veria que o cdigo executa um alert() de navegador que nos informa que a pgina contm seis elementos <a>. Passei esse valor para o mtodo alert() primeiramente selecionando todos os elementos <a>, e, em seguida, usando a propriedade length para retornar o nmero de elementos no conjunto encapsulador jQuery.

Captulo 1 Noes bsicas de jQuery

39

Voc deve estar ciente de que o primeiro parmetro da funo jQuery, como estamos usando aqui, tambm aceitar mltiplas expresses. Para isso, basta separar seletores mltiplos com uma vrgula dentro da mesma string, que passada como primeiro parmetro da funo jQuery. Veja um exemplo da aparncia desse processo:
jQuery('selector1, selector2, selector3').length;

Nossa segunda opo, e a menos comum, para selecionar elementos DOM, passar funo jQuery uma referncia JavaScript real para o(s) elemento(s) DOM. Como exemplo, o cdigo a seguir selecionar todos os elementos <a> no documento HTML. Observe que estou passando funo jQuery um array de elementos <a> obtidos por meio do mtodo DOM getElementsByTagName. Este exemplo produz os mesmos resultados do nosso exemplo anterior de cdigo:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body bgcolor="yellow"> <!-- sim, o atributo est obsoleto, isto s um exemplo --> <a href='#'>link</a> <a href='#'>link</a> <a href='#'>link</a> <a href='#'>link</a> <a href='#'>link</a> <a href='#'>link</a> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> // alerta que h 6 elementos alert('Page contains ' + jQuery(document.getElementsByTagName('a')).length + ' <a> Elements, And has a ' + jQuery(document.body).attr('bgcolor') + ' background'); </script> </body> </html>

Discusso
O trabalho pesado, pelo qual a jQuery reconhecida, parcialmente feito com base no engine de seleo Sizzle (http://sizzlejs.com/), que seleciona elemento(s) DOM de um documento HTML. Embora tenha a opo, e ela ser uma boa opo quando precisar dela, passar referncias do DOM funo jQuery no o que torna a jQuery famosa. So as grandes e poderosas opes disponveis com seletores que fazem dele algo to diferente.

40

jQuery Cookbook

Durante todo o resto do livro, voc encontrar seletores potentes e robustos. Quando encontr-los, certifique-se de compreender plenamente sua funo. Esse conhecimento ir ajud-lo em futuras empreitadas de codificao usando jQuery.

1.4 Selecionando elementos DOM em um contexto especfico

Problema
Voc precisa de uma referncia a um nico elemento DOM ou a um conjunto deles, no contexto de outro elemento DOM ou documento, a fim de operar no(s) elemento(s) utilizando mtodos jQuery.

Soluo
A funo jQuery, quando passada uma expresso CSS como parmetro, tambm aceita um segundo parmetro que informa a ela em qual contexto deve procurar pelos elementos DOM com base na expresso. O segundo parmetro, nesse caso, pode ser uma referncia DOM, um encapsulador jQuery, ou um documento. No cdigo a seguir, h 12 elementos <input>. Observe como utilizo um contexto especfico, com base no elemento <form>, para selecionar apenas elementos <input> especficos:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <form> <input <input <input <input </form> <form> <input <input <input <input </form> name="" name="" name="" name="" type="checkbox" /> type="radio" /> type="text" /> type="button" />

name="" name="" name="" name=""

type="checkbox" /> type="radio" /> type="text" /> type="button" />

<input name="" type="checkbox" /> <input name="" type="radio" /> <input name="" type="text" />

Captulo 1 Noes bsicas de jQuery

<input name="" type="button" /> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> // pesquisa em todos os elementos form, usando um encapsulador como contexto, // alerta "8 entradas" alert('selected ' + jQuery('input',$('form')).length + ' inputs'); // pesquisa no primeiro elemento form, usando a referncia DOM como contexto, // alerta "4 entradas" alert('selected' + jQuery('input',document.forms[0]).length + ' inputs'); // pesquisa dentro de body por todos os elementos input usando uma expresso, // alerta "12 entradas" alert('selected' + jQuery('input','body').length + ' inputs'); </script> </body> </html>

41

Discusso
Tambm possvel, como mencionado na soluo desta receita, selecionar documentos como o contexto para a pesquisa. Por exemplo, possvel pesquisar dentro do contexto de um documento XML que enviado de volta ao fazer uma requisio XHR (Ajax). Voc pode encontrar mais detalhes sobre esse uso no captulo 16.

1.5 Filtrando um conjunto encapsulador de elementos DOM

Problema
Voc tem um conjunto de elementos DOM selecionados em um conjunto encapsulador jQuery, mas deseja remover elementos do conjunto que no correspondem a uma (ou mais de uma) nova expresso especificada, a fim de criar um novo conjunto de elementos sobre os quais ir operar.

Soluo
O mtodo jQuery filter(), usado em um conjunto encapsulador jQuery de elementos DOM, pode excluir os elementos que no correspondam a uma expresso(es) especificada(s). Em suma, o mtodo filter() permite que voc filtre o atual conjunto de elementos. Essa uma distino importante do mtodo find da jQuery, que reduzir um conjunto encapsulado de elementos DOM, procurando (por meio de uma nova expresso seletora) novos elementos, incluindo elementos-filho do atual conjunto encapsulado.

42

jQuery Cookbook

Para entender o mtodo filter(), examinaremos o seguinte cdigo:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <a href="#" class="external">link</a> <a href="#" class="external">link</a> <a href="#"></a> <a href="#" class="external">link</a> <a href="#" class="external">link</a> <a href="#"></a> <a href="#">link</a> <a href="#">link</a> <a href="#">link</a> <a href="#">link</a> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> // alerta 4 restantes no conjunto alert(jQuery('a').filter('.external').length + ' external links'); </script> </body> </html>

A pgina HTML, mostrada no exemplo de cdigo, contm apenas uma pgina web com 10 elementos <a>. Aos links que so externos adicionada a classe external. Usando a funo jQuery, selecionamos todos os elementos <a> na pgina. Em seguida, utilizando o mtodo de filtro, todos os elementos que no tm um valor de atributo class de external so removidos do conjunto original. Uma vez que o conjunto inicial de elementos DOM alterado usando o mtodo filter(), invoco a propriedade length, que mostrar quantos elementos esto no novo conjunto, aps o filtro ser aplicado.

Discusso
Tambm possvel enviar ao mtodo filter() uma funo que pode ser utilizada para filtrar um conjunto encapsulado. Nosso exemplo anterior de cdigo, que passa ao mtodo filter() uma expresso string, pode ser alterado para usar uma funo, em vez disto:
alert( jQuery('a') .filter(function(index) { return $(this).hasClass('external');}) .length + ' external links' );

Captulo 1 Noes bsicas de jQuery

43

Repare que, agora, estou passando ao mtodo filter() uma funo annima. Essa funo chamada com um contexto igual ao do elemento atual. Isso significa que, quando usar $(this) na funo, estarei na realidade me referindo a cada elemento DOM no conjunto encapsulado. Na funo, estou verificando cada elemento <a> no conjunto encapsulado, para ver se o elemento tem uma classe (hasClass()) chamada external. Se isso acontecer, a funo retorna um tipo booleano verdadeiro (true); ento, mantenha o elemento no conjunto, caso contrrio (false), remova o elemento do conjunto. Outra maneira de enxergar esse funcionamento : se a funo retornar false, o elemento ser removido. Caso a funo retorne qualquer valor que no false, o elemento permanecer no conjunto encapsulado. Voc deve ter notado que passei funo o parmetro index, que no estou usando. Esse parmetro, se necessrio, pode ser usado para se referir numericamente ao ndice do elemento no conjunto encapsulador jQuery.

1.6 Encontrando elementos descendentes no atual conjunto encapsulado

Problema
Voc tem um conjunto selecionado de elementos DOM (ou apenas um elemento) e quer encontrar elementos descendentes (filhos) no contexto dos elementos atualmente selecionados.

Soluo
Use o mtodo .find() para criar um novo conjunto encapsulado de elementos com base no contexto do conjunto atual e dos seus descendentes. Por exemplo, digamos que voc tenha uma pgina web na qual h vrios pargrafos. Encapsulados nesses pargrafos, encontram-se palavras enfatizadas (itlico). Se quiser selecionar apenas elementos <em> contidos em elementos <p>, poderia fazer assim:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <p>Ut ad videntur facilisis <em>elit</em> cum. Nibh insitam erat facit <em>saepius</em> magna. Nam ex liber iriure et imperdiet. Et mirum eros iis te habent. </p> <p>Claram claritatem eu amet dignissim magna. Dignissim quam elit facer eros illum. Et qui ex esse <em>tincidunt</em> anteposuerit. Nulla nam odio ii vulputate feugait.</p> <p>In quis <em>laoreet</em> te legunt euismod. Claritatem <em>consuetudium</em>

44

jQuery Cookbook
wisi sit velit facilisi.</p> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> // alerta o total de palavras em itlico encontradas nos elementos <p> alert('The three paragraphs in all contain ' + jQuery('p').find('em').length + ' italic words'); </script> </body> </html>

Tenha em mente que poderamos, tambm, ter escrito esse cdigo passando uma referncia contextual como um segundo parmetro para a funo jQuery:
alert('The three paragraphs in all contain ' + jQuery('em',$('p')).length +' italic words');

Alm disso, vale a pena mencionar que os dois ltimos exemplos de cdigo tm a proposta de serem demonstrativos. Parece mais lgico, se no pragmtico, utilizar uma expresso seletora CSS para selecionar todos os elementos descendentes em itlico contidos nos elementos <p> anteriores.
alert('The three paragraphs in all contain ' + jQuery('p em').length +' italic words');

Discusso
O mtodo .find() da jQuery pode ser utilizado para criar um novo conjunto de elementos, com base no contexto do atual conjunto de elementos DOM e seus elementos-filho. As pessoas, muitas vezes, confundem o uso do mtodo .filter() com o do mtodo .find(). A maneira mais fcil de lembrar a diferena considerar que o .find() operar/selecionar os filhos do conjunto atual, enquanto que o .filter() somente funcionar com o atual conjunto de elementos. Em outras palavras, se quiser alterar o atual conjunto encapsulado usando-o como um contexto para facilitar a seleo dos filhos dos elementos selecionados, use .find(). Se apenas deseja filtrar o atual conjunto encapsulado e obter um novo subconjunto dos atuais elementos DOM apenas no conjunto, utilize o .filter(). Em sntese, o mtodo .find() retorna elementos filhos, enquanto o filter() apenas filtra o que est no conjunto encapsulado atual.

1.7 Retornando para a seleo prvia antes de uma mudana destrutiva

Problema
Um mtodo jQuery destrutivo (como, filter() ou find()) que foi utilizado em um conjunto de elementos, precisa ser removido para que o conjunto, antes da utilizao do mtodo destrutivo, seja devolvido ao seu estado anterior e possa ser operado como se o mtodo destrutivo nunca tivesse sido chamado.

Captulo 1 Noes bsicas de jQuery

45

Soluo
A jQuery fornece o mtodo end() de modo que voc possa voltar ao conjunto anterior de elementos DOM, os quais foram selecionados antes de usar um mtodo destrutivo. Para entender o mtodo end(), analisaremos o seguinte cdigo HTML.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <p>text</p> <p class="middle">Middle <span>text</span></p> <p>text</p> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> alert(jQuery('p').filter('.middle').length); // alerta 1 alert(jQuery('p').filter('.middle').end().length); // alerta 3 alert(jQuery('p').filter('.middle').find('span').end().end().length); // alerta 3 </script> </body> </html>

A primeira instruo alert() no cdigo contm uma instruo jQuery que procurar no documento todos os elementos <p> e, em seguida, aplicar filter() nos elementos <p> selecionados do conjunto, selecionando apenas aquele(s) com a classe middle. A propriedade length, em seguida, relatar quantos elementos restam no conjunto:
alert(jQuery('p').filter('.middle').length); // alerta 1

A prxima instruo alert() faz uso do mtodo end(). Estamos fazendo, neste momento, tudo o que fizemos na instruo anterior, exceo de desfazer o filter() e retornar ao conjunto de elementos contidos no conjunto encapsulado definido antes de o mtodo filter() ser aplicado:
alert(jQuery('p').filter('.middle').end().length); // alerta 3

A ltima sentena de alert() demonstra como o mtodo end() utilizado duas vezes para remover as mudanas destrutivas filter() e find(), retornando o conjunto encapsulado definido sua composio original:
alert(jQuery('p').filter('.middle').find('span').end().end().length); // alerta 3

46

jQuery Cookbook

Discusso
Se o mtodo end() for utilizado e no houver operaes destrutivas anteriores, ele retorna um conjunto vazio. Uma operao destrutiva qualquer operao que modifique o conjunto de elementos jQuery correspondidos, o que implica qualquer mtodo de seleo ou manipulao que retornar um objeto jQuery, incluindo add(), andSelf(), children(), closes(), filter(), find(), map(), next(), nextAll(), not(), parent(), parents(), prev(), prevAll(), siblings(), slice(), clone(), appendTo(), prependTo(), insertBefore(), insertAfter() e replaceAll().

1.8 Incluindo a seleo anterior na seleo atual

Problema
Voc manipulou apenas um conjunto de elementos, a fim de adquirir um novo conjunto. No entanto, pretende operar no conjunto anterior, assim como no conjunto atual.

Soluo
Voc pode combinar uma seleo prvia de elementos DOM com a seleo atual usando o mtodo andSelf(). Por exemplo, no cdigo a seguir, primeiramente selecionamos todos os elementos <div> da pgina. Em seguida, manipulamos esse conjunto de elementos encontrando todos os elementos <p> contidos nos elementos <div>. Agora, a fim de operar tanto no <div> quanto nos elementos <p> encontrados dentro dele, poderamos incluir o <div> no conjunto atual usando andSelf(). Se tivesse omitido o andSelf(), a cor da borda apenas teria sido aplicada aos elementos <p>:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <div> <p>Paragraph</p> <p>Paragraph</p> </div> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> jQuery('div').find('p').andSelf().css('border','1px solid #993300'); </script> </body> </html>

Captulo 1 Noes bsicas de jQuery

47

Discusso
Tenha em mente que, quando voc usa o mtodo andSelf(), ele somente acrescenta ao conjunto atual que est sendo operado e ao anterior, e no a todos os conjuntos anteriores.

1.9 Percorrendo o DOM com base em seu contexto atual para adquirir um novo conjunto de elementos DOM
Problema
Voc selecionou um conjunto de elementos DOM e, com base na posio dos elementos selecionados na rvore do DOM, pretende percorrer o DOM para selecionar novos elementos.

Soluo
A jQuery oferece um conjunto de mtodos para percorrer o DOM com base no contexto do(s) elemento(s) DOM atualmente selecionado(s). Por exemplo, analisaremos o seguinte trecho HTML:
<div> <ul> <li><a href="#">link</a></li> <li><a href="#">link</a></li> <li><a href="#">link</a></li> <li><a href="#">link</a></li> </ul> </div>

Agora, selecionaremos o segundo elemento <li> utilizando o seletor personalizado de ndice :eq():
// seleciona o segundo elemento no conjunto de <li> por seu ndice, que comea em 0 jQuery('li:eq(1)');

Temos agora um contexto, um ponto de partida dentro da estrutura HTML. Nosso ponto de partida o segundo elemento <li>. A partir disso, podemos ir a qualquer lugar, bem, a quase todos. Veremos para onde podemos ir com alguns mtodos jQuery fornecidos para percorrer o DOM. Leia os comentrios no cdigo para esclarecimentos:
jQuery('li:eq(1)').next() jQuery('li:eq(1)').prev() // seleciona o terceiro <li> // seleciona o primeiro <li>

jQuery('li:eq(1)').parent() // seleciona o <ul>

48
jQuery('li:eq(1)').parent().children() jQuery('li:eq(1)').nextAll() jQuery('li:eq(1)').prevAll() // seleciona todos os <li>

jQuery Cookbook

// seleciona todos os <li> depois do segundo <li> // seleciona todos os <li> antes do segundo <li>

Tenha em mente que esses mtodos de travessia produzem um novo conjunto encapsulador, e que para retornar ao conjunto encapsulado anterior, voc pode utilizar end().

Discusso
Os mtodos de seleo apresentados at agora tm demonstrado percursos simples. H dois conceitos adicionais importantes sobre selees. O primeiro conceito, e provavelmente o mais bvio, que os mtodos de seleo podem ser encadeados. Examinaremos novamente a seguinte sentena jQuery:
jQuery('li:eq(1)').parent().children() // seleciona todos os <li>

Repare que andei do segundo elemento <li> para o elemento-pai <ul> e novamente parti do elemento-pai para selecionar todos os elementos-filho do elemento <ul>. O conjunto encapsulador jQuery agora conter todos os elementos contidos no <ul>. Evidentemente, esse um exemplo inventado com a finalidade de demonstrar os mtodos de seleo. Se realmente quisssemos um conjunto encapsulador apenas de elementos <li>, teria sido muito mais simples selecionar todos os elementos <li> desde o princpio (por exemplo, jQuery('li')). O segundo conceito de que voc precisa ter em mente quando lida com os mtodos de seleo que muitos dos mtodos aceitaro um parmetro opcional que pode ser utilizado para filtrar as selees. Daremos nosso exemplo encadeado novamente e ver como podemos alter-lo para que apenas o ltimo elemento <li> seja selecionado. Lembre-se de que esse um exemplo inventado com o propsito de demonstrar como podemos selecionar um elemento muito especfico usando os mtodos de seleo:
jQuery('li:eq(1)').parent().children(':last') // seleciona o ltimo <li>

A jQuery fornece mtodos adicionais de seleo os quais no foram mostrados aqui. Para obter uma lista completa e sua documentao, acesse: http://docs.jquery.com/ Traversing. Voc encontrar esses mtodos adicionais de seleo utilizados ao longo deste livro.

1.10 Criando, operando e inserindo elementos DOM

Problema
Voc quer criar novos elementos DOM (ou apenas um elemento) que so imediatamente selecionados, operados e, injetados no DOM.

Captulo 1 Noes bsicas de jQuery

49

Soluo
Caso ainda no tenha percebido, a funo jQuery multifacetada e desempenha uma funo diferente dependendo da composio do(s) parmetro(s) que voc envia a ela. Se fornecer a funo com uma string de texto de HTML puro, ela criar dinamicamente esses elementos para voc. Por exemplo, a seguinte instruo criar um elemento <a> encapsulado dentro de um elemento <p> com um nodo de texto encapsulado dentro dos elementos <p> e <a>:
jQuery('<p><a>jQuery</a></p>');

Agora, com um elemento criado, voc pode usar mtodos da jQuery para continuar a operar sobre os elementos que criou. como se tivesse selecionado o elemento <p> desde o princpio em um documento HTML existente. Por exemplo, poderamos operar no <a> usando o mtodo .find() para selecionar o elemento <a> e definir um de seus atributos. No caso do cdigo a seguir, definimos o atributo href com o valor de http://www.jquery.com:
jQuery('<p><a>jQuery</a></p>').find('a').attr('href','http://www.jquery.com');

Isso timo, no ? Pois est prestes a ficar ainda melhor, porque tudo o que fizemos at agora foi criar elementos e manipul-los no cdigo. Ainda temos de mudar o DOM atualmente carregado, por assim dizer. Para fazer isso, usaremos os mtodos de manipulao fornecidos pela jQuery. O cdigo seguinte est no contexto de um documento HTML. Aqui estamos criando elementos, manipulando-os e, aps, inserindo-os no DOM com o mtodo de manipulao appendTo():
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> jQuery('<p><a>jQuery</a></p>').find('a').attr('href','http://www.jquery.com') .end().appendTo('body'); </script> </body> </html>

Observe como o mtodo end() usado para desfazer o mtodo find(), a fim de que, quando o mtodo appendTo() for chamado, ele acrescente ao que estava originalmente contido no conjunto encapsulado inicial.

50

jQuery Cookbook

Discusso
Nesta receita, passamos funo jQuery uma string de HTML puro, que usada para criar elementos DOM. Tambm possvel simplesmente passar funo jQuery um objeto DOM criado pelo mtodo createElement() do DOM:
jQuery(document.createElement('p')).appendTo('body'); //adiciona um elemento p vazio pgina

Isso poderia ser consideravelmente trabalhoso dependendo dos pormenores de sua utilizao, enquanto apenas uma string de HTML contendo mltiplos elementos j funcionaria adequadamente. Tambm vale a pena mencionar que s arranhamos a superfcie dos mtodos de manipulao utilizando o mtodo appendTo(). Alm do mtodo appendTo(), existem tambm os seguintes mtodos de manipulao: append() prepend() prependTo() after() before() insertAfter() insertBefore() wrap() wrapAll() wrapInner()

1.11 Removendo elementos DOM

Problema
Voc quer remover elementos do DOM.

Soluo
O mtodo remove() pode ser utilizado para remover um conjunto de elementos do DOM e seus elementos-filho. Verifique os seguintes exemplos:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head>

Captulo 1 Noes bsicas de jQuery

<body> <h3>Anchors</h3> <a href='#'>Anchor Element</a> <a href='#'>Anchor Element</a> <a href='#'>Anchor Element</a> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> jQuery('a').remove(); </script> </body> </html>

51

Quando o cdigo anterior for carregado em um navegador, os elementos-ncora permanecero na pgina at que o JavaScript seja executado. Assim que o mtodo remove() for utilizado para remover todos os elementos-ncora do DOM, a pgina visualmente conter apenas um elemento <h3>. Tambm possvel passar ao mtodo uma expresso para filtrar o conjunto de elementos a serem removidos. Por exemplo, nosso cdigo poderia ser alterado para remover ncoras apenas com uma classe especfica:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <h3>Anchors</h3> <a href='#' class='remove'>Anchor Element</a> <a href='#'>Anchor Element</a> <a href='#' class="remove">Anchor Element</a> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> jQuery('a').remove('.remove'); </script> </body> </html>

Discusso
Ao utilizar o mtodo remove() da jQuery, lembre-se de dois pontos:

52

jQuery Cookbook

enquanto os elementos selecionados so removidos do DOM utilizando o remove(), eles no so retirados do conjunto jQuery encapsulador. Isso significa que, teoricamente, voc poderia continuar a operar sobre eles e at mesmo adicion-los novamente ao DOM, se desejar; esse mtodo no apenas remover os elementos do DOM, mas tambm todos os manipuladores de eventos internos e dados armazenados em cache que possam estar contidos nos elementos retirados.

1.12 Substituindo elementos DOM

Problema
necessrio substituir os atuais ns do DOM por novos.

Soluo
Utilizando o mtodo replaceWith(), podemos selecionar um conjunto de elementos DOM para reposio. No exemplo de cdigo a seguir, utilizaremos o mtodo replaceWith() para substituir todos os elementos <li> com um atributo class de remove com uma nova estrutura DOM:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <ul> <li class='remove'>name</li> <li>name</li> <li class='remove'>name</li> <li class='remove'>name</li> <li>name</li> <li class='remove'>name</li> <li>name</li> <li class='remove'>name</li> </ul> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> jQuery('li.remove').replaceWith('<li>removed</li>'); </script> </body> </html>

Captulo 1 Noes bsicas de jQuery

53

A nova estrutura adicionada ao DOM vem de uma string passada no mtodo replaceWith(). Em nosso exemplo, todos os elementos <li>, incluindo elementos filhos, so substitudos pela nova estrutura, <li>removed</li>.

Discusso
A jQuery oferece um mtodo inverso a esse, o replaceAll() que faz a mesma tarefa com os parmetros invertidos. Por exemplo, poderamos reescrever o cdigo jQuery encontrado em nossa receita desta maneira:
jQuery('<li>removed</li>').replaceAll('li.remove');

Nesse momento, passamos funo jQuery a string de HTML e, em seguida, usamos o replaceAll() para selecionar o n do DOM e seus filhos os quais queremos remover e substituir.

1.13 Clonando elementos DOM

Problema
Voc precisa clonar/copiar um trecho do DOM.

Soluo
A jQuery oferece o mtodo clone() para copiar elementos do DOM. Seu uso simples. Basta selecionar os elementos DOM usando a funo jQuery e, depois, chamar o mtodo clone() no conjunto de elemento(s) selecionado(s). O resultado uma cpia da estrutura DOM sendo devolvida para encadeamento, em vez dos elementos DOM inicialmente selecionados. No cdigo a seguir, clonarei o elemento <ul> e, posteriormente, acrescentarei essa cpia de volta ao DOM, utilizando o mtodo de insero appendTo(). Basicamente, acrescento outra estrutura <ul> pgina, exatamente igual outra j presente:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <ul> <li>list</li> <li>list</li> <li>list</li> <li>list</li> </ul>

54

jQuery Cookbook
<script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> jQuery('ul').clone().appendTo('body'); </script> </body> </html>

Discusso
O mtodo de clonagem realmente muito til para mover snippets3 do DOM internamente. especialmente til quando voc quer no apenas copiar e mover os elementos do DOM, mas tambm os eventos ligados aos elementos clonados do DOM. Examine atentamente o HTML e a jQuery a seguir:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <ul id="a"> <li>list</li> <li>list</li> <li>list</li> <li>list</li> </ul> <ul id="b"></ul> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"></script> <script type="text/JavaScript"> jQuery('ul#a li') .click(function() {alert('List Item Clicked')}) .parent() .clone(true) .find('li') .appendTo('#b') .end() .end() .end() .remove(); </script> </body> </html> 3 N.T.: Um snippet um termo de programao para uma pequeno trecho de cdigo-fonte, cdigo de mquina ou texto reutilizvel. (fonte: Wikipdia)

Captulo 1 Noes bsicas de jQuery

55

Se voc fosse executar esse cdigo em um navegador, ele clonaria os elementos <li> na pgina que tem um evento de clique a eles associado, inseriria esses elementos recmclonados (incluindo os eventos) no <ul> vazio e removeria o elemento <ul> clonado. Isso pode ser um pouco difcil de entender para um desenvolvedor iniciante em jQuery. Ento, examinaremos essa instruo jQuery, percorrendo o cdigo, a fim de explicar os mtodos encadeados:

1. jQuery('ul#a li') Seleciona o elemento <ul> com um id de valor a, e seleciona todos os elementos <li> dentro do <ul>. 2. .click(function(){alert('List Item Clicked')}) Acrescenta um evento click para cada <li>. 3. .parent() Atravessa o DOM, substituindo o conjunto selecionado para o elemento <ul>. 4. .clone(true) Clona o elemento <ul> e todos seus filhos, incluindo todos os eventos anexados aos elementos que esto sendo clonados. Isso feito passando ao mtodo clone() um valor booleano true. 5. .find('li') Agora, dentro dos elementos clonados, modifica o conjunto de elementos para apenas os elementos <li> contidos no elemento <ul> clonado. 6. .appendTo('#b') Toma essa seleo de elementos <li> clonados e coloca-os dentro do elemento <ul> que tem um id igual a b. 7. .end() Retorna ao conjunto de elementos anteriormente selecionado, que era o elemento <li> clonado. 8. .end() Retorna ao conjunto de elementos anteriormente selecionado, que era o elemento <ul> clonado. 9. .end() Retorna ao conjunto de elementos anteriormente selecionado, que era o elemento <ul> original clonado. 10. .remove() Remove o elemento <ul> original.
A compreenso de como manipular o conjunto selecionado de elementos ou de como reverter para o conjunto anteriormente selecionado crucial para operaes complexas usando a jQuery.

1.14 Obtendo, definindo, e removendo atributos de elemento do DOM

Problema
Voc selecionou um elemento DOM usando a funo jQuery e precisa obter (get) ou definir (set) o valor do atributo do elemento DOM.

56

jQuery Cookbook

Soluo
A jQuery oferece o mtodo attr() para obter e definir valores de atributos. No cdigo a seguir, definiremos e, em seguida, obteremos o valor de um atributo href de um elemento <a>:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <a>jquery.com</a> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"> </script> <script type="text/JavaScript"> // mostra em um alerta a URL da home page da jQuery alert( jQuery('a').attr('href','http://www.jquery.com').attr('href') ); </script> </body> </html>

Como voc pode verificar no exemplo de cdigo, selecionamos o nico elemento <a> no documento HTML, definimos seu atributo href e, em seguida, obtemos seu valor com o mesmo mtodo attr(), passando ao mtodo o nome do atributo sozinho. Se houvesse mltiplos elementos <a> no documento, o mtodo attr() acessaria o primeiro elemento a que correspondesse. O cdigo, quando carregado em um navegador, alertar (alert()) o valor que definimos ao atributo href. Agora, como a maioria dos elementos tem mais de um atributo disponvel, tambm possvel definir atributos de diversos valores usando um nico mtodo attr(). Por exemplo, poderamos tambm definir o atributo title no exemplo anterior, passando ao mtodo attr() um objeto em vez de dois parmetros string:
jQuery('a').attr({'href':'http://www.jquery.com','title':'jquery.com'}).attr('href')

Soma-se capacidade de adicionar atributos a elementos a capacidade de remover os atributos e seus valores. O mtodo removeAttr() pode ser utilizado para remover atributos de elementos HTML. Para utiliz-lo, basta passar a ele um valor string do atributo o qual voc deseja remover (por exemplo, jQuery('a').removeAttr('title')).

Captulo 1 Noes bsicas de jQuery

57

Discusso
Alm do mtodo attr(), a jQuery oferece um conjunto especfico de mtodos para trabalhar com o atributo class do elemento HTML. Uma vez que um elemento pode conter vrias classes (por exemplo, class="class1 class2 class3"), esses mtodos sero usados para gerenciar esses valores. Os mtodos JQuery so estes:
addClass()

Atualiza o valor do atributo class com um novo(a) valor/classe, mantendo outras classes j presentes.
hasClass()

Verifica se o valor do atributo class contm uma classe especfica.

removeClass()

Remove uma classe nica do atributo class enquanto mantm os valores definidos.
toggleClass()

Adiciona a classe especificada se ela no estiver presente; remove a classe especificada se ele estiver presente.

1.15 Obtendo e definindo o contedo HTML

Problema
Voc precisa obter (get) ou definir (set) um bloco de contedo HTML na atual pgina web.

Soluo
A jQuery fornece o mtodo html() para obter e definir blocos (ou estruturas DOM) de elementos HTML. No cdigo a seguir, utilizamos esse mtodo para definir e obter o valor do elemento HTML <p>, encontrado no documento HTML:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <p></p>

58

jQuery Cookbook
<script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"> </script> <script type="text/JavaScript"> jQuery('p').html('<strong>Hello World</strong>, I am a <em>&lt;p&gt;</em> element.'); alert(jQuery('p').html()); </script> </body> </html>

Executar esse cdigo em um navegador resultar no navegador alertando o contedo HTML contido no elemento <p>, que foi definido utilizando o mtodo html() e depois recuperado usando o mtodo html().

Discusso
Esse mtodo usa a propriedade innerHTML do DOM para obter e definir blocos de HTML. Voc tambm deve estar ciente de que esse html() no est disponvel em documentos XML (embora ele funcione para documentos XHTML).

1.16 Obtendo e definindo contedo de texto

Problema
Voc precisa obter (get) ou definir (set) um texto que est dentro de um(uns) elemento(s) HTML.

Soluo
A jQuery fornece o mtodo text() para obter e definir o contedo de texto dos elementos. No cdigo a seguir, utilizamos esse mtodo para definir e obter o valor de texto do elemento <p> encontrado no documento HTML:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> </head> <body> <p></p> <script type="text/JavaScript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js"> </script>

Captulo 1 Noes bsicas de jQuery

<script type="text/JavaScript"> jQuery('p').text('Hello World, I am a <p> element.'); alert(jQuery('p').text()); </script> </body> </html>

59

Executar esse cdigo em um navegador resultar no navegador alertando o contedo do elemento <p>, que foi definido usando o mtodo text() e depois recuperado usando o mtodo text().

Discusso
importante lembrar que o mtodo text() no diferente do html(), exceto pelo fato de que ele escapar o HTML (substituindo < e > por suas entidades HTML). Isso significa que, se voc colocar tags dentro da string de texto passada ao mtodo text(), ele converter essas tags s suas entidades HTML (&lt; e &gt;).

1.17 Usando o alias $ sem criar conflitos globais

Problema
Voc quer utilizar o alias $ em vez de digitar o nome do namespace global (jQuery) sem medo de conflitos globais.

Soluo
Criar uma funo annima, autoinvocadora, para a qual passamos o objeto jQuery e, depois, usar o caractere $ como um ponteiro, apontando para o objeto jQuery. Por exemplo, todo o cdigo jQuery pode ser encapsulado dentro da seguinte funo autoinvocadora:
(function($) { // funo para criar o escopo privado com o parmetro $ // escopo privado utilizando o $ sem se preocupar com conflitos })(jQuery); // invoca a funo sem nome e passa a ela o objeto jQuery

Discusso
Essencialmente, o que acontece que passamos a referncia global jQuery para uma funo, criando um escopo privado. Se no tivssemos feito isso e optssemos por utilizar o alias $ no escopo global, correramos um risco ao presumir que no h outros scripts includos no documento HTML (ou que no haver outros scripts sendo includos no futuro) que utilizam o caractere $. Por que arriscar quando voc pode simplesmente criar seu prprio escopo privado?

60

jQuery Cookbook

Outra vantagem de fazer isso que o cdigo includo dentro da funo annima autoinvocadora ser executado em seu prprio escopo privado. Fique tranquilo, pois tudo o que for colocado na funo, provavelmente nunca causar um conflito com outro cdigo JavaScript escrito no escopo global. Assim, novamente, por que arriscar colises programticas? Basta criar seu prprio escopo privado.