Consulta e navegação

Antes de começar

• Módulo 07 concluído, com visitas de vários clientes e técnicos no banco.
• Este módulo é quase todo Dicionário. O Java aparece só no passo 3, para usar mensagens e configuração.

O que você vai construir

Com dezenas de visitas, a janela Visita Técnica deixa de ser o melhor jeito de encontrar alguma coisa. Neste módulo, você cuida de quem consulta:

• Uma Info Window: busca rápida de visitas, com filtros, que também serve de lookup.
• Mensagens no Dicionário: os erros do plugin passam a ser traduzíveis e editáveis sem recompilar.
• Uma configuração para a regra "visita concluída precisa de linha", que cada empresa pode ligar ou desligar.
• Um índice para as consultas que o plugin faz o tempo todo.
• Uma linha de status no cadastro do cliente: "3 visitas técnicas em aberto".
• O histórico de alterações das visitas.

Passo a passo

1. A Info Window

Conceito: uma Info Window é uma tela de busca: filtros em cima, resultado em grade embaixo. Não edita nada. Serve para o usuário encontrar registros e, a partir deles, abrir a janela ou rodar um processo.

Como System, na janela Info Window, crie:

O campo Window é o destino do zoom: o duplo clique numa linha abre a visita nessa janela. Default faz desta a Info Window padrão da tabela EDU_Visita.

Na aba Column, crie as colunas. Sql SELECT é a expressão, com o alias do FROM; Query Criteria marca as que viram filtro:

Salve e clique em Validate, na aba Window. O iDempiere monta o SQL e testa no banco; se estiver certo, marca Valid. Uma Info Window inválida não abre.

Crie a entrada de menu com Action Info e Info Window Visitas Técnicas, e rode Role Access Update como GardenAdmin.

Teste como GardenAdmin: busque as visitas em aberto de um cliente, depois as de um técnico no mês. Dê duplo clique numa linha: a visita abre na janela.

2. Mensagens no Dicionário

Hoje o plugin tem dois textos em português escritos no Java. Isso tem três problemas: não dá para traduzir, não dá para corrigir sem recompilar e ninguém encontra o texto procurando no Dicionário.

Na janela Message, crie:

Entity Type EDU em todas. A terceira é para o passo 5. O {0} é um marcador do MessageFormat do Java.

3. Uma regra configurável

Conceito: o System Configurator guarda parâmetros que mudam o comportamento do sistema sem mexer no código. Cada parâmetro tem um nível: pode valer para o sistema todo, ou ser sobrescrito por empresa ou por organização.

Na janela System Configurator, crie:

Com o nível Client, a GardenWorld pode ter o próprio registro com outro valor, e ele vale só para ela.

Agora o Java. Na MVisita, troque a regra de conclusão:

public static final String SYSCONFIG_EXIGE_LINHA = "EDU_VISITA_EXIGE_LINHA";

@Override
protected boolean beforeSave(boolean newRecord) {
    if (getC_BPartner_Location_ID() <= 0
            || is_ValueChanged(COLUMNNAME_C_BPartner_ID) && !is_ValueChanged(COLUMNNAME_C_BPartner_Location_ID)) {
        setC_BPartner_Location_ID(getEnderecoPadrao(getCtx(), getC_BPartner_ID(), get_TrxName()));
    }

    if (isEDU_IsConcluida()
            && is_ValueChanged(COLUMNNAME_EDU_IsConcluida)
            && MSysConfig.getBooleanValue(SYSCONFIG_EXIGE_LINHA, true, getAD_Client_ID())
            && getLinhas().isEmpty()) {
        log.saveError("Error", Msg.getMsg(getCtx(), "EDU_VisitaSemLinhas"));
        return false;
    }
    return true;
}

Imports: org.compiere.model.MSysConfig e org.compiere.util.Msg.

E no ClienteComVisitaAberta, do módulo 05:

if (temVisitaAberta)
    throw new AdempiereException(Msg.getMsg(cliente.getCtx(), "EDU_ClienteComVisitaAberta"));

Dois detalhes:

• O valor padrão do getBooleanValue é true: se alguém apagar a configuração, a regra continua valendo. Escolha o padrão mais seguro.
• O nome da configuração vira constante. Ele é usado no código e digitado no Dicionário; uma constante evita que os dois se desencontrem.

Reinicie o servidor e teste: com Y, a regra funciona como antes. Mude o valor para N, conclua uma visita sem linhas e veja passar. O valor é lido em cache: se a mudança não aparecer, use Cache Reset no menu. Volte para Y no fim.

4. Índices pelo Dicionário

O plugin consulta visitas por cliente e situação em três lugares: o event handler do módulo 05, o processo do módulo 06 e a linha de status do próximo passo. Com poucas visitas, tanto faz. Com cem mil, é a diferença entre instantâneo e travado.

Como System, na janela Table and Column, tabela EDU_Visita, aba Table Index:

Na aba Index Column:

Volte à aba Table Index e clique em Index Validate. Confira no psql:

\d edu_visita

Pelo Dicionário, e não com CREATE INDEX direto no banco, pelo mesmo motivo da view do módulo 07: o índice vai no 2Pack junto com a tabela.

5. A linha de status no cliente

Conceito: uma Status Line executa uma consulta e mostra o resultado formatado por uma mensagem. Pode aparecer na barra de status de uma janela ou no painel de ajuda ao lado.

Na janela Status Line, crie:

Na aba Used In:

O @C_BPartner_ID@ é lido do contexto da janela, como nas lógicas do módulo 02. O resultado entra no lugar do {0} da mensagem.

Teste como GardenAdmin: abra Business Partner, navegue até um cliente com visitas e veja a contagem na barra de status. Mude de cliente e ela muda junto.

6. Histórico de alterações

Conceito: o iDempiere pode registrar cada mudança de valor, com usuário, data, valor antigo e novo. Vem desligado por padrão, tabela por tabela, porque ocupa espaço.

Na tabela EDU_Visita, marque Maintain Change Log e salve.

Como GardenAdmin:

1. Abra uma visita, mude o Tipo e salve.
2. Clique com o botão direito no campo Tipo e escolha Change Log. Aparece a mudança, com quem fez e quando.
3. Para ver tudo o que mudou no sistema, use a janela Change Audit.

7. Commit

Inclua no Pack Out a Info Window (tipo Info Window), as três mensagens (tipo Message) e o item de menu. A tabela EDU_Visita entra de novo, porque ganhou índice e Maintain Change Log.

A Status Line e a configuração não têm tipo próprio: vão como Data, com a tabela e uma consulta em SQL Expression/Statement:

Gere o 2Pack_1.0.4.zip.

git add .
git commit -m "Visitas 1.0.4: info window, mensagens, configuração, índice, status line e change log"

Checkpoint

Erros comuns

Desafio

Adicione à Info Window um processo: Gerar Visitas de Manutenção (módulo 06), na aba Process da Info Window. Depois, faça a linha de status mostrar também a data da próxima visita em aberto do cliente (dica: {1} na mensagem e uma segunda coluna no SELECT).

Referência

Níveis do System Configurator

No código, o método recebe o nível mais específico que você conhece: getBooleanValue(nome, padrão), getBooleanValue(nome, padrão, AD_Client_ID) ou getBooleanValue(nome, padrão, AD_Client_ID, AD_Org_ID). Existem as mesmas variações para getValue, getIntValue e getBigDecimalValue.

Mensagens no código

Operadores da Info Column

=, !=, >, >=, <, <=, Like (começa com) e Full Like (contém). Para ignorar maiúsculas, use UPPER(bp.Name) no Sql SELECT. Colunas com Range pedem "de" e "até".

Próximo módulo

09 · Documentos e aprovação: a visita vira um documento, com número, status, completar, anular e aprovação.