• Sumario
• ⚙️ Setup
  • Como instalar as dependencias informadas de cada um?
• 🤝 Contribuir
  • 🤝 Boas práticas
    • 🔎 Buscar atualizações
    • 📦 Atualizar código local com as alterações buscadas
  • Como saber meu branch atual?
• 🧪 Guia de comandos
• 🧩 Estrutura de projeto
• 🖥️ Padrão para criação de views
• 💻 Criando views
  • 🧠 Boas práticas - Views
  • Adicionando titulo a página
• 📦 Componentes
  • Modal
  • Modal com conteúdo
  • Modal com conteúdo e com actions
• Sidemenu
  • Como funciona ?
  • Como adicionar um link ao globals.sidemenu
• Custom Facades
• Custom Helpers
• Snippets
• Git Utilities
• TASK - Pendencias do projeto
  • Login e Registrar
  • Resolução de problema
  • Exibir informações do usuário
  • Ações administrativas
    • View de usuários
    • View de salas
    • View de cursos
  • Padrão nomear para receber os Dados
  • 🧠 Boas práticas
  • Criação da rota para tela de cadastro

1 - Clonar repositorio para maquina local

git clone https://github.com/senaCrono/senacronogama.git

2 - Instalar as dependencias do projeto

Ao clonar o repositorio, não temos as dependencias "upadas" mas sim um arquivo que informa quais dependecias o projeto usa, nesse caso, temos uma stack(NodeJS & PHP). O Arquivo que informa quais dependencias estamos utilizando no projeto são:

package.json - NodeJS

composer.json - PHP Composer

1 - Composer

composer install

2 - NodeJS

npm install

[!INFORMATION] A abreviação de NPM em português é Gerenciador de pacotes do node ou nó, do inglês Node Package Manager

Após executar estes comandos você tera o suas dependencias instaladas.

3 - Copiar .env.example para .env

4 - Gerar APP_KEY com artisan

php artisan key:generate --ansi

Antes de começar a criar divisões do código branches você deve verificar se há alterações no código dev e novos branches e atualizar seu repositorio local.

git fetch origin

Origin é o remoto principal do projeto https://github.com/SenaCrono/senacronogama.git

git pull

Antes de contrubuir siga os passos abaixo:

1 - Criação de branch para cada parte que for alterada do código

# criar um branch e mudar para o mesmo
git checkout -b nome_do_recurso

O parametro -b é para informar qual é o nome do branch que você deseja criar, e em seguida o checkout mudara para o mesmo.

Para saber em qual branch você esta operando:

git branch

O item que retornar marcado com um * e na cor verde é o atual.

2 - Confirmar alterações

# adicionar todos os arquivos alterados para o repositorio local
git add *
# confirmar alterações
git commit -m 'Titulo que descreve a função' -m 'Mensagem completa que descreve todas as alterações'
# enviar para o repositorio e aguardar uma avaliação
git push

O comando npm run dev inicia um dev server do asset builder Vite. veja mais

O comando php artisan serve inicia um dev server do projeto, servindo como base a url / a mesma coisa de 127.0.0.1:8000/ e caso fosse um servidor estático 127.0.0.1:8000/public/

Deve se manter a estrutura original do projeto e qualquer criação de nova pasta na source tree deve ser planejada antes.

Qualquer novo recurso que exija uma alteração na estrutura também deve ser planejada e avisada.

Siga os passos abaixo para criar views dentro do padrão do projeto resouces/views

O nome deve ser resumido e descritivo, um exemplo bem simples:

users.blade.php;

Organização com pastas, seguindo o padrão:

users / list.blade.php;

Seguindo esses padrões podemos desenvolver um projeto onde todos já sabem o que devem fazer apenas dependendo deste documento

[!WARNING] > Seguir esses padrões não é obrigatorio, mas devemos manter um padrão de organização para que todos tenham o conhecimento do projeto

Para criar uma view, temos o padrão base abaixo:

  @extends('components.layout.padrao')
    @section('content')
        @include('components.home.index')
   @endsection

Esse padrão servirá para você poder incluir partes básicas da página sem precisar repetir muitas linhas, essas partes são elas: sidemenu, navbar/header, layout responsivo. Essa base ajudará a manter as páginas consistentes, diminuindo problemas ao mudar o padrão de design.

extends - Esta extenção serve para usar um padrao de layout components/layout/padrao.blade.php

section - Onde colocara o conteudo dentro de uma Seção

content Serve para posicionar o conteudo dentro da sua Seção section('content') > resources/views/components/users/index.blade.php

include - Incluindo algo dentro da sua seção como componentes etc

endsection - Fecha sua Seção

  @include('components.home.index')
  // Para deixar seu codigo mais limpo voce usa o include puxando os componentes da sua pagina toda usando um só comando

  @vite ('resources/js/views/welcome.js')
  // Caso queira carregar um arquivo estatico de CSS e JavaScript esse comando ajudara a puxar os arquivos rapidamente

Por padrão observe o codigo a cima a pagina nao vira com um titulo padrão

Para fazer isso voce pode seguir o exemplo abaixo

    @section ('tittle')

Modal base foi implementado na plataforma e pode ser usado em qualquer página Basta apenas utilizar o elemento:

<x-modal> </x-modal>

Esse elemento criará todos as divs necessarias para criar um backdrop e a caixa de dialogo do modal

Podemos também adicionar um id nesse modal, para identifica-lo mais tarde com ações. Essas propriedades lembram bastante o bootstrap, o funcionamento é parecido, mas com codigos nativos.

<x-modal id="my-modal-info"> </x-modal>

E podemos abrir o modal com:

<!-- BOTÃO PARA ABRIR O MODAL -->
<button data-open-modal="#my-modal-info"></button>

E fechar com:

<button data-modal-recuse="#my-modal-info"></button>

data-open-modal será mapeado ao carregar a página, então garanta que o app.js esta incluido, poís é ele que fara esta função. A mesma coisa serve para data-modal-recuse

Para criar um modal com um body, podemos fazer o seguinte:

<x-modal id="my-modal-info">
    <!-- CONTÉUDO -->
    <div class="flex flex-col"></div>
</x-modal>

Você pode definir o conteúdo da forma como quiser com divs, forms ou qualquer outra coisa, o modal é bem diversificado para aceitar childrens(parents nodes internos)

Para criar um modal com um body e bottom actions(utilizar a parte de baixo do modal), podemos seguir:

<x-modal id="my-modal-info">
    <!-- CONTÉUDO -->
    <div class="flex flex-col"></div>

    @slot('actions')
    <button class="p-3 border rounded">Enviar</button>
    <button class="p-3 border rounded" data-modal-recuse="#my-modal-info">
        Close
    </button>
    @endslot
</x-modal>

Definimos um modal que tem um slot que seria a mesma coisa que uma div, essa que aponta para o slot actions do modal, ou seja, é para criarmos um conteudo dentro de uma parte desejada de um componente. Nesse mesmo modal definimos um botão de close que aponta para o modal.

O Sidemenu(menu lateral) define as páginas disponiveis para um usuário comum e condicional para um usuário com permissões' elevadas

De forma básica os links são incluidos manualmente no Sidemenu através do arquivo globals.sidemenu, por enquanto não há nenhuma condição para não mostrar páginas de permissões elevadas, ou seja, todas estão sendo exibidas

Para adicionar um novo link(referenciada a uma nova página) você pode editar o arquivo globals.sidemenu.

Observe o cógido abaixo:

<x-sidemenu.option
    link="{{route('index')}}"
    option="Tela inicial"
    active="{{Matcher::match('index')}}"
>
    @slot('icon') 🖥️ @endslot
</x-sidemenu.option>

Veja que x-sidemenu.option criará uma nova opção para a sidemenu como se fosse uma div e de fato x-sidemenu.option por trás "das caras" é uma div que contém pre-definições de classes do tailwindcss para poder ecomizar linhas no código final.

link - Qual é a ancora de referencia ou o link da página que o usuário será redirecionado ao clicar

option - Nome da opção que aparecera no menu

active - Verifica se a a rota atual for igual a que esta selecionada ao menu, por exemplo:

Se o link for igual a /home e der match com a rota nomeada de home, o item do menu ficara marcado como ativo.

icon - O slot icon serve para encaixar um icone ao menu e quando o mesmo estiver minimizado, apenas o icone será mostrado.

web.php

Route::get('/home', [...])->name('home')

globals.sidemenu

<x-sidemenu.option
    link="{{route('home')}}"
    option="Tela inicial"
    active="{{Matcher::match('home')}}"
>
    @slot('icon') 🖥️ @endslot
</x-sidemenu.option>

A Facade Matcher faz exatamente o trabalho de verificar se a rota atual é exatamente a mesma que está selecionada no sidemenu.

Matcher - Class comparadora de URL - página O matcher é usado para verificar se a url atual corresponde ao item informado como parametro da função match

Matcher::match('my-route-name')

my-route-name - Alguma rota definida em seu web.php e a rota que deseja fazer um 'match' com a url atual, então:

Se a URL /minha-pagina for igual a web.php -> Route::<method>()->name('my-route-name'), match() retornará true caso não 'tenha dado match', false.

match - Função comparadora de URL - página

• Snippet para base de página indice

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />

        <title>Laravel</title>

        <!-- Fonts -->
        <link rel="preconnect" href="https://fonts.bunny.net" />
        <link
            href="https://fonts.bunny.net/css?family=figtree:400,600&display=swap"
            rel="stylesheet"
        />

        @vite("resources/css/app.css")
    </head>
    <!-- Styles -->

    <body style="background-color: white">
        <div class="flex flex-row w-full">
            @include('globals.sidemenu')
            <div class="mx-3 w-full">
                <div class="flex flex-col mt-3 gap-3">
                    @include('globals.navbar')
                </div>
            </div>
        </div>
    </body>
</html>

• Botão com tooltip

<div class="group relative">
    <span
        class="group-hover:visible invisible absolute bg-white shadow ps-3 px-3 border rounded left-0 z-50 -translate-y-5"
    >
        My tooltip
    </span>
    <button
        class="border p-3 rounded-lg hover:bg-slate-100 transition-all active:bg-slate-300"
    >
        Get started
    </button>
</div>

• git add *

  Prepara todas suas alterações locais para subi-lás no código master

• git commit

• git branch (nome_do_branch)

  Define a "Fatia" do código em que você está trabalhando

• git push

  "Empurra" as alterações para o código principal #Após isso atentar-se ao Pull Request no GITHUB

• git branch (nome_do_branch)

  Define a "Fatia" do código em que você está trabalhando

• git fetch

  Atualiza todas as alterações feitas por outros colaboradores no código

• git pull

  Puxa todas as atualizações disponíveis no branch master

• git merge

  Faz a integração dos branchs(fatias) entre elas

    git merge (nome_do_branch)

• - Criação da view login e com Controller

Para a tela de login deve-se ter os campos para digitar o numero de registro do professor ou E-Mail e senha, com um checkbox para esconder ou exibir a senha, após isso fazer o botão que será responsável por enviar o formulario.

• - Criação da view register e usando o mesmo Controller de login

Para a tela de registro deve-se ter campos: Nome de usuário, E-Mail/Numero de registro, senha e repetir senha, após isso fazer o botão que será responsável por enviar o formulario.

Para questões de lógica, segue:

• O primeiro usuario cadastrado na plataforma sempre será o responsável por configura-la após o processo de cadastro ou seja:

No banco de dados para as propriedades de usuário podemos ter um campo do tipo Enum que determina se esse usuário é um usuário padrão ou administrador.

CREATE TABLE users(..., ...., ...., AccountType ENUM('default', 'admin'))

Após o primeiro usuário ser cadastrado o mesmo será responsavel por aceitar o pedido de cadastro dos demais, então podemos determinar se o usuário default tem permissão para usar a plataforma pós-cadastro:

CREATE TABLE users(..., ..., ..., AccountType ENUM('default', 'admin'), AccountActivated BOOL)

Onde AccountActivated será alterada para true quando a requisição de cadastro for aceita pelo Administrador, então precisamos filtrar telas onde serão exibidos os usuários cadastrados e outra com uma lista de usuários pendentes. Uma feature que pode ser incluida é a possibilidade do próprio Administrador cadastrar um usuário manualmente e passando a opção de AccountActivated para true.

Feito os passos anteriores, agora o estado da página de login mudará, pois um novo usuário foi criado.

# Exemplo de busca
SELECT * FROM users

$varusers = User::all();
if (sizeof($varusers) == 0) {
    // mostrar apenas a tela de cadastro
    return;
}

// mostrar a página de cadastro e login

Isso é um exemplo de código usado em um AuthController que seria responsável por lidar com as autenticações na plataforma.

Para poder fazer um AuthController e um sistema de autenticação, você pode buscar na documentação do Laravel de como autenticar um usuário usando o Model User e extendendo a class Authenticable. Veja mais apartir da seção retornando um usuário autenticado.

Todo e qualquer sistema de autenticação deve dar a opção para o usuário trocar de senha com um token temporario gerado ao clicar no campo esqueci minha senha. Por isso é importante a plataforma ter algum tipo de verificação para validar se realmente é o usuário que está tentando fazer login, como uma palavra chave para recuperar a senha ou usando o token citado anteriormente.

Seguindo a lógica de como recuperar uma senha:

1 - O usuário clica em esqueci minha senha e é redirecionado para uma página onde terá uma input para digitar o código enviado ao E-Mail do mesmo ou em um sistema interno de E-Mail da plataforma onde um administrador seria responsavel por fazer a recupreção da conta.

2 - Ao digitar o código gerado e o mesmo sendo válido(função de um Controller para válidar se o código fornecido é o mesmo que foi gerado pela plataforma) o usuário será novamente redirecionado, mas agora para a página para criar uma nova senha.

Para contornar o gigante caminho citado nas seções anteriores, podemos fazer uma página referente ao usuário, ou seja, quando ele clicar em esqueci minha senha, seria redirecionado para uma página onde mostraria algumas informações básicas de login do própio usuário, seria essas informações: dica de senha, ultima senha usada, palavra chave. Devemos dar ajuda para que o usuário possa lembrar de sua esquecida senha.

• - Criação da view de exibição do usuário(perfil) - O nome do Controller pode ser qualquer um desde que siga o padrão.
• - Modal ou página para dar a opção do usuário editar as informações ou fazer campos editáveis na propria página de exibição
• - Opcional - Popup/Modal de confirmação das alterações feitas e um botão de submeter-se

O responsável por fazer a página deve documentar os campos passados via POST, ou seja, apenas especificar os nomes atribuidos nas inputs.

• - Opção para o usuário deletar a conta

Todas as opções listadas devem apenas serem mostradas para usuários administradores, e o que determinará essa exibição é apenas um @if ou @auth no blade.

• - Opção para ver a informação do usuário, editar e deletar ou opções para ativar ou desativar a conta do mesmo.
• - Exibição do status da conta(se está autorizado a fazer login ou não: Login e registrar)

• - Opção de criar nova sala, editar ou deletar.

• - Opção de criar novo curso, editar ou deletar.

- [ ] - Exemplo:  name="nameroom"
  // Voce esta nomeando sua input que ira receber o dado quando for cadastrado

- [ ] - Use o mesmo padrão acima só que agora sera com rotas
- [ ] - Exemplo: Route::view('/create', 'users/create')->name('users.register');
     // Nomeando essa rota você ira puxar esse nome no seu href
- [ ] - Exemplo: href="{{route('users.register')}}
     // Aqui voce estara puxando sua rota para exibição da tela de cadastro