monte.js
v1.0.1
Published
A easy litter framework with jquery that works plugins (pages, components and forms) and manager front routes.
Downloads
3
Maintainers
Readme
monte.js
- Dependências de desenvolvimento
- Instalação
- Adicionando dependências de desenvolvimento
- Adicionando dependências ao projeto
- Gulp: buildando o projeto (diretório
/assets
) - Sistema
Dependências de desenvolvimento
npm install -g bower
npm install -g handlebars
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 semax-width < 992px
;center-force-mobile-remove-p
: centraliza div na tela somente semax-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 escrevahtml
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) => { ... } )
, ondet
é 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
});
});
});
};