Regras de UI

O motor de regras surge com a necessidade de alterar o estado da view em determinadas condições. A plataforma elevation (V4) alterou, ligeiramente, a forma de construir regras de UI. E passou a avaliar expressões com o mecanismo fornecido pelo ng-formly.

Migração das regras da v3 para a v4

Com a nova versão da framework as regras dos produtos necessitam de sofrer uma migração. A versão 3 da plataforma elevation necessitava de usar determinadas variáveis que nesta nova versão foram alteradas. Assim, quando um produto migrar para a versão 4 necessita de atualizar os ficheiros de regras.

• $parent.model para parentModel;
• viewState.isEditable e $parent.viewState.isEditable passam para formState.isEditable;
• as regras sobre o modelState devem terminar;
• regras sobre atributos detail (ex: documentLines) devem utilizar o parentModel para realizar a expressão para o binding;
• A ação de delete (action_delete) passou a ser action_cancel para entidades não deletable;
• A expressão de validação sobre claims appContextService.claims.contains(\"setting_simplifiedwithholdingtaxes\")" passa a appContext.containsClaims(\"setting_simplifiedwithholdingtaxes\")"

Boas práticas na escrita de regras de ui

Na análise feita às regras já escritas pelos produtos foram encontradas diversas regras com possíveis problemas. É necessário ter em atenção que as expressões vão ser avaliadas pelo javascript e não podem ocorrer erros como:

• Variáveis undefined - É necessário garantir que a variável documentLines tem valor. Ou seja, a regra deve ser escrita da seguinte forma:

"model.documentLines.length > 0” - FORMA ERRADA
“model.documentLines && model.documentLines.length > 0” - FORMA CORRETA

• Usar o parentModel em atributos detail - Quando se pretende fazer uma regra para os detalhes (ex: documentLines) o model a ser usado na regra é o parentModel em vez do model. Porque o componente de detalhe assume o model o conjunto de linhas e não o master.

"model.sourceDoc == null || model.sourceDoc == undefined” - FORMA ERRADA
"parentModel.sourceDoc == null || parentModel.sourceDoc == undefined” - FORMA CORRETA

• Value Lists - Devido a uma limitação no componente é necessário que as value lists se encontrem visíveis aquando do carregamento da view de modo a conseguirem carregar o default value. Assim, ao definir regras para a visibilidade de uma value list deve ser tido em conta o estado formState.initializing, de forma a garantir que na inicialização da view estas se encontram visíveis.

Além disso, os atributos utilizados nas regras têm de estar definidos na resource.

Exemplo de regras

As regras de UI são possiveis de aplicar a vários elementos das views. Alguns exemplos são:

• Bloquear campos da view:

    ...
    {
        "actionType": "SetDisabledValue",
        "target": "warehouse",
        "value": "model.itemType == 2"
    }
    ...

Regra para bloquear o warehouse na linha da encomenda quando o tipo do artigo é do tipo serviço.

• Visibilidade de campos da view

    ...
    {
        "actionType": "SetVisibilityValue",
        "target": "discount",
        "value": "model.autoCreated == true"
    }
    ...

Regra para visibilidade a false do discount na encomenda quando auto created for verdadeiro.

• Required de campos da view

    ...
    {
        "actionType": "SetRequiredValue",
        "target": "fiscalDocumentType",
        "value": "model.isPortugueseCompany == true"
    }
    ...

Regra para obrigatório do tipo de documento fiscal quando uma empresa é portuguesa.

• Loading de campos da view

    ...
    {
        "field": "payableAmount",
        "actions": [
            {
                "actionType": "LoadingDependencies",
                "attributes": [ "serie", "documentLines.quantity", "documentLines.unitPrice", "documentLines.discount1", "documentLines.salesItem" ]
            }
        ]
    }
    ...

Regra para loading do payableAmount quando um dos atributos da lista é alterado.

• Visibilidade de linhas ou colunas

    ...
    {
        "actionType": "SetVisibilityValue",
        "target": "row_Account_Row",
        "where": "model.usesExternalIdentityProvider === false",
        "value": "true"
    }
    ...

Regra para visibilidade a true quando provider não é externo.

• Bloquear ação de delete

    ...
    {
        "actionType": "SetDisabledValue",
        "target": "action_delete",
        "value": "model.autoCreated === true"
    }
    ...

Regra para bloquear a ação de delete quando documento é auto created.

Execução das regras

O serviço de motor de regras existente na versão 3 acabou, na versão 4, usamos o motor do ng-formy para aplicar as expressões aos campos. Ou seja, existe uma tradução no momento inicial para traduzir as regras para expressões angular e é atribuída essa expressão às variáveis do FormField do ng-formy.

Regras de UI definidas ao nível do Presentation Model

Atualmente, as regras de UI podem ser definidas tanto no ficheiro de regras como ao nível do Presentation Model. No entanto, se existir uma regra definida na modelação as regras definidas no ficheiro de regras serão ignoradas.

• Regras de UI para visibilidade de campos

Para definir regras de UI para a visibilidade de campos no Presentation Model basta aceder ao modelo, abrir o editor view layout e associar a expressão que será utilizada para a regra ao campo, coluna, linha, expander ou grelha pretendida.

Exemplo de aplicação de regra de UI para a visibilidade de coluna:

Neste caso, o que acontece, é que na view de sequências, a coluna entidade (e, por sua vez, o campo que esta coluna contém), apenas será visível caso o campo "Tipo de Segmento" tenha o valor 1 (Entidade).

A visibilidade de ações também pode ser condicionada através de regras de UI neste modelo, bastando selecionar a ação pretendida no editor operation e aplicar a expressão pretendida. A ação apenas ficará visível quando a expressão definida for verdadeira.

No entanto, podem existir cenários em que a visibilidade de campos esteja definida tanto a nível de regras de UI como a nível da associação de claims.

Nota: Para mais informação acerca do condicionamento de visibilidade de campos através de claims consultar o documento Subscription Claims.

Para estes casos, a visibilidade do campo está condicionada tanto pela existência da claim associada ao campo na subscrição, como pela verificação da expressão definida na regra de UI. Caso não se verifiquem ambas as condições, o campo não ficará visível.

• Regras de UI para a obrigatoriedade de campos

A definição da obrigatoriedade de campos pode, igualmente, ser definida no presentation model, acedendo ao editor layout da view e selecionando o campo ao qual se pretende associar a respetiva expressão.

• Regras de UI para desabilitação de campos

Relativamente à desabilitação de campos, a mesma pode ser efetuada ao aceder ao presentation model e definir a expressão a aplicar no editor de layout da view. A aplicação destas regras apenas pode ser efetuada a campos, grelhas, bem como a ações, no respetivo editor operation.

• Regras de UI aplicadas a operações da grelha

As operações de clonagem, remoção e inserção de linha acima, disponíveis nas grelhas também podem ser condicionadas no presentation model. Assim, quando se pretende que determinada operação na grelha seja condicionada por regras de UI, basta aceder ao editor view layout, selecionar a grelha, e na propriedade respetiva associar a expressão que condicionará a disponibilidade da operação.