Forms é uma biblioteca uspdev que permite gerar formulários dinâmicos a partir de definições armazenadas em banco de dados e, opcionalmente, persiste os resultados.
- Gera formulários a partir de definições no BD;
- Processa a submissão dos formulários com validação e persistência;
- Mostra o resultado com views padrão;
- Possui crud completo para
admin; - Suporta estilos em Bootstrap 4 e 5;
- Integra com aplicações Laravel 11 em diante.
- Instale a biblioteca via Composer e publique as migrations
composer require uspdev/forms
php artisan vendor:publish --tag=forms-migrations
php artisan migrate- Menu na aplicação
No arquivo config/laravel-usp-theme.php, adicione ou reposicione a chave uspdev-forms para mostrar o menu. Ele será visível apenas para administradores.
[
'key' => 'uspdev-forms',
],Você pode personalizar as configurações do pacote modificando o arquivo config/uspdev-forms.php.
php artisan vendor:publish --tag=forms-config
Popula o banco com um formulário de demonstração com vários tipos de campos, facilitando testes rápidos.
php artisan forms:demoSincroniza definições de formulários em .json para a tabela form_definitions de forma idempotente (create ou update).
php artisan forms:syncPor padrão, o comando lê os arquivos do diretório configurado em uspdev-forms.forms_storage_dir.
Opcionalmente, você pode informar outro diretório:
php artisan forms:sync --path=storage/app/formsJson-
Crie uma entrada na tabela form_definitions
-
Nome do formulário: nome único que identifica o formulário
-
Grupo: serve para agrupar vários formulários em implementações mais complexas
-
Descrição: campo livre sem uso específico no sistema
-
Campos: campos do formulário
OBS.: Os campos USP dependem do replicado.
-
Em todos os campos pode ser definido a diretiva validation_rule com a validação dos campos Laravel conforme a documentação.
OBS.: Campos são validados pelo tipo definido em type. Por exemplo, campos do tipo "number" serão validados pela validação do Laravel "numeric".
- texto de 1 linha
[
{
"name": "name",
"type": "text",
"label": "Nome (text)",
"required": true,
"validation_rule": "max:150"
},
]- dois campos na mesma linha
[
{
"name": "name",
"type": "text",
"label": "Nome (text)",
"required": true
},
{
"name": "email",
"type": "email",
"label": "Email (email)",
"required": false,
"validation_rule":"max:150"
}
],- select simples
[
{
"name": "rating",
"type": "select",
"label": "Avaliação (select)",
"options": [
"1",
"2",
"3",
"4",
"5"
],
"validation_rule":"exists:ranking,id"
},
]- textarea
[
{
"name": "message",
"type": "textarea",
"label": "Mensagem (textarea)"
},
]- file (upload de arquivo)
[
{
"name": "arquivo",
"type": "file",
"label": "Arquivo",
"accept": ".pdf, image/*"
},
]- pessoa-usp
[
{
"name": "codpes",
"type": "pessoa-usp",
"label": "Pessoa USP",
"required": true
},
]- disciplina-usp
[
{
"name": "coddis",
"type": "disciplina-usp",
"label": "Disciplina USP",
"required": true
},
]- patrimonio-usp
[
{
"name": "numpat",
"type": "patrimonio-usp",
"label": "Patrimônio USP",
"required": true
},
]- local-usp
[
{
"name": "codlocusp",
"type": "local-usp",
"label": "Local USP",
"required": true
},
]- data
[
{
"name": "data",
"type": "date",
"label": "Campo de data",
"required": true
},
]FormDefinition::create($form);
- Gere o formulário na sua view:
Use a classe FormGenerator para renderizar o formulário no seu template Blade:
use Uspdev\Forms\Form;
$form = new Form($key = null, ['action' => route('forms.action')]);
$formHtml = $form->generateHtml('demo'); // conforme definido em $form
// ....- Trate as submissões do formulário:
No seu controller, trate a submissão do formulário salvando os dados no banco de dados:
public function store(Request $request)
{
$form = (new Form())->handleSubmission($request);
// ....
}OBS.: caso exista no $request a chave id ($request->id) o formulário anteriormente submetido com este id será atualizado. Caso existam erros de validação, o método retorna um array com as seguintes informações: [$validated['status'=>'error','errors'=>[dados do erro],'data'=>[dados preenchidos no formulário]],String HTMLFormulário preenchido]
Exemplo de tratamento de erros:
$message = [
'max'=>'O campo :attribute pode ter no máximo :max caracteres',
'required_if'=>'O campo :attribute precisa ser informado.',
'data_saida.after_or_equal'=>'O campo data saída deve ter um valor posterior à data de hoje',
'data_retorno.after_or_equal'=>'O campo data retorno deve ter um valor posterior à data informada na data de saída',
'date_format'=>'O formato de data deve ser HH:MM'
];
$form = (new Form(['editable'=>true]))->handleSubmission($request);
if (is_array($form))
{
$erros = '<li>';
foreach($form['validated']['errors']->getMessages() as $field=>$value) // Instância de MessageBag (Laravel)
{
foreach($value as $e)
{
$nomE = explode('.',$e);
if (!empty($message[$field.".".$nomE[1]])) $erros.="<ul>".$message[$field.".".$nomE[1]]."</ul>";
else $erros.="<ul>".str_replace(":attribute",$field,$message[$nomE[1]])."</ul>";
}
}
$erros.='</li>';
session(['alert_danger'=>$erros]); //precisa mostrar os erros na view no caso dessa varíavel existir
return view('view-aplicacao.create',['html'=>$form['formHtml']]); //formulário preenchido
}- Listar submissões Recupere todas as submissões em geral ou de um formulário específico:
$allSubmissions = $form->listSubmission();
// Ou
$allFormNameSubmissions = $form->listSubmission('form-name');- Obter submissão Recupere uma submissão específica pelo seu id:
$formSubmission = $form->getSubmission($formSubmissionId);- Download de arquivo Faça o download de um arquivo de uma submissão através do nome do campo:
$formSubmission = $form->downloadSubmissionFile($formSubmission, $fieldName);OBS.: Os arquivos são armazenados em storage/app/formsubmissions/<ano>/id<00>-<hash>.<ext>. Caso tenha problemas de download verifique se os arquivos estão no local correto.
- pessoa-usp: campo tipo select que faz busca no replicado e retorna uma pessoa. nome do campo recomendado: codpes;
- disciplina-usp: campo tipo select que faz busca no replicado e retorna uma disciplina. nome do campo recomendado: coddis;
- patrimonio-usp: campo tipo select que faz busca no replicado e retorna um bem patrimoniado. nome do campo recomendado: numpat;
- local-usp: campo tipo select que faz busca no replicado e retorna um local da usp já formatado. nome do campo recomendado: codlocusp;
- data: data simples no formato dd/mm/aaaa;
- text: texto simples (linha única);
- pode passar
"maxlength": 100para limitar a quantidade de caracteres;
- pode passar
- number: campo numérico;
- pode passar
"min","max"e"step"para definir limites e incremento;
- pode passar
- email: valida campos email;
- select: precisa passar
options; - textarea: parágrafos;
- file: pode passar
"accept" : ".pdf, image/*";
O atributo width define a largura do campo no grid do Bootstrap (col-1 até col-12).
{
"type": "text",
"name": "nome",
"width": 6
}HTML gerado:
<div class="col-6">
<input type="text" name="nome">
</div>Contribuições são bem-vindas! Siga estes passos para contribuir:
- Faça um fork do repositório.
- Crie um novo branch (git checkout -b feature/SuaFuncionalidade).
- Faça suas alterações e commit (git commit -m 'Adiciona nova funcionalidade').
- Envie para o branch (git push origin feature/SuaFuncionalidade).
- Crie um novo Pull Request.
- Visão Geral do Pacote: Descreve o que o pacote faz.
- Funcionalidades: Destaca as principais funcionalidades.
- Passos de Instalação: Fornece instruções detalhadas de instalação.
- Detalhes de Configuração: Guia sobre como personalizar as configurações.
- Exemplos de Uso: Mostra como criar um formulário YAML e usá-lo na sua aplicação.
- Guia de Contribuição: Incentiva contribuições com passos claros.
- Informações de Licença: Indica a licença