README

Biblioteca PHP para geração dinâmica de formulários baseados em dicionários de metadados de entidades. Permite criar, editar e validar formulários de maneira automatizada e consistente.

Principal Funcionalidade

A principal funcionalidade desta biblioteca é a view de formulário, que permite gerar formulários completos através de uma URL simples:

/form/{entidade}/{id}/{campos_opcionais}

Por exemplo:

/form/clientes/2 - Editar o cliente com ID 2
/form/produtos/null - Criar um novo produto
/form/usuarios/5/nome,email,telefone - Editar o usuário 5, mostrando apenas os campos especificados

Esta abordagem torna extremamente fácil implementar CRUDs completos sem necessidade de codificação adicional para cada entidade.

Funcionalidades

Geração Dinâmica: Cria formulários automaticamente a partir de dicionários de metadados
Suporte a Diversos Tipos de Campos: Input, textarea, select, checkbox, radio, switch, upload de arquivos, etc.
Relacionamentos: Gerencia relacionamentos entre entidades (one-to-one, one-to-many, many-to-many)
Validação Cliente/Servidor: Validação em JavaScript e PHP
Customização: Personalize a aparência e comportamento dos formulários
Autocomplete: Funcionalidade de preenchimento automático para campos relacionais
Responsivo: Formulários adaptáveis a diferentes tamanhos de tela

Instalação

composer require ueb/form

Como Usar

1. Via URL (Método Principal)

Simplesmente acesse a URL no formato:

// Criar novo registro
/form/{entidade}

// Editar registro existente
/form/{entidade}/{id}

// Especificar campos
/form/{entidade}/{id}/{campo1}/{campo2}

// Opções de exibição
/form/{entidade}/{id}/form-no-header  // Sem cabeçalho
/form/{entidade}/{id}/form-no-card    // Sem card

O formulário será gerado automaticamente com base no dicionário de metadados da entidade.

2. Integração com JavaScript

Para carregar um formulário dentro de uma div específica em sua página:

// Carrega o formulário na div #container
pageTransition("form/clientes/5", "#container");

// Carrega formulário com campos específicos
pageTransition("form/clientes/5/nome/email/telefone", "#container");

3. Query String Avançada

Você pode passar parâmetros adicionais via query string:

// Carregar com valores padrão
/form/clientes?defaults={"status":1,"tipo":"PF"}

// Especificar callback JavaScript após salvamento
/form/clientes?callback=reloadTable

// Desativar salvamento automático
/form/clientes?autosave=0

// Aplicar CSS customizado
/form/clientes?css=.custom-field{background:#f5f5f5}

4. Configuração de Rota (opcional)

Para implementar a rota /form/, você pode adicionar:

// Em seu arquivo de rotas
Router::route('/form/:entity/:id', function($data) {
    $entity = $data['entity'];
    $id = $data['id'];
    include PATH_HOME . 'vendor/ueb/form/public/view/form/form.php';
});

5. Uso Programático (alternativo)

// Criar um formulário para a entidade "produtos"
$form = new Form\Form("produtos");

// Exibir todos os campos da entidade
$form->showForm();

// Ou especificar campos desejados
$form->setFields(["nome", "descricao", "preco"]);
$form->showForm();

// Carregar formulário para edição
$form->showForm(5); // Carrega o registro com ID 5 para edição

Recursos Avançados

Formulários com Sub-formulários

Para entidades com relacionamentos, é possível carregar sub-formulários:

// Carregar formulário de cliente com sub-formulário de endereços
/form/clientes/5?loadRelated=enderecos

// Carregar formulário de pedido com sub-formulários de itens em formato tabular
/form/pedidos/10?loadRelated=itens&itemsLayout=table

Formulários com Etapas (Wizard)

Para formulários complexos que necessitam ser divididos em etapas:

// Definir formulário com etapas
/form/clientes?wizard=true&steps=dadosPessoais,endereco,configuracoes

// Acessar uma etapa específica
/form/clientes/5?wizard=true&currentStep=2

Modos de Visualização

// Modo somente leitura
/form/clientes/5?readOnly=true

// Modo de impressão
/form/clientes/5?printMode=true

// Modo de comparação (antes/depois)
/form/clientes/5?compareWith=4

Agrupamento de Campos em Seções

// Agrupar campos em seções com títulos
/form/clientes?groupFields=pessoal:nome,email,telefone;endereco:rua,numero,cidade

Eventos JavaScript

A biblioteca dispara eventos que podem ser capturados para personalização:

// Evento disparado após carregar o formulário
$(document).on("formLoaded", function(e, formData) {
    console.log("Formulário carregado:", formData.entity);
});

// Evento disparado após salvar com sucesso
$(document).on("formSaved", function(e, response) {
    notifySuccess("Registro salvo com sucesso!");
});

API JavaScript Avançada

// Obter instância do formulário
var formInstance = $("#form-container").data("formInstance");

// Acessar métodos e propriedades
formInstance.getData(); // Obter todos os dados atuais
formInstance.setFieldValue("nome", "Novo Valor"); // Definir valor
formInstance.validate(); // Validar manualmente
formInstance.save(); // Salvar manualmente

// Limpar formulário
formInstance.clear();

// Recarregar dados originais
formInstance.reload();

Personalização

// Definir valores padrão para novos registros
$form = new Form\Form("usuarios");
$form->setDefaults([
    "status" => 1,
    "data_cadastro" => date("Y-m-d")
]);

// Personalizar botão de salvar
$form->setSaveButtonText("Cadastrar Usuário");
$form->setSaveButtonIcon("person_add");
$form->setSaveButtonClass("btn-large");

// Desativar salvamento automático
$form->setAutoSave(false);

// Definir callback após salvamento
$form->setCallback("reloadTable");

Tipos de Campos Suportados

Input: Texto, número, email, telefone, CPF, CNPJ, CEP, etc.
Textarea: Campos de texto multilinha
Select: Dropdown com opções
Checkbox/Radio: Seleção única ou múltipla
Switch: Toggle on/off
File: Upload de arquivos
List: Campos relacionais
List_mult: Relações múltiplas
Extend: Campos de extensão para relacionamentos complexos

Opções da URL

A URL oferece algumas opções especiais:

form-no-header: Esconde o cabeçalho do formulário
form-no-card: Remove o estilo de card do formulário

Exemplo:

/form/clientes/2/form-no-header/form-no-card/nome/email

Endpoints

A biblioteca disponibiliza vários endpoints para processamento:

/post/save/form.php: Salva dados do formulário
/post/api.php: API principal para interação com formulários
/post/autocomplete/form.php: Gerencia autocomplete de campos
/post/children/form.php: Gerencia formulários filhos
/post/read/list.php: Leitura de listas relacionais

Templates Personalizáveis

A biblioteca utiliza templates Mustache para renderização. Cada tipo de campo possui seu próprio template:

input.mustache - Campos de texto, número, etc.
select.mustache - Dropdowns
checkbox.mustache - Caixas de seleção
file.mustache - Upload de arquivos
etc.

Você pode personalizar estes templates para adaptar a aparência dos formulários ao seu design.

Requisitos

PHP 7.2 ou superior
MySQL/MariaDB
Bibliotecas de dependência:
- Entity (para gerenciamento de dicionários de metadados)
- Helpers (para funções auxiliares)
- Conn (para conexão com banco de dados)

Contribuindo

Contribuições são bem-vindas! Por favor, sinta-se à vontade para enviar um Pull Request.

Licença

Este projeto está licenciado sob a MIT License.

ueb / form

Maintainers

Details