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:

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

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

2. 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';
});

3. 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

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

API JavaScript

A biblioteca inclui scripts JavaScript para interação do usuário:

// Inicializar formulário
$("#form-container").form("usuarios", null, ["nome", "email", "telefone"]);

// Inicializar com callback após salvamento
$("#form-container").form("usuarios", null, [], function() {
    alert("Usuário salvo com sucesso!");
});

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

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)

Exemplos Avançados

Criando um formulário com relacionamentos

// Formulário de pedidos com relacionamento a clientes
$form = new Form\Form("pedidos");
$form->showForm();

// Automaticamente gerencia o campo de seleção de cliente
// baseado no dicionário de metadados

Validação customizada

// A validação é definida no dicionário de metadados
// e processada automaticamente

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.