Guia de início rápido

Neste tutorial rápido, nós iremos construir uma aplicação jQuery com o auxílio da biblioteca jQuery TOAD.

Trata-se de uma página que contém um botão para exibir uma mensagem pré-definida como alerta, e outro botão que exibe a mesma mensagem, porém como o texto de um elemento h1.

É bem simples, mas servirá para exemplificar nossa proposta. Em outros tutoriais nós iremos evoluir pra algo melhor, de acordo com que formos introduzindo novos conceitos.

Lembrando que, o que chamamos aqui de jQuery TOAD é o conjunto da biblioteca JavaScript mais essa documentação. Porque não se trata apenas de código, mas de conceitos para desenvolvimento de aplicações usando jQuery.

Criando o código inicial

Crie um arquivo index.html com o seguinte conteúdo:

Crie também um arquivo my-controller.js com o seguinte conteúdo:

Isso é tudo o que precisamos. Abra o arquivo index.html em seu navegador preferido e você verá dois botões:

Clicando no primeiro um alerta exibirá a mensagem "Olá mundo jQuery TOAD!". Clicando no segundo a mesma mensagem será atribuída a um título h1 logo abaixo dos botões na própria página.

Na verdade a mensagem será apresentada em um segundo h1, porque já existirá um contendo o texto "A mensagem virá aqui em baixo:".

Entendendo os conceitos básicos

Após você experimentar a aplicação funcionando em seu navegador, e ver com os próprios olhos a jQuery TOAD em ação, vamos agora entender algums conceitos básicos.

O que construímos em termos de aplicação não é tão útil assim, porém é mínimo o suficiente pra falarmos dos conceitos que queremos propor com o uso dessa biblioteca ao desenvolver aplicações jQuery.

1. Não misture HTML com JavaScript

Com exceção das linhas de 6 a 8 no aquivo index.html (iremos falar sobre isso logo abaixo) não temos código JavaScript misturado com HTML (isso também se aplica pra código CSS).

Isso também é percebido nas linhas 12 e 13 também do arquivo index.html:

Aqui ao invés de usar a propriedade HTML onclick (que é específica para o fim) nós usamos uma sintaxe um pouco diferente que é fornecida pela biblioteca jQuery TOAD. A vantagem dessa sobre a onclick, é que na onclick nós precisamos incluir código JavaScript, e nessa segunda abordagem na verdade o que estamos fazendo é informando que um evento chamado onClickMessage deve ser acionado ao ocorrer o evento onclick nativo do elemento HTML em si. Mas não informamos um código, porque o mesmo é definido por quem controla essa visão, no caso estamos falando do arquivo my-controller.js.

Todo o código JavaScript em sí é carregado de arquivos específicos. Veja isso nas linhas de 16 a 18 no arquivo index.html.

O resultado disso é que seus arquivos ficam muito mais legíveis. É muito mais fácil você trabalhar nesse arquivo sabendo que o que está contido nele é puramente código HTML.

2. Controle sua visão

Quando apresentamos a primeira regra, 1 - Não misture HTML com JavaScript, o que queremos dizer é muito mais amplo, queremos dizer: "Não misture, mas separe as coisas".

Separe o que é código de apresentação (a visão do usuário), ou seja, o próprio HTML, do código que controla a sua aplicação, isso é o seu código JavaScript.

Esse é o princípio do MVC (Model, View e Controller - Modelo, Visão e Controlador) (saiba mais sobre MVC nesse artigo), e nós propomos o uso desse conceito para desenvolver suas aplicações jQuery. A biblioteca jQuery TOAD te ajuda a fazer isso.

Veja que na linha 11 do arquivo index.html anotamos algo na tag body,:

Com isso jQuery TOAD já sabe ligar esse elemento HTML body a um objeto JavaScript correspondente, neste caso identificado por my.

3. Seja semântico

Ser semântico é dar e observar a "significação" das coisas. É o que chamo de: "uma coisa é uma coisa, outra coisa é outra coisa".

No arquivo index.html, na linha 15, nós identificamos o elemento h1 com um dado personalizado data-id="message", isso é uma marca que estamos fazendo para encontrar este item mais tarde por nossa controller, no caso para saber onde apresentar o texto da mensagem.

Muitos de nós já estamos acostumados a fazer isso usando a propriedade id, o que ficaria assim:

Outros ainda usam uma classe, o que ficaria assim:

Na verdade, já que estamos falando de semântica, o ideal aqui seria usar a propriedade id para tal, ao invés de data-id. Mais tarde em outro tutorial estaremos vendo porque usar id não é o ideal, por agora só peço que entenda que data-id="message" é a nossa forma de marcar um elemento para identificá-lo mais tarde.

O não tão ideal seria usar a propriedade class, que apesar de servir para identificação, ou seja para classificar elementos, nós a usamos muito mais para identificar elementos para uso em estilos CSS, então deixamos assim:

• Quando temos um class="message" podemos inferir que isso identifica um elemento para fins de apresentação;
• Quando temos um data-id="message" podemos inferir que isso identifica um elemento para fins de controle de aplicação;

Com isso deixamos claro que "uma coisa é uma coisa" e "outra coisa é outra coisa". E o mais importante é que isso não infringe as regras de semântica do HTML, porque o atributo data-* está aí justamente para acoplar dados personalizados a nossos elementos, só o que estamos fazendo é usando-os para o que são feitos.

4. Modularize

Seja para o reaproveitamento de código, para a segurança de código (um código não interferir no funcionamento de oturo), para a organização (cada coisa no seu lugar), ou simplesmente para a simplicidade (é muito mais fácil ler o código pequeno de uma controller, do que achar o trecho responsável pela controller num arquivo gigante de aplicação).

Qualquer que seja o seu propósito, modularizar é o princípio de tudo, e logo na linha 1 do arquivo my-controller.js nós temos a jQuery TOAD nos ajudando com isso:

Primeiramente nós temos esse objeto global MYAPP. Esse deve ser o único objeto global que sua aplicação "pendura" na window.

Lembra quando falei no item 1: ... "Com exceção das linhas de 6 a 8 no aquivo index.html..."

Pois bem, o único motivo de existir esse trecho de código em sua página HTML é pra definir qual será o nome do objeto global que conterá a aplicação TOAD. Como definimos para MYAPP, tudo partirá de MYAPP..., se você der outro nome, já sabe o que fazer.

Na verdade sempre teremos dois objetos globais, um será a variável __TOAD__ que contém o nome do objeto global da aplicação, e outro será o próprio objeto global da aplicação em si. Mas didaticamente isto não é importante (rsss).

Poderíamos pré-definir um nome como App, ou mesmo $ClientApp ou algo desse tipo (pensei nisso a princípio), e com isso não precisaríamos do trecho de código JavaScript contido no HTML acima. Mas entendemos que o nome da aplicação diz muito nos scripts que escrevemos. Por exemplo, imagine que sua aplicação se chama SIGF (Sistema Integrado de Gestão de Frameworks), então um trecho de código como esse:

É muito sugestivo, não!?

Entenda que MYAPP é o seu módulo principal de aplicação, e dentro deste módulo estarão vários outros módulos (submódulos) que você construirá de acordo com sua necessidade, para abrigar suas várias peças de software, e para isso você usará espaços de nomes para manter tudo catalogado e organizado.

No nosso exemplo, criamos um espaço de nomes chamado controllers e nele abrigamos o controllador de nossa página. Com isso já garantimos que nada irá vazar para a window ou outro escopo exterior.

O controlador em si é uma função JavaScript construtora padrão, e dentro dela nós criamos uma variável privada chamada message que contém a mensagem que desejamos exibir. Também definimos dois métodos públicos, this.onClickMessage e this.onClickH1 que por sua vez são referenciados na nossa visão, lembra:

Com isso sabemos que o clicar de cada botão, chamará um método específico do controlador.

Aqui o importante é saber que o método precisa ser público para que jQuery TOAD possa vinculá-lo corretamente, ou seja, o método precisa estar "pendurado" no this do controlador.

O código de cada método em nossa controller é JavaScript puro ou jQuery puro e não precisa de maiores explicações.

O que temos de diferente ainda são somente a linha 2 do arquivo my-controller.js, que usa o recurso require do jQuery TOAD para acessar os módulos de nossa aplicação.

Aqui no caso estamos acessando um objeto especial chamado @registerController, que é um recursos da jQuery TOAD, nós o utilizamos mais abaixo na linha 18 pra registrar nossa controller, chamada de my e vinculada ao objeto MyController:

Você seguirá a mesma lógica sempre que precisar acessar objetos entre os vários espaços de nomes. Já que nós criamos um espaço de nomes chamado controllers, imagine também que você criou outro espaço de nomes chamado utils. Então de dentro de controllers, caso precise acessar objetos de utils você usaria algo como:

Daí é só você utilizar o conteúdo de utils. É claro que ainda falta falar sobre require/exports, mas trataremos disso em outro tutorial.

Concluindo

Mesmo sendo um exemplo de código tão pequeno, serviu para explanarmos sobre nossa proposta de como podemos desenvolver aplicações jQuery de uma forma padronizada, e aplicando boas práticas que nos fazem tanto bem. Se você investir um pouco de tempo estudando essa nossa proposta, verá que pode aplicá-la imediatamente em seus projetos que usam pura e exclusivamente jQuery e JavaScript.

Também me arrisco a dizer, que com esse investimento de tempo pra ler essa documentação por inteiro talvez te convença a ponderar melhor sobre a necessidade de ter que usar alguma abordagem SPA em todos os seus projetos. Talvez o "velho e querido jQuery" já seja mais do que suficiente.

Em suma o que queremos propor com jQuery TOAD é um padrão para desenvolver aplicações puramente JavaScript e jQuery seguindo essas simples regras:

1. Não misture HTML com JavaScript
2. Controle sua visão
3. Seja semântico
4. Modularize

Este tutorial pode não ser conclusivo para você entender o uso de jQuery TOAD, mas com certeza fala dos princípios que nortearam o seu desenvolvimento.

Convido você a ler todos os outros tutoriais e descobrir como essa biblioteca junto a essa documentação pode te ajudar a desenvolver aplicações jQuery mais sustentáveis.

Sua opinião também é muito bem vinda, seja para comentar sobre os vários erros contidos na documentação, quanto para tirar dúvidas e/ou propor melhorias. Fique à vontade, o código e a documentação estão aí pra isso.