monte.js

1. Dependências de desenvolvimento
2. Instalação
3. Adicionando dependências de desenvolvimento
4. Adicionando dependências ao projeto
5. Gulp: buildando o projeto (diretório /assets)
6. Sistema
   1. Styles
      1. Alguns estilos desenvolvidos
   2. Scripts
      1. Utils
         1. Tradução de mensagens
         2. Mensagens no console
         3. Caixa de diálogo (modal)
      2. Pages
      3. Components
         1. Requisições HTTP ao October
      4. Forms
      5. Rotas front-end
         1. Requisição de páginas (rotas)
   3. Templates
      1. Criando templates
      2. Renderizando templates
         1. Resetando conteúdo da div
         2. Preservando conteúdo da div
         3. Funções auxiliares
      3. Elements
         1. Alguns elements desenvolvidos
         2. Criando um element
         3. Registrando um element
         4. Renderizando um element
      4. Forms
   4. Exemplo de criação de rota, requisição, renderização e chamada ajax

Dependências de desenvolvimento

• Node.js

• npm

• Bower

npm install -g bower

• Handlebars

npm install -g handlebars

• Gulp

npm install -g gulp

Instalação

npm install

Adicionando dependências de desenvolvimento

npm install --save-dev **plugin**

ou

bower install --save-dev **plugin**

Adicionando dependências ao projeto

npm install --save **plugin**

ou

bower install --save **plugin**

Gulp: buildando o projeto (diretório /public)

O diretório /public é gerado dinâmicamente, utilizando a tecnologia Gulp. Somente esse diretório é acessível ao usuário e seus arquivos são o resultado da build do projeto.

Para desenvolvimento utilize o comando npm start. Como alternativa você também pode utilizar o comando gulp watch.

Para gerar uma versão buildada do projeto utilize o comando npm run build.

Sistema

Esse projeto serve como aplicação front-end ao OctoberCMS.

Utiliza-se o padrão de "single page application", ou seja, uma única página manipulada por javascript.

Assim sendo uma aplicação front-end, requisições HTTP ocorrem via Ajax (Request) aos Components desenvolvidos no OctoberCMS.

Alguns aspectos deste projeto:

Styles

Frameworks utilizados no desenvolvimento do estilo:

• Bootstrap 3, para estruturar a responsividade da aplicação;
• Material Design for Bootstrap, que transforma a interface do Bootstrap em Material design.

O estilo do projeto foi desenvolvido utilizando o pré-processador Sass, que otimiza e acelera o desenvolvimento de css.

Alguns estilos desenvolvidos

Algumas classes foram desenvolvidas no intuito de agilizar ainda mais o processo de montagem de layout:

• center-force: centraliza div na tela;
• center-force-remove-p: centraliza div na tela e remove paddings laterais;
• center-force-mobile: centraliza div na tela somente se max-width < 992px;
• center-force-mobile-remove-p: centraliza div na tela somente se max-width < 992px e remove paddings laterais;
• right: seta float para right;
• remove-margins: remove margins laterais;
• remove-paddings: remove paddings laterais;
• remove-mp: remove margins e paddings laterais;
• remove-mt: remove margin-top;
• remove-mb: remove margin-bottom;
• remove-p-l: remove apenas padding-left;
• remove-p-r: remove apenas padding-right;

Exemplo:

<div class="col-md-8">
    <div class="col-md-6 center-force">
        This div is centralized
    </div>
</div>
<div class="col-md-4 remove-mp">
    This div has no margin and padding left/right.
</div>

Scripts

Desenvolvido com jQuery para manipulação de documentos HTML, manipulação de eventos, animação e Ajax. A fim de desenvolvimento, os arquivos do diretório /scripts devem ser buildados para terem efeito no diretório /public.

Tradução de mensagens

Toda e qualquer mensagem que seja renderizada ao usuário deve passar pela função translate(string msg).

Exemplo:

let msg = translate( 'Aqui minha mensagem em pt-br' ); // <-- return string translated

Mensagens no console

Para mostrar mensagens no console do navegador deve-se utilizar a função consoleLog(string msg).

Para mostrar mensagens de erro utilize a função consoleError(string msg).

Exemplo:

consoleLog( translate('Aqui minha mensagem no console') );
consoleError( translate('Aqui minha mensagem de erro no console') );

*Caso o cookie debug esteja setado como false as mensagens não serão exibidas.

Caixa de diálogo (modal)

Foram desenvolvidos métodos baseados em Bootstrap3 Dialog que facilitam a criação de caixas de diálogo. São elas: confirmDialog(json data) e modalDialog(json data). Não é necessário passar as strings pelo método translate() pois essa transformação já ocorre internamente nos métodos desenvolvidos.

Exemplos:

confirmDialog({
    title: 'Confirmação',
    message: 'Você realmente deseja confirmar essa ação?',
    button: { // <-- main button
        icon: 'fa fa-check',
        label: 'Confirmar',
        action: (dialogItself) => {
            // code
            dialogItself.close(); // <-- close modal
        }
    }
});

modalDialog({
    headerBackground: 'rgb(0,95,108)',
    title: 'Modal',
    message: '<h2>html content</h2>',
    onshown: () => {
        // call in show modal
        // code
    },
    button: { // <-- main button
        icon: 'fa fa-edit',
        label: 'Ok modal',
        cssClass: 'btn-success',
        action: (dialogItself) => {
            //code
            dialogItself.close(); // <-- close modal
        }
    }
});

Requisições HTTP ao OctoberCMS

Chamada ajax

Para fazer uma requisição Ajax ao OctoberCMS utilize a função createRequest(string component, json data). Essa função retorna um elemento $.request, ou seja, o seu resultado é acessível através do método .done( (response) => { ... } );, onde response é o json de resposta do component do OctoberCMS.

Exemplo:

createRequest('myComponent', { name: 'name' }).done( (response) => {
    consoleLog(response); // <-- log json result
});

Rotas front-end

O sistema de rotas do front-end utiliza Routie.js para gerenciar as requisições ao front-end. Routie captura e modifica o histórico do navegador, utilizando hash #.

As rotas estão definidas no arquivo /scripts/core/routes.js.

Exemplo:

routie({
    '/home': () => {
        // code
    },

    '*': () => { // <-- default route
        routie('/home'); // <-- go to 'home' route
    }
});

Assim, para o usuário navegar entre as rotas, basta criar um link apontando para #/nomeDaRota.

Exemplo:

<a href="#/home"> Go to home </a>

Requisição de páginas (rotas)

O projeto trabalha com requisição de arquivos javascript por demanda, ou seja, cada arquivo é carregado somente se for requisitado. Assim, para cada página existe um arquivo .js em /scripts/pages/ contendo seus métodos específicos. O método getPage(string page) cria uma Promise que requisita o arquivo javascript correspondente, ou seja, retorna um método .then( () => { ... } ) quando o arquivo for carregado.

Exemplo:

getPage('home').then( () => {
   // file '/scripts/pages/_home.js' is loaded
});

Templates

Os templates são pré-compilados utilizando a tecnologia Handlebars. Os arquivos .hbs estão no diretório /templates.

O Handlebars é responsável por transformar cada arquivo de template em um .js, e o salva em /public/assets/js/templates.

Criando templates

Para criar um template siga os passos:

• crie um arquivo .hbs em /templates. Exemplo: home.hbs
• edite home.hbs e escreva html normalmente, inserindo o objeto que deverá renderizar no template. Para maiores informações sobre a sintaxe de Handlebars, clique aqui.
• gulp templates (se quiser buildar separadamente)

Exemplo:

<div class="col-md-10 center-force">
    <h1>{{title}}</h1>
</div>

Renderizando templates

Cada chamada de renderização de templates trabalha com a tecnologia Promise para requisitar um template para a página. Sendo assim, toda e qualquer lógica referente ao template deve ser escrito dentro do método .then( () => { ... }), que recebe uma função sem parâmetros. Isso garante que os códigos escritos dentro dessa função sejam executados somente após a renderização do template no html.

O objeto json data é o que será integrado com o template Handlebars. Esse parâmetro é opcional.

Resetando conteúdo da div

Para requisitar um template e renderizá-lo, substituindo o valor atual de HTML da div associada, utilize a função htmlDiv($(element) $div, string template, json data).

Exemplo:

let $div = $('#root');
htmlDiv($div, 'home', {title:  translate('Título do meu template')}).then( () => {
    // template 'home.hbs' is render as new #root content
});

Preservando conteúdo da div

Para requisitar um template e renderizá-lo, preservando o valor HTML da div e adicionando o novo conteúdo, utilize a função appendDiv($(element) $div, string template, json data).

Exemplo:

let $div = $('#root');
appendDiv($div, 'home', {title:  translate('Título do meu template')}).then( () => {
    // template 'home.hbs' is added in #root content
});

Funções auxiliares

• clearDiv(array $divs) Limpa o conteúdo HTML de uma div. Espera como parâmetro um array de elementos jQuery.
• getTemplate(string template) Cria uma Promise que requisita o template associado e retorna uma função .then( (t) => { ... } ), onde t é a função Handlebars contendo o template pré-compilado.

Exemplo:

let json = {title:  translate('Título do meu template')};
getTemplate('home').then( (t) => {
    let $div = $('#root');
    $div.html( t(json) ); // <-- insert json data in template and print in div
});

Elements

Alguns elementos foram criados com o intuito de facilitar e agilizar o desenvolvimento do projeto. Cada element é um fragmento de html, disposto num arquivo .hbs no diretório /templates/elements/. Assim, para popular um element basta passar um objeto json com as opções disponíveis para cada fragmento.

Alguns elements desenvolvidos

input-text, input-email, input-password: {
    label: translate('Título'),
    id: 'id',
    name: 'name',
    hint: translate('Mensagem no rodapé do campo'),
    value: 'value',
    option: 'required'
}

button: {
    id: 'btn-login',
    class: 'success btn-submit', // <-- class 'btn-submit' to form submit button
    title: translate('Entrar')
}

Criando um element

Para criar um element crie um arquivo .hbs em /templates/elements/:

Exemplo: /templates/elements/button.hbs

<button type="button"
        id="{{ id }}"
        class="btn btn-{{ class }}">

    {{ title }}

</button>

Registrando um element

Para que um element seja chamado dentro de um template, conforme a documentação do Handlebars, deve ser registrado como uma Partial. Isso deve ser feito no método registerPartials() em /scripts/core/_templates.js.

Exemplo:

const registerPartials = () => {
    Handlebars.registerPartial('button', Chip.templates['button']);
};

Renderizando um element

Um element é renderizado dentro de um template, ou seja, existe uma "tag" do Handlebars específica para chamar Partials: {{> element-name }}. Uma Partial não herda os atributos json do template pai, mas é possível passar um atributo do pai para a partial.

let data = {
    title: translate('Título do meu template home'),
    btn: {
        id: 'btn-reset-password',
        class: 'success btn-submit',
        title: translate('Alterar senha e entrar')
    }
};

let $div = $('#root');
htmlDiv($div, 'home', data).then( () => { // <-- render 'home' template
    // 'template' rendered
});

/templates/home.hbs:

<div class="col-md-12 remove-mp">
    <h1>{{title}}</h1>

    <div class="col-md-12 text-center"> <!-- button center -->
        {{> button btn }} <!-- partial button receive object 'btn' -->
    </div>

</div>

Forms

Para facilitar a manutenção de formulários, o template (.hbs) dos mesmos devem ser desenvolvidos separadamente no diretório /templates/forms. Para requisitar um formulário utilize o método getForms(string form).then( (t) => { ... }), que retorna uma Promise contendo a função t Handlebars de criação do modelo de layout. Assim, basta passar os dados json para retornar o html do layout.

Exemplo:

const json = {item: 'myitem'};
getForms('myform').then( (t) => { // <-- load myform
    let html = t(json); // <-- html content
});

Exemplo de criação de rota, requisição, renderização e chamada ajax

Exemplo de criação de rota e requisição:

routie({

    '/home': () => { // <-- create route 'home'
        refreshToken().then( () => { // <-- refresh access_token
           getPage('home').then( () => { // <-- load page 'home'
               renderHome(); // <-- call method in '/scripts/pages/home.js'
           });
        });
    }

});

Exemplo de renderização e chamada ajax (/scripts/pages/home.js):

const renderHome = () => {
    let $div = $('#root'); // <-- div where content will render
    htmlDiv($div, 'home', {
        title: translate('Título do meu template home')
    }).then( () => {
        // all ready, template 'home.hbs' is render as new #root content

        refreshToken().then( () => { // <-- refresh access_token
            createAjax('GET', 'url', {data: data}, {header: header}).done( (result) => {
                consoleLog(result); // <-- ajax result
            });
        });
    });
};