Quick Start
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.
Então vamos lá!
Crie um arquivo index.html com o seguinte conteúdo:
<!DOCTYPE html>
<html lang="pt-br">
<head>
<meta charset="utf-8">
<script type="text/javascript">
var __TOAD__ = 'MYAPP'
</script>
</head>
<body data-controller="my">
<button data-events="click=>onClickMessage">Diga olá por alerta!</button>
<button data-events="click=>onClickH1">Diga olá no H1!</button>
<h1>A mensagem virá aqui em baixo:</h1>
<h1 data-id="message"></h1>
<script src="https://unpkg.com/jquery@1.12.4/dist/jquery.js"></script>
<script src="https://unpkg.com/jquery-toad/dist/jquery-toad.js"></script>
<script src="my-controller.js"></script>
</body>
</html>Crie também um arquivo my-controller.js com o seguinte conteúdo:
MYAPP.namespace('controllers', function () {
var register = MYAPP.require('@registerController');
function MyController() {
var message = 'Olá mundo jQuery TOAD!';
this.onClickMessage = function () {
alert(message);
}
this.onClickH1 = function () {
$('[data-id="message"]').text(message);
}
}
register({
name: 'my',
ctor: MyController
});
})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:".
Aqui está a DEMO deste exemplo!
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.
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:
<button data-events="click=>onClickMessage">Diga olá por alerta!</button>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.
<script src="https://unpkg.com/jquery@2.2.4/dist/jquery.js"></script>
<script src="https://unpkg.com/jquery-toad/dist/jquery-toad.js"></script>
<script src="my-controller.js"></script>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.
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>:
<body data-controller="my">Com isso jQuery TOAD já sabe ligar esse elemento HTML <body> a um objeto JavaScript correspondente, neste caso identificado por my.
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.
<h1 data-id="message"></h1>Muitos de nós já estamos acostumados a fazer isso usando a propriedade id, o que ficaria assim:
<h1 id="message"></h1>Outros ainda usam uma classe, o que ficaria assim:
<h1 class="message"></h1>Na verdade, já que estamos falando de semântica, o ideal aqui seria usar a propriedade
idpara tal, ao invés dedata-id. Mais tarde em outro tutorial estaremos vendo porque usaridnão é o ideal, por agora só peço que entenda quedata-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.
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:
MYAPP.namespace('controllers', function () {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..."
<script type="text/javascript">
var __TOAD__ = 'MYAPP'
</script>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:
SIGF.namespace(...)É 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:
<button data-events="click=>onClickMessage">Diga olá por alerta!</button>
<button data-events="click=>onClickH1">Diga olá no H1!</button>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 os objetos do espaço de nomes @, que é um espaço reservado para recursos da jQuery TOAD, neste caso utilizamos o método Controller mais abaixo nas linhas de 16 a 19 pra registrar nossa controller, chamada de my e vinculada ao objeto MyController:
register({
name: 'my',
ctor: MyController
});Mas você seguirá a mesma lógica sempre que precisar acessar os 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:
var utils = MYAPP.require('utils');Daí é só você utilizar o conteúdo de utils. É claro que ainda falta falar sobre require/exports, mas trataremos disso em outro tutorial.
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:
- Não misture HTML com JavaScript
- Controle sua visão
- Seja semântico
- 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.