Pastas e agrupamentos: organizando a tela do cadastro

Em qual aba do cadastro um campo aparece é decidido, de saída, no dicionário de dados: o campo aponta para uma pasta pelo X3_FOLDER, na SX3, e a pasta é um registro da SXA da mesma tabela. O título que o usuário vê na aba (“Cadastrais”, “Fiscais”, “Vendas” no cadastro de clientes) é o XA_DESCRIC desse registro. Ao lado da pasta existe o agrupamento, uma divisão com título próprio dentro da tela, que o campo indica pelo X3_AGRUP e que também fica na SXA.

A rotina pode mudar isso. Em MVC, a estrutura da View (FWFormViewStruct) tem as propriedades MVC_VIEW_FOLDER_NUMBER (“Pasta do campo”) e MVC_VIEW_GROUP_NUMBER (“Agrupamento do campo”), que o SetProperty troca campo a campo. Se o campo aparece numa aba diferente da que o X3_FOLDER indica, procure um SetProperty desses na ViewDef da rotina. Como a View trata as propriedades MVC_VIEW_* está em Validar e bloquear campo no MVC.

A documentação da SXA situa os dois recursos: pastas valem para a tela de cadastro montada com Enchoice ou, em MVC, com FormField; o agrupamento (agrupador) é recurso de rotina escrita em MVC, que pode dividir cada pasta. O mapa das tabelas do dicionário está em Dicionário de dados do Protheus.

Na SXA, o que separa pasta de agrupamento é o XA_AGRUP: segundo a documentação, registro com XA_AGRUP em branco é pasta; preenchido, é o código de agrupamento a que o X3_AGRUP do campo se liga.

O XA_ORDEM é a ordem de exibição, e só na pasta ele é também a chave de ligação com a SX3. O título da pasta ou do agrupamento é o XA_DESCRIC. O XA_TIPO, quando preenchido, vale 1 para Painel ou 2 para Separador, segundo a mesma documentação.

O cadastro de clientes do padrão usa as duas coisas:

• Pastas (XA_AGRUP e XA_TIPO em branco): 1 Cadastrais, 2 Adm/Fin., 3 Fiscais, 4 Vendas.
• Agrupamentos, todos com XA_TIPO = 2 (separador) e com XA_ORDEM de 1 a 8, na mesma sequência dos códigos:

Repare no XA_ORDEM: os agrupamentos do SA1 também usam 1, 2, 3 e 4, os mesmos valores das pastas. Por isso, toda consulta que procura a pasta pelo XA_ORDEM precisa filtrar o XA_AGRUP em branco.

O cadastro de produtos tem oito pastas — de “Cadastrais” a “Garantia Estendida”. O B1_BITMAP, a foto do produto, está na pasta 5, “Atendimento”.

O código do agrupamento tem regra de dono: iniciado por número é de uso do sistema; iniciado por letra é do usuário. Um agrupamento seu começa por letra.

Duas observações tiradas desses dados:

• Pasta e agrupamento são independentes. No SA1, os campos do agrupamento 008 estão espalhados por pastas diferentes (A1_TPFRET na pasta 2, A1_TRANSP na 4), e a maioria não tem pasta nenhuma. X3_FOLDER e X3_AGRUP são colunas separadas, e cada uma é preenchida por conta própria.
• O “Outros” do SA1 é um agrupamento cadastrado na SXA, com código 008. Não confunda com o “Outros” que aparece na tela para campos sem pasta ou sem agrupamento, descrito a seguir.

No exemplo da série, a tabela customizada ZA1 guarda o cadastro de motoristas de uma transportadora. A tela vai ter duas pastas:

E cada campo aponta para a sua pelo X3_FOLDER:

Os campos reservados ZA1_MSBLQL (bloqueio) e ZA1_BITMAP (foto) ficam sem pasta, e na tela eles vão para uma pasta “Outros”, sem posição definida por XA_ORDEM. A TOTVS registra esse efeito no cadastro de Grupos de Aprovação (MATA114): um campo com X3_FOLDER vazio aparecia na pasta Outros, e a correção foi preencher o X3_FOLDER com a pasta certa. Se um campo seu aparecer em “Outros” sem você querer, confira o X3_FOLDER dele.

O procedimento das pastas, conforme a documentação da TOTVS:

1. No Configurador, em Base de Dados > Dicionário > Arquivos, posicione na ZA1 e clique em Editar. A tela do arquivo tem a pasta Pastas, onde ficam as abas já vinculadas à tabela.
2. Em Pastas, clique em Incluir. A inclusão pede só as descrições: Descrição, Desc. Espan. e Desc. Inglês. Crie “Dados do motorista” e depois “Observacoes”.
3. Preenchida a pasta, clique na pasta Campos e em Adicionar. Marque cada campo com duplo clique até aparecer um x. A lista só oferece campos que ainda não estão em nenhuma pasta — um campo pertence a uma pasta só. Confirme os campos e confirme a criação da pasta.
4. Para mudar a ordem em que as abas aparecem, use Ordenar, na janela de manutenção de pastas: Mover Acima e Mover Abaixo reposicionam cada pasta, e a ordem é confirmada em Ok. Para levar campos de uma pasta para outra, use Mover Campo: escolha a pasta de origem, marque os campos e indique a pasta de destino em Mover Para.
5. Para ver como a tela fica, volte ao browse de Arquivos, posicione na ZA1 e clique em Preview. A prévia pode ser montada como Enchoice, Get Dados ou Pasta de Cadastro, entre outras opções. Depois, confirme o que ficou gravado com as consultas do fim do artigo.

O agrupamento só aparece em rotina escrita em MVC, como a tela da ZA1 em Testando a tabela criada. Dentro da pasta “Dados do motorista”, a ideia é separar a identificação do motorista do vínculo e do curso:

• A01 — Identificacao, tipo Separador: ZA1_COD, ZA1_NOME, ZA1_NASC e ZA1_IDADE.
• A02 — Vinculo e MOPP, tipo Painel: ZA1_VINC e ZA1_MOPP.

O código (XA_AGRUP) começa por letra porque o agrupamento é de usuário. O tipo decide o comportamento: Separador define um título e inclui um separador entre os campos; Painel permite esconder e revelar os campos dele.

O procedimento, conforme a documentação da TOTVS:

1. No Configurador, posicione na ZA1 e clique em Editar, como no passo 1 das pastas (a página da TOTVS sobre agrupamentos escreve o caminho como Base de Dados > Dicionário > Base de Dados).
2. Clique em Agrupamentos e em Incluir.
3. Em Agrupamento, informe o código: A01.
4. Em Tipo, escolha Painel (para esconder/revelar campos) ou Separador (para definir títulos e incluir separador).
5. Em Descrição, informe o texto que aparece no painel ou no separador: “Identificacao”.
6. Clique em Campos e em Adicionar, selecione os campos do agrupamento e clique em Salvar. Depois, em Confirmar.
7. Repita para o A02. Ao terminar, clique em Confirmar, depois em Atualizar base de dados, e vá avançando até Finalizar.

Os campos que não estiverem em nenhum agrupamento aparecem, segundo a mesma página, num separador chamado Outros. Na ZA1, é ali que o ZA1_OBS ficaria, dentro da pasta “Observacoes”. O esquema a seguir não detalha o interior da pasta “Outros” onde ficam o ZA1_MSBLQL e o ZA1_BITMAP.

O esquema abaixo junta as duas montagens. É um desenho da disposição, não uma captura da tela, e liga cada parte à coluna do dicionário que a produz:

As pastas e agrupamentos de uma tabela; as pastas vêm primeiro, com XA_AGRUP em branco. O XA_PROPRI diz de quem é o registro: a documentação da SXA o descreve como “S - Sistema” ou “U – Usuário”. O sufixo 010 é o do exemplo; o seu depende da empresa.

SELECT XA_ORDEM, XA_DESCRIC, XA_AGRUP, XA_TIPO, XA_PROPRI
  FROM SXA010
 WHERE XA_ALIAS = 'ZA1'
   AND D_E_L_E_T_ = ' '
 ORDER BY XA_AGRUP, XA_ORDEM

Cada campo com a pasta e o agrupamento em que está. Campo com X3_FOLDER vazio (e XA_DESCRIC nulo) é campo sem pasta; com X3_AGRUP vazio, é campo sem agrupamento:

SELECT X3.X3_FOLDER, XA.XA_DESCRIC, X3.X3_AGRUP, X3.X3_CAMPO, X3.X3_TITULO
  FROM SX3010 X3
  LEFT JOIN SXA010 XA
    ON XA.XA_ALIAS = X3.X3_ARQUIVO
   AND XA.XA_ORDEM = X3.X3_FOLDER
   AND XA.XA_AGRUP = ' '
   AND XA.XA_TIPO = ' '
   AND XA.D_E_L_E_T_ = ' '
 WHERE X3.X3_ARQUIVO = 'ZA1'
   AND X3.D_E_L_E_T_ = ' '
 ORDER BY X3.X3_FOLDER, X3.X3_ORDEM

O XA.XA_AGRUP = ' ' e o XA.XA_TIPO = ' ' no JOIN restringem a ligação aos registros de pasta. Sem eles, no SA1, a pasta 1 viria junto com o agrupamento 001, que também tem XA_ORDEM igual a 1, e os campos da pasta 1 sairiam duplicados.

Quando todo mundo cai em “Outros”

A Central de Atendimento TOTVS documenta um sintoma específico do cadastro de clientes: a tela perde as abas, e os campos aparecem todos numa mesma aba “outros”. A causa apontada é a migração da versão 11 para a 12, em que o layout existente na SXA do SA1 não foi reconhecido pelo sistema. A solução indicada, para esse caso, é atualizar o dicionário de dados com a versão mais recente disponível no Portal do Cliente e executar o UPDDISTR, o atualizador de dicionário.

Antes de ir para o atualizador, as duas consultas acima (trocando ZA1 por SA1) mostram se as pastas existem na SXA e se o X3_FOLDER dos campos aponta para elas.

Os campos reservados de foto, bloqueio e log estão em Campos reservados.

Se você está reorganizando a tela de um cadastro grande e quer que a mudança não bagunce o que os usuários já conhecem, fale com a gente.