Menus do Protheus: como incluir uma rotina customizada no módulo

Compilar uma rotina não a coloca na tela de ninguém. Para o usuário abrir a sua User Function pelo módulo, ela precisa virar item de um menu, esse menu precisa ser gerado e o usuário precisa estar apontado para ele. São três passos diferentes, e a rotina “sumida” quase sempre parou em um deles.

O cadastro de menus é a rotina CFGX013, em Ambiente > Cadastros > Menus no Configurador. Ela trabalha sempre do mesmo jeito: parte de um menu que já existe, o menu de entrada, e gera outro, o menu de saída.

O exemplo deste artigo é o da série: pôr a rotina U_ZA1CAD, o cadastro de motoristas da tabela ZA1, num grupo Customizados do menu do Faturamento.

Onde os menus ficam no banco

Com o dicionário no banco, os menus ficam num conjunto de tabelas MPMENU_, sem sufixo de empresa: MPMENU_MENU com os menus, MPMENU_ITEM com os itens, MPMENU_FUNCTION com as funções chamadas e MPMENU_I18N com as descrições por idioma.

No ambiente que conferimos, os menus com nome de módulo, como SIGAFAT, têm cópias do menu anterior nessas tabelas, com o nome #BKP_<MENU>#<data e hora>. A cópia guarda os itens do menu anterior, e dá para consultá-la por SQL para ver o que existia antes da troca. Não conferimos se um menu com nome próprio também ganha cópia, nem um procedimento para restaurar a partir dela: o caminho seguro continua sendo gerar com nome próprio, como mostra a seção sobre o nome do menu. Veja as cópias que existem para o Faturamento:

SELECT M_NAME, M_MODULE
  FROM MPMENU_MENU
 WHERE D_E_L_E_T_ = ' '
   AND M_NAME LIKE '#BKP_SIGAFAT#%'
 ORDER BY M_NAME

E esta responde “em quais menus a ZA1CAD está, e com que descrição”:

SELECT M.M_NAME, F.F_FUNCTION, N.N_DESC
  FROM MPMENU_MENU M
  JOIN MPMENU_ITEM I
    ON I.I_ID_MENU = M.M_ID
   AND I.D_E_L_E_T_ = ' '
  JOIN MPMENU_FUNCTION F
    ON F.F_ID = I.I_ID_FUNC
   AND F.D_E_L_E_T_ = ' '
  LEFT JOIN MPMENU_I18N N
    ON N.N_PAREN_ID = I.I_ID
   AND N.N_LANG = '1'
   AND N.D_E_L_E_T_ = ' '
 WHERE M.D_E_L_E_T_ = ' '
   AND M.M_NAME NOT LIKE '#%'
   AND F.F_FUNCTION LIKE '%ZA1CAD%'

O filtro NOT LIKE '#%' tira as cópias de segurança. Sem ele, a rotina aparece também em cada backup do menu. A estrutura das tabelas MPMENU_ foi conferida num ambiente com dicionário no banco. Se a consulta falhar no seu, confira os nomes das colunas antes de concluir qualquer coisa.

Montando o menu

1. Abra Ambiente > Cadastros > Menus. A rotina mostra os menus disponíveis. No rodapé, use Todos os menus para desmarcar todos, marque só o do Faturamento (SIGAFAT) e clique em OK.
2. Na coluna do meio, clique em Adicionar. O sistema cria, na coluna Novo Menu, uma cópia do menu escolhido.
3. Em Novo Menu, posicione o cursor na pasta principal que deve receber o grupo, por exemplo Atualizações. Clique em Novo Grupo e digite o nome, Customizados.
4. Posicione no grupo e clique em Novo Item. Preencha o item e clique em OK.
5. Clique em Gerar e, em Arquivo, informe o nome do menu. A seção seguinte explica qual nome usar.

A documentação da TOTVS chama de Ambiente o campo em que se escolhe o módulo. Os passos da Central de Atendimento chamam o mesmo campo de Módulo. É o único que a documentação marca como indispensável para gerar o menu.

A página da TOTVS sobre criar item diz que o programa em AdvPL deve estar precedido por #. Nos menus gravados em banco que conferimos, nenhuma função aparece com #: os itens do tipo Função de Usuário estão quase sempre só com o nome, ZA1CAD, sem #, sem U_ e sem parênteses. Com o dicionário no banco, siga o que está gravado: informe só o nome e confira como ficou com a segunda consulta do início do artigo. Se o seu ambiente mostrar outra grafia nos itens que já funcionam, siga a do seu ambiente.

Para alterar um item que já existe, posicione nele, no lado direito, e use Detalhes. Faça a alteração, confirme e gere o menu de novo.

O nome que você digita em Arquivo, ao gerar, decide quem é afetado.

Com o nome do módulo (SIGAFAT), você sobrescreve o menu padrão do Faturamento. É assim que a TOTVS manda incluir a rotina APCFG110 no menu do Configurador: gerando como SIGACFG.

Com um nome próprio, por exemplo ZSIGAFAT, o menu novo não afeta ninguém até ser atribuído a um usuário ou a um grupo. Com o dicionário no banco, essa é a orientação da TOTVS: não mexer nos arquivos .xnu da pasta System nem alterar o menu padrão. Segundo a Central de Atendimento, alterar o menu padrão pelo Configurador nesse cenário quebra a estrutura padrão e deixa o menu desconfigurado. Monte um menu com nome próprio e vincule a quem precisa.

Entregando o menu ao usuário

1. Em Usuário > Senhas > Usuários, clique no usuário e em Alterar.
2. Na aba Restrições de acesso / Ambientes, localize o módulo Faturamento. Na coluna Arquivo, dê um duplo clique e troque o nome pelo do menu que você gerou.
3. Clique em Confirmar.
4. Para um grupo inteiro, o caminho é o mesmo em Usuário > Senhas > Grupos.

Ao incluir uma rotina no menu do Configurador, a orientação da TOTVS é sair e entrar de novo para ver a opção nova. Faça o mesmo no módulo do usuário.

O último caso merece atenção. Quando a TOTVS publica um menu novo para um módulo, o arquivo baixado vai para a pasta System. Com o dicionário no banco, entre em Ambiente > Cadastros > Menus e clique em Atualizar, no lado direito da rotina. Ela lista os arquivos de menu que estão na pasta System. Clique em Atualizar de novo e aguarde a mensagem de sucesso.

Com a rotina no menu, quem decide o que cada usuário pode fazer dentro dela são os privilégios.