kdymsolucoes/laravel_boilerplate
Template padrão para início de projetos com Laravel
Downloads
Stars
Version
Laravel Boilerplate
Biblioteca para gerar um template padrão de um painel administrativo baseado em AdminLTE 3. Já vem com algumas funções pré-definidas, como: controle de usuários, campos com máscara, etc.
Índice
Dependências
Instalação
$ composer require agenciamaior/laravel_boilerplate
Após baixar o pacote via Composer, você deve rodar o comando abaixo para instalar a biblioteca:
$ php artisan boiler:install
AVISO: A instalação da biblioteca vai substituir VÁRIOS arquivos dentro das pastas do seu projeto Laravel. Recomenda-se executar esse comando numa instalação limpa do Laravel.
A instalação pode levar algum tempo, já que vários pacotes NPM serão baixados para seu projeto.
Essa biblioteca não instala nem configura nenhum banco de dados no seu projeto. Você deve fazê-lo manualmente como faria com qualquer outro projeto recém-criado do Laravel.
A instalação roda automaticamente o comando php artisan make:auth para gerar um sistema de Autenticação com algumas migrations já pré-configuradas para uma tabela de usuários, modificada para adicionar alguns campos a mais dos que já vêm na instalação padrão do Laravel.
Após a instalação, você pode executar as migrations através do comando:
$ php artisan migrate
A instalação copia vários arquivos de estilos e scripts para dentro da pasta resources. O arquivo de estilo se encontra em resources/sass/_boilerplate.scss e você deve importa-lo manualmente dentro do arquivo resources/sass/app.scss:
@import 'boilerplate';
Depois de importado, você deve compilar os scripts através do comando:
$ npm run dev
Ou, se você preferir que a compilação seja feita automaticamente toda vez que um asset for modificado, execute e deixe rodando o comando:
$ npm run watch
No seu arquivo de rotas routes/web.php, aponte o endereço raiz para a Home:
Antes:
Route::get('/', function() {
return view('welcome');
});
Depois:
Route::get('/', 'HomeController@index')->name('home');
\AgenciaMaior\LaravelBoilerplate\LaravelBoilerplateServiceProvider::routes();
A instalação adiciona automaticamente suas próprias rotas. Na seção Rotas dentro desse documento, você pode saber como sobrescrever essas rotas.
Recursos disponíveis
Formulários
Todos os formulários dentro das views utilizam a biblioteca BootstrapForms. Para ler a documentação completa dessa biblioteca, clique aqui.
Login
Ao entrar pela primeira vez, o sistema vai pesquisar na tabela de usuários se ela está vazia. Se estiver, você será apresentado a uma tela para cadastrar o primeiro usuário do tipo Administrador.
Esse formulário já conta com uma validação via javascript através da biblioteca jQuery Validation.
Se houverem usuários cadastrados na tabela, você será redirecionado para a tela de login normalmente.
O layout dessa página pode ser encontrado e modificado livremente em /resources/views/auth/login.blade.php.
Perfis de usuário
Essa biblioteca utiliza constantes numéricas para representar os perfis de usuário, são esses:
- Administrador => 0
- Usuário comum => 1
Essas constantes são definidas dentro do model app/User.php:
//...
const ROLE_ADMIN = 0;
const ROLE_COMMON = 1;
public static function roles() {
return [
self::ROLE_ADMIN => 'Administrador',
self::ROLE_COMMON => 'Comum',
];
}
public function getRoleStringAttribute() {
return self::roles()[$this->role];
}
//...
Você pode adicionar novos perfis ou alterar os existentes se preferir. Essas constantes são salvas num campo role do tipo INTEGER dentro da tabela users (gerado pela migration da instalação).
A função getRoleStringAttribute é um Accessor para se obter a representação em formato texto do perfil do usuário. Para saber mais sobre Accessors no Laravel, consulte a documentação.
Exemplo de utilização das constantes:
$user->role = \App\User::ROLE_ADMIN;
// Equivalente a:
$user->role = 0;
Exemplo de utilização do Acessor:
<p><b>Perfil do Usuário:</b> {{ $user->role_string }}</p>
<!-- Equivalente a: -->
<p><b>Perfil do Usuário:</b> Administrador</p>
Template
Todos os templates se encontram dentro de /resources/views/boilerplate. Dentro desse diretório, existe um template master onde podem ser adicionadas as meta tags do projeto, assim como alterar o título e outros atributos globais da página.
O template raw é usado para telas de login e outras páginas com o mesmo formato.
As demais páginas vão herdar do template page.
Para alterar o menu, acesse a view main-menu dentro desse diretório. Na seção Menu, você pode ver mais detalhes sobre como adicionar itens do menu.
Estrutura da view resources/views/home.blade.php, seguindo o template da biblioteca:
@extends('boilerplate.page')
@section('css')
{{-- Seus estilos específicos de página aqui --}}
@endsection
@section('header-title')
<h1>
Bem-vindo
</h1>
@stop
@section('header-breadcrumbs')
<li class="breadcrumb-item"><a href="/">Home</a></li>
<li class="breadcrumb-item active">Dashboard</li>
@endsection
@section('content')
{{-- Seu conteúdo aqui --}}
@stop
@section('js')
{{-- Seus scripts específicos de página aqui --}}
@endsection
Estilos e Scripts
Os arquivos de estilo se encontram dentro de resources/sass/_boilerplate.scss. Como mencionado na instalação, esse arquivo não é importado automaticamente para dentro de resources/sass/app.scss para não causar conflitos com os estilos atuais do seu projeto. Para importa-lo, utilize no arquivo app.scss o comando:
@import 'boilerplate';
Você vai precisar resolver manualmente qualquer conflito de estilos que surgir depois dessa importação.
Ao contrário do arquivo de estilos, o arquivo de scripts resources/js/boilerplate.js já é adicionado automaticamente ao final do arquivo resources/js/bootstrap.js.
Assim, você pode definir seus próprios estilos e scripts globais separadamente dos fornecidos pela biblioteca, mas nada impede que você possa modificar esses arquivos, se assim desejar.
Os estilos e scripts específicos por página podem ser colocados em suas respectivas @section dentro das views.
Menu
O template do menu se encontra em resources/boilerplate/main-menu.blade.php. No começo desse arquivo, duas variáveis são geradas para identificar qual o Controller atual e qual a Action atual, com isso, é possível tornar o menu ativo quando a página estiver aberta no seu respectivo item de menu.
Exemplo de um novo item de menu:
@php
$class = '';
if ($controller == 'AlgumController') {
$class = 'active';
}
@endphp
<li class="nav-item">
<a href="link/do/menu" class="nav-link {{ $class }}">
<i class="nav-icon fa fa-icone"></i>
<p>Novo Link</p>
</a>
</li>
A biblioteca utiliza os ícones do FontAwesome, mas você pode utilizar qualquer outra biblioteca de ícones que desejar.
Excemplo de um novo grupo com dois itens de menu:
@php
$class = '';
if ($controller == 'AlgumController') {
$class = 'menu-open';
}
@endphp
<li class="nav-item has-treeview {{ $class }}">
<a href="#" class="nav-link">
<i class="nav-icon fa fa-icone"></i>
<p>Grupo <i class="fa fa-angle-left right"></i></p>
</a>
<ul class="nav nav-treeview">
@php
$class = '';
if ($controller == 'AlgumController' && $action == 'algumaAction') {
$class = 'active';
}
@endphp
<li class="nav-item">
<a href="link/do/menu" class="nav-link {{ $class }}">
<i class="fa fa-icone nav-icon"></i>
<p>Item 1</p>
</a>
</li>
@php
$class = '';
if ($controller == 'OutroController') {
$class = 'active';
}
@endphp
<li class="nav-item">
<a href="link/do/menu" class="nav-link {{ $class }}">
<i class="fa fa-icone nav-icon"></i>
<p>Item 2</p>
</a>
</li>
</ul>
</li>
Todas as outras opções de menu podem ser visualizadas na página oficial da biblioteca AdminLTE 3.
ACLs
A instalação cria automaticamente uma Policy para o Model de Usuários em app/Policies/UserPolicy.php, que já é importada automaticamente pra dentro do arquivo app/Providers/AuthServiceProvider.php. As demais Policies devem ser criadas e importadas manualmente. Para saber mais sobre Policies, consulte a documentação do Laravel.
Uma diretiva padrão para permitir que o usuário administrador tenha acesso a qualquer coisa também já é adicionada ao AuthServiceProvider.php:
// ...
class AuthServiceProvider extends ServiceProvider
{
// ...
public function boot()
{
$this->registerPolicies();
Gate::before(function ($user) {
if ($user->role == User::ROLE_ADMIN) {
return true;
}
});
// ...
}
}
Exemplos de uso das Policies
@can('create', \App\User::class)
<a href="{{ route('users.create') }}" class="btn btn-primary"><i class="fa fa-plus"></i> Novo Usuário</a>
@endcan
@foreach($users as $u)
@can('edit', $u)
<a href="{{ route('users.edit', ['user' => $u]) }}" class="btn btn-default btn-sm"><i class="fa fa-pencil-alt"></i> Editar</a>
@endcan
@endforeach
Usuários
A biblioteca gera um CRUD simples de Usuários. Suas views podem ser visualizadas ou modificadas em resources/views/users e seu respectivo controller em app/Http/Controllers/UsersController.php.
A lista de usuários utiliza o plugin jQuery DataTables.
Essa área também conta com a função de bloquear/desbloquear os usuários.
Por padrão, você não pode bloquear ou excluir o seu próprio usuário nessa lista. Esse comportamento pode ser alterado dentro dessa mesma view.
Perfil
A biblioteca tem uma página de Perfil, onde você pode alterar sua senha ou enviar uma foto de avatar. Se nenhuma foto for enviada, será usado um placeholder com as primeiras letras do seu nome e sobrenome. Esse comportamento pode ser alterado no Accessor getAvatarAttribute() dentro do model app/User.php.
Rotas
A instalação vai adicionar, ao final do arquivo routes/web.php, o seguinte comando:
\AgenciaMaior\LaravelBoilerplate\LaravelBoilerplateServiceProvider::routes();
Que consiste das seguintes rotas:
Route::group(['prefix' => '/users'], function () {
Route::post('/first-user', 'UsersController@storeFirstUser')->name('users.first-user');
Route::get('/profile', 'UsersController@profile')->name('users.profile');
Route::post('/profile', 'UsersController@updateProfile')->name('users.save-profile');
Route::post('/check-email', 'UsersController@checkEmail')->name('users.check-email');
Route::post('/check-profile-email', 'UsersController@checkProfileEmail')->name('users.check-profile-email');
Route::post('/check-profile-password', 'UsersController@checkProfilePassword')->name('users.check-profile-password');
Route::get('/block/{user}', 'UsersController@block')->name('users.block');
Route::get('/unblock/{user}', 'UsersController@unblock')->name('users.unblock');
});
Route::resource('/users', 'UsersController');
Qualquer uma dessas rotas pode ser sobrescrita, contanto que sejam definidas antes do comando acima.
UI
Máscaras
As máscaras utilizam as bibliotecas jQuery MaskPlugin e MaskMoney.
Para utilizar essas máscaras, adicione a respectiva classe ao campo:
- .cpf-mask - CPF (000.000.000-00)
- .cnpj-mask - CNPJ (00.000.000/0000-00)
- .cpf-cnpj-mask - CPF ou CNPJ no mesmo campo, muda a medida que você vai digitando
- .tel-ddd-mask - Telefone com DDD, aceita com ou sem o dígito 9 ((00) 00000000 ou (00) 900000000)
- .cep-mask - CEP (00000-000)
- .time-mask - Horas, formato horas:minutos (00:00)
- .date-mask - Data, formato dia/mês/ano (99/99/9999)
- .money-mask - Dinheiro (R$ 999.999,99)
- .number-mask - Número com casas decimais (999.999,99)
- .percent-mask - Porcentagem (999,99%)
Você pode ver um exemplo de utilização das máscaras nesse link.
A configuração das máscaras pode ser alterada em resources/js/boilerplate.js.
Datepicker
Adicione a classe .datepicker a um campo para utilizar o Datepicker da biblioteca jQueryUI.
Obs.: A classe .date-mask pode ser usada em conjunto com o Datepicker.
Você pode ver um exemplo de utilização do Datepicker nesse link.
A configuração do Datepicker pode ser alterada em resources/js/boilerplate.js.
Select2
Adicione a classe .select-2 a um campo do tipo Select para utilizar o Select2.
Você pode ver um exemplo de utilização do Select nesse link.
A configuração do Select2 pode ser alterada em resources/js/boilerplate.js.
Editor
Acidione a classe .editor a um campo do tipo TextArea para utilizar o Summernote.
Você pode ver um exemplo de utilização do Select nesse link.
A configuração do Editor pode ser alterada em resources/js/boilerplate.js.
Validações
Essa seção descreve algumas validações customizadas para serem utilizadas na biblioteca jQuery Validation.
Todas as validações podem ser alteradas em resources/js/boilerplate.js.
dateBR
Valida um campo para uma data válida no formato dd/mm/aaaa.
Exemplo:
{{ Form::bsText('data', 'Data', ['class' => 'datepicker date-mask']) }}
$('#id-do-formulario').validate({
rules: {
data: {
required: true,
dateBR: true,
},
}
});
Um exemplo de utilização desse validator pode ser visto nesse link.
period
Valida um campo de data em relação a outro campo de data para um período válido entre os dois.
Exemplo:
<div class="row">
<div class="col-md-6">
{{ Form::bsText('data_inicio', 'Data Início', ['class' => 'datepicker date-mask']) }}
</div>
<div class="col-md-6">
{{ Form::bsText('data_fim', 'Data Fim', ['class' => 'datepicker date-mask']) }}
</div>
</div>
$('#id-do-formulario').validate({
rules: {
data_inicio: {
required: true,
dateBR: true,
},
data_fim: {
required: true,
dateBR: true,
period: ['data_inicio'],
},
}
});
Um exemplo de utilização desse validator pode ser visto nesse link.
filesize
Valida um campo do tipo File para um tamanho de arquivo específico, em Megabytes.
Exemplo:
{{ Form::bsFile('arquivo', 'Arquivo <small>máx 2MB</small>') }}
$('#id-do-formulario').validate({
rules: {
arquivo: {
required: true,
extension: ['jpg', 'jpeg', 'png'],
filesize: 2,
},
}
});
cpf
Valida um campo contendo a máscara .cpf-mask para um CPF válido, utilizando a validação de módulo 11.
Exemplo:
{{ Form::bsText('cpf', 'CPF', ['class' => 'cpf-mask']) }}
$('#id-do-formulario').validate({
rules: {
cpf: {
required: true,
cpf: true,
},
}
});
cnpj
Valida um campo contendo a máscara .cnpj-mask para um CNPJ válido, utilizando a validação de módulo 11.
Exemplo:
{{ Form::bsText('cnpj', 'CNPJ', ['class' => 'cnpj-mask']) }}
$('#id-do-formulario').validate({
rules: {
cnpj: {
required: true,
cnpj: true,
},
}
});
cpfCnpj
Valida um campo contendo a máscara .cpf-cnpj-mask para um CPF/CNPJ válido, utilizando a validação de módulo 11.
Exemplo:
{{ Form::bsText('cpf_cnpj', 'CPF/CNPJ', ['class' => 'cpf-cnpj-mask']) }}
$('#id-do-formulario').validate({
rules: {
cpf_cnpj: {
required: true,
cpfCnpj: true,
},
}
});
Um exemplo de utilização desses validators pode ser visto nesse link.
editorRequired
Verifica se um campo contendo a máscara .editor está vazio ou não.
Exemplo:
{{ Form::bsTextarea('editor', 'Editor', ['class' => 'editor']) }}
$('#id-do-formulario').validate({
ignore: [], // Essa diretiva é obrigatória para esse validator funcionar
rules: {
editor: 'editorRequired',
}
});
Um exemplo de utilização desse validator pode ser visto nesse link.
Confirmable
Adicione a classe .confirmable a qualquer botão ou link para adicionar uma janela de confirmação a ele. Essa função é muito usada em botões de excluir.
Animação no submit do formulário
Por padrão, ao fazer o submit de um formulário, o botão de submit vai ficar desabilitado e o texto dentro dele será substituído por um spinner. Isso impede o usuário de clicar várias vezes no botão de submit.
Para desabilitar esse comportamento, adicione a classe .without-spinner à tag <form> da sua página.
Parsers
Dentro do arquivo app/Http/Controller/Controller.php, a instalação vai copiar duas funções para transformar datas e valores do tipo dinheiro.
Exemplo de utilização dentro de um Controller:
$date = '03/05/2019';
$newDate = $this->parseDate($date); // 2019-05-03
$price = 'R$ 300,00';
$newPrice = $this->parseCurrency($price); // 300
Estados Brasileiros
Dentro do arquivo app/Http/Controller/Controller.php, a instalação vai copiar um array com todos os estados brasileiros e suas respectivas siglas:
const ESTADOS_BRASILEIROS = [
'AC' => 'Acre',
'AL' => 'Alagoas',
'AP' => 'Amapá',
'AM' => 'Amazonas',
'BA' => 'Bahia',
'CE' => 'Ceará',
'DF' => 'Distrito Federal',
'ES' => 'Espírito Santo',
'GO' => 'Goiás',
'MA' => 'Maranhão',
'MT' => 'Mato Grosso',
'MS' => 'Mato Grosso do Sul',
'MG' => 'Minas Gerais',
'PA' => 'Pará',
'PB' => 'Paraíba',
'PR' => 'Paraná',
'PE' => 'Pernambuco',
'PI' => 'Piauí',
'RJ' => 'Rio de Janeiro',
'RN' => 'Rio Grande do Norte',
'RS' => 'Rio Grande do Sul',
'RO' => 'Rondônia',
'RR' => 'Roraima',
'SC' => 'Santa Catarina',
'SP' => 'São Paulo',
'SE' => 'Sergipe',
'TO' => 'Tocantins'
];
Exemplo de utilização num Select:
{{ Form::bsSelect('estados', 'Estados', \App\Http\Controller::ESTADOS_BRASILEIROS) }}
