PHSYS - Wiki

O que é

O Formulário é uma tela dinâmica de coleta de informações, configurada inteiramente via cadastro (sem precisar de programação pra cada caso novo). Cada Formulário é composto por um cabeçalho (nome, legenda, tamanho) e uma lista de campos, onde cada campo é configurado como um registro próprio — com tipo, obrigatoriedade, valor padrão, etc.

O mesmo motor de Formulário é reaproveitado em vários pontos do sistema, tanto no desktop quanto na web: não existe um "Formulário de relatório" e um "Formulário de dashboard" separados — é a mesma engine, o que muda é só onde ela é acionada e o que é feito com os valores preenchidos.

Para que serve

Hoje o Formulário é usado em quatro frentes:

• Preenchimento de informações durante um processo: Um botão de cadastro pode abrir um Formulário pra pedir dados antes de executar uma rotina (ex: confirmar um período, escolher uma opção, informar uma observação) antes de rodar o script/regra de negócio vinculada ao botão.
• Filtro de relatório: Um formato de relatório pode ter um Formulário vinculado; os valores preenchidos viram parâmetros disponíveis pra a consulta do relatório.
• Filtro de dashboard: Um dashboard pode ter um Formulário vinculado; cada campo do Formulário pode ser ligado a uma coluna catalogada de um widget do dashboard (cadastro Filtro do Widget do Dashboard), o que monta automaticamente a condição de filtro sem precisar mexer na consulta (EXPRESSAOSQL) do widget.
• (Em breve) Filtro de Kanban e de Agenda: Mesmo mecanismo de filtro do dashboard, aplicado às próximas telas que vão passar a aceitar filtro por Formulário.

Quais os benefícios e/ou ganhos de uso

• Um único motor atende as quatro frentes, quem aprende a montar um Formulário sabe montar pra qualquer um dos usos acima, sem curva de aprendizado nova a cada contexto.
• Campo, tipo, obrigatoriedade e valor padrão são configuração, não programação, reduz a dependência de desenvolvimento pra ajustes pontuais.
• O preenchimento automático de data (Valor Padrão dinâmico, ver Exemplos) evita que o usuário esqueça de ajustar o filtro e acabe analisando um período desatualizado sem perceber, o campo já abre certo, todo dia. Recurso valioso para os dashboards, na qual podemos definir comportamentos de filtro, se a necessidade de informar manualmente um período.
• Um Formulário marcado para "lembrar" o preenchimento evita que o usuário tenha que redigitar o mesmo filtro toda vez que reabre a tela.

Cadastro

Formulário (cabeçalho)

• Nome: Identificador único do Formulário, usado internamente pra vincular a um botão de cadastro, formato de relatório ou dashboard.
• Legenda: Título exibido no cabeçalho da tela/modal do Formulário.
• Largura / Altura: Tamanho da tela do Formulário no desktop.
• Salvar: Quando marcado, o sistema lembra o último valor preenchido por cada usuário em cada campo, e já abre o Formulário preenchido da próxima vez (útil pra filtros repetitivos, como os de relatório/dashboard).
• Ajuda: Link relacionado à página de ajuda correspondente. Quando informado, é criado um botão de ajuda que serve de atalho para a respectiva página de ajuda.

Campo do Formulário (um registro por campo)

• Nome: Identificador do campo dentro do Formulário; é esse nome que aparece como parâmetro disponível pra quem consome o Formulário (relatório, dashboard, script do botão).
• Legenda: Rótulo exibido acima do campo pro usuário.
• Tipo de Campo: Define o tipo de dado e o controle exibido. Principais tipos disponíveis: Texto (linha única), Texto (memo/várias linhas), Inteiro, Valor (numérico com casas decimais), Data, Data/Hora, Hora, Lógico (sim/não), Lista de Opções, Radio, Tabela (busca/vínculo a um cadastro), Filtro, Diretório, Imagem.
• Sequência: Ordem de exibição do campo na tela.
• Nova Linha: Força o campo a começar sozinho numa linha nova, mesmo sobrando espaço na linha anterior.
• Opcional: Quando marcado, o campo não é obrigatório pra confirmar o Formulário.
• Leitura: Torna o campo somente-leitura (exibe o valor mas não permite edição).
• É Senha: Mascara o valor digitado (usado em campos de texto sensíveis).
• Valor Padrão: Valor com que o campo já abre preenchido. Além de um valor literal fixo, campos de Data/Data e Hora aceitam uma expressão dinâmica que é recalculada toda vez que o Formulário é aberto (ver Exemplos abaixo) — é a forma recomendada de propor um período relativo (últimos 30 dias, mês atual, ano atual, etc.) sem deixar uma data fixa "esquecida" na configuração.
• Agora: Quando marcado (só se aplica a campos de Data/Data e Hora), o campo sempre abre com a data do dia. Tem prioridade sobre o Valor Padrão.
• Condição SQL: Filtro adicional aplicado à busca de um campo do tipo Tabela/Lista de Opções (ex: restringir a busca a registros ativos, ou de uma filial específica).
• Tabela de Pesquisa / Campo Exibição / Campo Pai: Usados no campo tipo Tabela, definem em qual cadastro buscar, qual coluna mostrar como resultado, e (se aplicável) qual campo pai relaciona a busca a um valor já preenchido em outro campo do mesmo Formulário.
• Lista de Opções: Grupo de opções (DB_LISTASOPCOES) usado nos tipos Lista de Opções e Radio.
• Casas Decimais: Quantidade de casas decimais exibidas no tipo Valor.
• Mínimo: Tamanho mínimo de caracteres aceito (tipo Texto) ou valor mínimo (conforme o tipo).
• Vários Registros: Permite selecionar mais de um valor no mesmo campo (tipos Tabela/Lista de Opções), tratados como uma lista na hora de aplicar o filtro.
• Colunas: Colunas exibidas na grade de busca do campo tipo Tabela.

Por padrão, não adicionamos imagens/figuras ao processo de documentação.

Exemplos

Sintaxe dinâmica de data no Valor Padrão

Um campo de Data ou Data/Hora aceita, no Valor Padrão, a expressão [DATA;TIPO;VARIAÇÃO], resolvida pra uma data real toda vez que o Formulário é aberto — o campo nunca fica "parado" numa data antiga.

Tipo	Significado	Variação
D	Variação em dias	quantidade de dias a somar/subtrair de hoje
MP	Primeiro dia do mês, variando mês a mês	quantidade de meses a deslocar antes de tomar o 1º dia
MU	Último dia do mês, variando mês a mês	quantidade de meses a deslocar antes de tomar o último dia
AP	Primeiro dia do ano, variando ano a ano	quantidade de anos a deslocar antes de tomar o 1º dia
AU	Último dia do ano, variando ano a ano	quantidade de anos a deslocar antes de tomar o último dia

Exemplos de resultado (tomando "hoje" como uma data qualquer de referência):

• [DATA;D;0] → hoje
• [DATA;D;-30] → hoje menos 30 dias
• [DATA;MP;0] → primeiro dia do mês atual
• [DATA;MU;0] → último dia do mês atual
• [DATA;MP;-1] → primeiro dia do mês passado
• [DATA;AP;0] → primeiro dia do ano atual
• [DATA;AU;0] → último dia do ano atual

Formulário como filtro de período de um dashboard

Um Formulário com dois campos de Data — "Data Inicial" (Valor Padrão [DATA;D;-30]) e "Data Final" (Valor Padrão [DATA;D;0]) — vinculado a um dashboard, sempre abre propondo "os últimos 30 dias até hoje", sem que ninguém precise lembrar de ajustar manualmente. Cada um desses dois campos é então ligado, no cadastro de Filtro do Widget do Dashboard, à coluna do widget que representa a data (uma condição "maior ou igual" pra Data Inicial, "menor ou igual" pra Data Final) — um período é sempre modelado como duas condições simples, não como um único campo de intervalo.

Conclusão

O Formulário é a peça que conecta processos, relatórios e dashboards a uma tela de coleta configurável — sem depender de programação pra cada tela nova. Dominar a criação de um Formulário (tipos de campo, valor padrão, condição SQL) aproveita pras quatro frentes de uso atuais e futuras (processo, relatório, dashboard, e em breve Kanban/Agenda).

Assuntos Relacionados

Dashboards