jquery-toad

<!DOCTYPE html> <html lang="pt-br"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"> <meta http-equiv="X-UA-Compatible" content="ie=edge"> <title>jQuery TOAD</title> <link rel="icon" href="images/jquery-toad-icon.png"> <link rel="stylesheet" href="https://unpkg.com/bootstrap@4.1.2/dist/css/bootstrap.css"> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.1.0/css/all.css"> <link rel="stylesheet" href="https://unpkg.com/highlightjs@9.10.0/styles/github-gist.css"> <link rel="stylesheet" href="style/toad.css"> <script> var __TOAD__ = 'TOAD'; </script> </head> <body data-controller="main"> <main role="main"> <div class="container"> <div class="toad-main-box bg-light border-dark"> <div class="toad-logo-box"><img class="img-fluid" src="images/jquery-toad-logo.png" alt="Logo jQuery TOAD"></div> <nav class="navbar navbar-expand-lg navbar-dark bg-dark"><a class="navbar-brand" href="index.html">Home</a> <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#main-menu" aria-controls="main-menu" aria-expanded="false" aria-label="Alterna navegação"><span class="navbar-toggler-icon"></span></button> <div class="collapse navbar-collapse" id="main-menu"> <ul class="navbar-nav mr-auto"> <li class="nav-item active"><a class="nav-link" href="motivacao.html">Qual a motivação?</a></li> <li class="nav-item dropdown"><a class="nav-link dropdown-toggle" href="#" id="submenu-documentacao" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Documentação</a> <div class="dropdown-menu" aria-labelledby="submenu-documentacao"> <h6 class="dropdown-header">TUTORIAIS</h6><a class="dropdown-item" href="tutorial-quickstart.html">Guia de início rápido</a><a class="dropdown-item" href="tutorial-mvc.html">O padrão MVC</a> <div class="dropdown-divider"></div> <h6 class="dropdown-header">CONCEITOS</h6><a class="dropdown-item" href="conceito-variavel-toad.html">A variável <kbd>__TOAD__</kbd></a><a class="dropdown-item" href="conceito-modulo.html">Modularização</a><a class="dropdown-item" href="conceito-componente.html">Componentes</a><a class="dropdown-item" href="conceito-utilitario.html">Utilitários</a><a class="dropdown-item" href="conceito-configuracao.html">Configurações</a><a class="dropdown-item" href="conceito-constante.html">Constantes</a> </div> </li> </ul> </div> </nav> <div class="toad-content-box col-md-10 offset-md-1"> <h1 class="display-4 text-center">Guia de início rápido</h1> <p class="lead"> Neste tutorial rápido, nós iremos construir uma aplicação jQuery com o auxílio da biblioteca jQuery TOAD. </p> <blockquote class="blockquote"> 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 <code>h1</code>. </blockquote> <p class="lead"> É 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. </p> <p class="lead"> Lembrando que, o que chamamos aqui de <i>jQuery TOAD</i> é 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. </p> <h2>Criando o código inicial</h2> <p class="lead">Crie um arquivo <code>index.html</code> com o seguinte conteúdo:</p> <div data-gui="code-block" data-lang="html" data-file-path="samples/tutorial/quickstart/index.html"></div> <p class="lead">Crie também um arquivo <code>my-controller.js</code> com o seguinte conteúdo:</p> <div data-gui="code-block" data-lang="js" data-file-path="samples/tutorial/quickstart/my-controller.js"></div> <p class="lead"> Isso é tudo o que precisamos. Abra o arquivo <code>index.html</code> em seu navegador preferido e você verá dois botões: </p> <p class="lead"> Clicando no primeiro um alerta exibirá a mensagem <i>"Olá mundo jQuery TOAD!"</i>. Clicando no segundo a mesma mensagem será atribuída a um título <code>h1</code> logo abaixo dos botões na própria página. </p> <blockquote class="blockquote">Na verdade a mensagem será apresentada em um segundo <code>h1</code>, porque já existirá um contendo o texto <i>"A mensagem virá aqui em baixo:"</i>.</blockquote> <div data-gui="demo" data-file-path="samples/tutorial/quickstart/index.html"></div> <h2>Entendendo os conceitos básicos</h2> <p class="lead"> 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. </p> <p class="lead"> 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. </p> <h4>1. Não misture HTML com JavaScript</h4> <p class="lead"> Com exceção das linhas de <code>6 a 8</code> no aquivo <code>index.html</code> (iremos falar sobre isso logo abaixo) não temos código JavaScript misturado com HTML (isso também se aplica pra código CSS). </p> <div data-gui="code-block" data-lang="html" data-file-path="samples/tutorial/quickstart/index.html" data-line-begin="6" data-line-end="8"></div> <p class="lead">Isso também é percebido nas linhas <code>12 e 13</code> também do arquivo <code>index.html</code>:</p> <div data-gui="code-block" data-lang="html" data-file-path="samples/tutorial/quickstart/index.html" data-line-begin="12" data-line-end="13"></div> <p class="lead"> Aqui ao invés de usar a propriedade HTML <code>onclick</code> <i>(que é específica para o fim)</i> nós usamos uma sintaxe um pouco diferente que é fornecida pela biblioteca jQuery TOAD. A vantagem dessa sobre a <code>onclick</code>, é que na <code>onclick</code> nós precisamos incluir código JavaScript, e nessa segunda abordagem na verdade o que estamos fazendo é informando que um evento chamado <code>onClickMessage</code> deve ser acionado ao ocorrer o evento <code>onclick</code> 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 <code>my-controller.js</code>. </p> <p class="lead"> Todo o código JavaScript em sí é carregado de arquivos específicos. Veja isso nas linhas de <code>16 a 18</code> no arquivo <code>index.html</code>. </p> <div data-gui="code-block" data-lang="html" data-file-path="samples/tutorial/quickstart/index.html" data-line-begin="16" data-line-end="18"></div> <p class="lead"> 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. </p> <h4>2. Controle sua visão</h4> <p class="lead"> Quando apresentamos a primeira regra, <strong>1 - Não misture HTML com JavaScript</strong>, o que queremos dizer é muito mais amplo, queremos dizer: <strong><i>"Não misture, mas separe as coisas"</i></strong>. </p> <p class="lead"> 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. </p> <p class="lead"> Esse é o princípio do <i>MVC (Model, View e Controller - Modelo, Visão e Controlador)</i> (<a href="conceito-mvc.html">saiba mais sobre MVC nesse artigo</a>), e nós propomos o uso desse conceito para desenvolver suas aplicações jQuery. A biblioteca jQuery TOAD te ajuda a fazer isso. </p> <p class="lead">Veja que na linha <code>11</code> do <code>arquivo index.html</code> anotamos algo na tag <code>body,</code>:</p> <div data-gui="code-block" data-lang="html"></div> <p class="lead"> Com isso jQuery TOAD já sabe ligar esse elemento HTML <code>body</code> a um objeto JavaScript correspondente, neste caso identificado por <code>my</code>. </p> <h4>3. Seja semântico</h4> <p class="lead"> Ser semântico é dar e observar a <i>"significação"</i> das coisas. É o que chamo de: <strong><i>"uma coisa é uma coisa, outra coisa é outra coisa"</i></strong>. </p> <p class="lead"> No arquivo <code>index.html</code>, na linha <code>15</code>, nós identificamos o elemento <code>h1</code> com um dado personalizado <code>data-id="message"</code>, 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. </p> <div data-gui="code-block" data-lang="html"></div> <P class="lead">Muitos de nós já estamos acostumados a fazer isso usando a propriedade <code>id</code>, o que ficaria assim:</P> <div data-gui="code-block" data-lang="html"></div> <p class="lead">Outros ainda usam uma classe, o que ficaria assim:</p> <div data-gui="code-block" data-lang="html"></div> <blockquote class="blockquote"> Na verdade, já que estamos falando de semântica, o ideal aqui seria usar a propriedade <code>id</code> para tal, ao invés de <code>data-id</code>. Mais tarde em outro tutorial estaremos vendo porque usar <code>id</code> não é o ideal, por agora só peço que entenda que <code>data-id="message"</code> é a nossa forma de marcar um elemento para identificá-lo mais tarde. </blockquote> <p class="lead"> O não tão ideal seria usar a propriedade <code>class</code>, 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: </p> <ul class="lead"> <li>Quando temos um <code>class="message"</code> podemos inferir que isso identifica um elemento para fins de apresentação;</li> <li>Quando temos um <code>data-id="message"</code> podemos inferir que isso identifica um elemento para fins de controle de aplicação;</li> </ul> <p class="lead"> Com isso deixamos claro que <i>"uma coisa é uma coisa"</i> e <i>"outra coisa é outra coisa"</i>. E o mais importante é que isso não infringe as regras de semântica do HTML, porque o atributo <code>data-*</code> está aí justamente para acoplar dados personalizados a nossos elementos, só o que estamos fazendo é usando-os para o que são feitos. </p> <h4>4. Modularize</h4> <p class="lead"> 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). </p> <p class="lead"> Qualquer que seja o seu propósito, modularizar é o princípio de tudo, e logo na linha <code>1</code> do arquivo <code>my-controller.js</code> nós temos a jQuery TOAD nos ajudando com isso: </p> <div data-gui="code-block" data-lang="js"></div> <p class="lead"> Primeiramente nós temos esse objeto global <code>MYAPP</code>. Esse deve ser o único objeto global que sua aplicação "pendura" na <code>window</code>. </p> <p class="lead">Lembra quando falei no item 1: ... <i>"Com exceção das linhas de 6 a 8 no aquivo index.html..."</i></p> <div data-gui="code-block" data-lang="html" data-file-path="samples/tutorial/quickstart/index.html" data-line-begin="6" data-line-end="8"></div> <p class="lead"> 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 <strong>TOAD</strong>. Como definimos para <code>MYAPP</code>, tudo partirá de <code>MYAPP</code>..., se você der outro nome, já sabe o que fazer. </p> <blockquote class="blockquote"> Na verdade sempre teremos dois objetos globais, um será a variável <code>__TOAD__</code> 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). </blockquote> <p class="lead"> Poderíamos pré-definir um nome como <code>App</code>, ou mesmo <code>$ClientApp</code> 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 <string>SIGF</strong> (Sistema Integrado de Gestão de Frameworks), então um trecho de código como esse: </p> <div data-gui="code-block" data-lang="js"></div> <p class="lead">É muito sugestivo, não!?</p> <p class="lead"> Entenda que <code>MYAPP</code> é 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. </p> <p class="lead"> No nosso exemplo, criamos um espaço de nomes chamado <code>controllers</code> e nele abrigamos o controllador de nossa página. Com isso já garantimos que nada irá vazar para a <code>window</code> ou outro escopo exterior. </p> <p class="lead"> O controlador em si é uma função JavaScript construtora padrão, e dentro dela nós criamos uma variável privada chamada <code>message</code> que contém a mensagem que desejamos exibir. Também definimos dois métodos públicos, <code>this.onClickMessage</code> e <code>this.onClickH1</code> que por sua vez são referenciados na nossa visão, lembra: </p> <div data-gui="code-block" data-lang="html"></div> <p class="lead">Com isso sabemos que o clicar de cada botão, chamará um método específico do controlador.</p> <p class="lead"> Aqui o importante é saber que o método precisa ser público para que <i>jQuery TOAD</i> possa vinculá-lo corretamente, ou seja, o método precisa estar "pendurado" no <code>this</code> do controlador. </p> <p class="lead">O código de cada método em nossa controller é JavaScript puro ou jQuery puro e não precisa de maiores explicações.</p> <p class="lead"> O que temos de diferente ainda são somente a linha <code>2</code> do arquivo <code>my-controller.js</code>, que usa o recurso <code>require</code> do <i>jQuery TOAD</i> para acessar os módulos de nossa aplicação. </p> <p class="lead"> Aqui no caso estamos acessando um objeto especial chamado <code>@registerController</code>, que é um recursos da jQuery TOAD, nós o utilizamos mais abaixo na linha <code>18</code> pra registrar nossa controller, chamada de <code>my</code> e vinculada ao objeto <code>MyController</code>: </p> <div data-gui="code-block" data-lang="js"></div> <p class="lead"> 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 <code>controllers</code>, imagine também que você criou outro espaço de nomes chamado <code>utils</code>. Então de dentro de <code>controllers</code>, caso precise acessar objetos de <code>utils</code> você usaria algo como: </p> <div data-gui="code-block" data-lang="js"></div> <p class="lead"> Daí é só você utilizar o conteúdo de utils. É claro que ainda falta falar sobre <strong>require/exports</strong>, mas trataremos disso em outro tutorial. </p> <h2>Concluindo</h2> <p class="lead"> 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. </p> <p class="lead"> 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 <i>SPA</i> em todos os seus projetos. Talvez o <i>"velho e querido jQuery"</i> já seja mais do que suficiente. </p> <p class="lead"> Em suma o que queremos propor com <i>jQuery TOAD</i> é um padrão para desenvolver aplicações puramente JavaScript e jQuery seguindo essas simples regras: </p> <ol class="lead font-weight-bold"> <li>Não misture HTML com JavaScript</li> <li>Controle sua visão</li> <li>Seja semântico</li> <li>Modularize</li> </ol> <p class="lead"> 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. </p> <p class="lead"> 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. </p> <p class="lead"> 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. </p> </div> </div> </div> </main> <footer class="text-secondary bg-light border-dark toad-footer-box"> <div class="container"> <p class="lead text-center" data-gui="copyright"></p> <div class="my-2 my-lg-0 text-center"><a class="btn btn-secondary" target="_blank" href="https://github.com/e5r/jquery-toad" role="button" title="@e5r/jquery-toad"><i class="fab fa-github"></i></a> <a class="btn btn-info" target="_blank" href="https://erlimar.wordpress.com" role="button" title="erlimar.wordpress.com"><i class="fab fa-wordpress-simple"></i></a> <a class="btn btn-primary" target="_blank" href="https://twitter.com/erlimar" role="button" title="@erlimar"><i class="fab fa-twitter"></i></a> <a class="btn btn-danger" target="_blank" href="https://www.youtube.com/channel/UC6zPtVBfcAdkzq7-dpSlhdw" role="button" title="E5R Development Team"><i class="fab fa-youtube"></i></a>  </div> </div> </footer> <script src="https://unpkg.com/jquery@3.3.1/dist/jquery.js"></script> <script src="https://unpkg.com/bootstrap@4.1.2/dist/js/bootstrap.js"></script> <script src="https://unpkg.com/highlightjs@9.10.0/highlight.pack.js"></script> <script src="lib/jquery-toad.js"></script> <script src="app/components/code-block-component.js"></script> <script src="app/components/copyright-component.js"></script> <script src="app/components/demo-component.js"></script> <script src="app/controllers/main-controller.js"></script> </body> </html>