NFS Crud All — Guia de Configuração e Uso

1) O que é o Crud All

O Crud All é um formulário único de inserção que permite trabalhar:

com uma tabela principal;
com as tabelas filhas relacionadas a tabela principal;
com tabelas não relacionadas;
escolhendo quais campos exibir e quais tabelas devem ou nao ser exibidas
com cenários onde há regras de replicação de valores, limpeza por grupo e validação guiada.
relatórios de salvamento geral

Na prática, ele reduz navegação entre telas e concentra o preenchimento em um fluxo único e orientado.

2) Rota do recurso

Base: t/{table}

GET /t/{table}/all
Exibe o formulário Crud All.

3) Como o Crud All é habilitado

A configuração vem de Entry Point de CONFIG com ACTION=CrudAll. São aceitos entrypoints do tipo JSON e PHP.

3.1 Campos de configuração relevantes

A config normalizada do Crud All considera principalmente:

main_table
hidden_children
extra_tables
main_hidden_fields
children_fields
replicate_excluded_fields
replicate_from_main_enabled
replicate_field_map
replicate_field_map_scope

3.2 Exemplo de configuração comentado (PHP)

FILE_OR_DOMAIN

CONFIG

ACTION

CrudAll

CODE

$this->outputValues = [
    'main_table' => 'OS', /** tabela principal */
    'hidden_children' => ['OS_DIV_TALHAO'], /** tabelas filhas que serão ocultadas */
    'extra_tables' => ['EQP'],/** tabelas fora de relação que devem ser incluidas */
    'replicate_from_main_enabled' => true, /** Ver ajuda 1 */
    'replicate_excluded_fields' => ['DIV_TALHAO'], /** Ver ajuda 2 */
    'replicate_field_map' => [/** Ver ajuda 3 */
        'DESCRICAO' => 'INI_DH_ONLINE',/** Ver ajuda 3 */
    ],
    'replicate_field_map_scope' => [/** Ver ajuda 4 */
        'DESCRICAO:INI_DH_ONLINE' => ['EQP_APT'],/** Ver ajuda 4 */
    ],
    'main_hidden_fields' => ['DATA_ULTIMA_ALTERACAO'],/** campos da tabela principal que não devem ser exibidos no crud all */
    'children_fields' => [/* é um objeto/mapa por tabela filha. Ver ajuda 5 */
        'EQP_APT' => [/* Ver ajuda 5 */
          'hidden_fields' => ['CAMPO_1', 'CAMPO_2']/* Campos que serão ocultados */
      ]
    ]
];

Ajuda 1: replicate_from_main_enabled (true/false): Se ativo a replicação de campos iguais entre as tabelas passa a acontecer de forma automática. Se tabelas filhas compatilharem de campos com mesmo nome/tipo ao preencher a tabela principal os campos das filhas se conectam e também são preenchidos, desde que a tabela esteja no formulario de envio (com algum dado já preenchido).

Exemplo:

Ajuda 2: replicate_excluded_fields (array): Passe os campos que tem o mesmo nome mas nao devem ter o valor compartilhado, assim a replicação irá ignorar esse comportamento.

Ajuda 3: replicate_field_map (array): O comportamento de replicação de campos da tabela principal para as tabelas filhas, pode ser manipulado atraves desse mapa. Para que campos com nomes diferentes possam ser considerados como sendo campos que compartilham o valor e a replicação de valor passar a ocorrer desde que aqui esteja configurado.

Exemplo: Quero que o valor que eu preencher no campo DESCRICAO seja replicado nos campos INI_DH_ONLINE das tabelas filhas que tem o campo, eles não tem o mesmo nome, então automaticamente eles não iriam compartilhar do mesmo valor, mas o mapa configura, que, DESCRICAO replica em INI_DH_ONLINE.

Ajuda 4: replicate_field_map_scope (array): Esse campo limita o scopo da replicação explicada melhor na Ajuda 3 para as tabelas apontadas.

Exemplo:

'DESCRICAO:INI_DH_ONLINE' => ['EQP_APT'],

No exemplo acima, vemos que a regra de replicação do campo DESCRICAO para INI_DH_ONLINE só deve acontecer para a tabela EQP_APT. Ou seja, mesmo que outra tabela filha tenha um campo chamado INI_DH_ONLINE ele será ignorado e a replicação não irá acontecer.

Ajuda 5: children_fields é um objeto/mapa por tabela filha. Hoje, o único campo aceito dentro de cada tabela é hidden_fields.

'children_fields' => [
    'EQP_APT' => [ /** Tabela filha */
      'hidden_fields' => ['CAMPO_1', 'CAMPO_2'] /** Campos */
  ]
]

4) Estrutura visual/UX da tela

O formulário possui:

header com título + botão de favoritos;
grupo principal (main);
grupos filhos (com conteúdo e sem conteúdo);
botão global Salvar;
botão global Limpar tudo;
botão por grupo filho para limpeza individual (ícone lixeira);
modal de progresso/sucesso/erro do salvamento.

Overview

5) Comportamentos importantes

5.1 Salvamento em etapas

No submit, o fluxo registra progresso por tabela (principal + filhos que têm conteúdo), ao final é recebido um feedback de sucesso ou erros, sempre por tabela.

Relatório de erro no salvamento do Crud All — Exemplo de relatório de erro por tabela no salvamento do Crud All.

Na imagem vemos que a validação passou nos campos da tabela principal (OS), mas parou em uma tabela filha. Nada foi salvo, pois usamos transações, e o registro só sera persistido se todas as tabelas passarem da validação.

5.2 Relatório de salvamento

Após tudo ser validado e persistido, teremos algumas opções na tela como podemos ver no print a baixo.

Tela de sucesso ao salvar — Exemplo de sucesso na persistência dos dados.

Uma das opções é o relatório final com os dados que foram persistidos.

Veja o exemplo de relatório: Baixar relatório

5.3 Limpeza

Limpar tudo: limpa principal e filhos.
Limpar tabela individual: limpa apenas o grupo selecionado.

5.4 Replicação de valores

Quando habilitado, valores da principal podem ser replicados para campos-alvo em grupos filhos, respeitando:

mapeamento por gatilho (replicate_field_map);
escopo (replicate_field_map_scope);
exclusões (replicate_excluded_fields);
flag mestre (replicate_from_main_enabled).

INSERT INTO novaagro_bobagro.nfs_tours
(DESCRIPTION, TITLE, URL, STEPS, ACTIVE)
VALUES('Tour Crud All', 'Tour Crud All', '/t/*/all', '[
    {
      "popover": {
        "title": "Bem-vindo ao Crud All",
        "description": "Aqui você faz um cadastro único com informações da tabela principal e das tabelas relacionadas. O objetivo é preencher tudo em uma única tela, de forma simples e organizada."
      }
    },
    {
      "element": "#nfs-crud-form-all",
      "popover": {
        "title": "Área de preenchimento",
        "description": "Nesta área ficam os campos do formulário. Primeiro preencha os dados principais e, quando houver, complete também os dados complementares."
      }
    },
    {
      "element": ".children-group .group-clear-btn",
      "popover": {
        "title": "Limpar tabela individual",
        "description": "Use este ícone para limpar apenas os dados desta tabela, sem afetar o restante do formulário."
      },
      "side": "left",
      "align": "center"
    },
    {
      "element": "#tour-crud-all-save",
      "popover": {
        "title": "Salvar cadastro",
        "description": "Quando finalizar o preenchimento, clique em Salvar para concluir o cadastro."
      },
      "side": "right",
      "align": "center"
    },
    {
      "element": "#tour-crud-all-clear",
      "popover": {
        "title": "Limpar tudo",
        "description": "Se quiser recomeçar, use este botão para limpar todos os dados do formulário."
      },
      "side": "left",
      "align": "center"
    },
    {
      "popover": {
        "title": "Tour concluído",
        "description": "Pronto! Agora você já conhece os principais recursos de uso do Crud All."
      }
    }
  ]', 1);

Simova Docs