Pontos de Entrada para fontes Advpl desenvolvidos utilizando o conceito MVC
Pontos de entrada são uma forma de personalizar rotinas, funções e procedimentos do Microsiga Protheus.Os pontos de entrada recebem parametros através da variável PARAMIXB, conforme a documentação do mesmo.Os pontos de entrada retornam valores como uma função Advpl. Caso o retorno do ponto de entrada seja diferente do especificado na documentação a rotina poderá ser abortada.
A idéia de ponto de entrada, para fontes desenvolvidos utilizando-se o conceito de MVC e suas classes, é um pouco diferente dos fontes desenvolvidos de maneira convencional.
Nos fontes convencionais temos um "nome" para cada ponto de entrada criado, por exemplo, na rotina MATA010 – Cadastro de Produtos temos os pontos de entrada: MT010BRW, MTA010OK, MT010CAN, etc. Em MVC, não é desta forma. Em MVC criamos um único ponto de entrada e este é chamado em vários momentos dentro do fonte desenvolvido.
Este ponto de entrada único deve ser uma User Function e ter como nome o ID do Modelo de Dados (Model) do Fonte. Peguemos de exemplo um fonte do Modulo Jurídico: JURA001. Neste fonte o ID do Modelo de Dados ( definido na funcão ModelDef() ) é também JURA001, portanto ao se escrever o ponto de entrada desta rotina, faríamos:
User Function JURA001()
Local aParam := PARAMIXB
Local xRet := .T.
...
Return xRet
O ponto de entrada criado recebe via parâmetro (PARAMIXB) um vetor com informações referentes ao fonte. Estes parâmetros variam para cada situação, em comum todos eles tem os 3 primeiros elementos que são listados abaixo, no quadro seguinte existe a relação de parâmetros de cada ID:
Posições do array de parâmetros comuns a todos os IDs:
| POS. | TIPO | DESCRIÇÃO |
| 1 | O | Objeto do formulário ou do modelo, conforme o caso |
| 2 | C | ID do local de execução do ponto de entrada |
| 3 | C | ID do formulário |
Como já foi dito, o ponto de entrada é chamado em vários momentos dentro do fonte, na 2ª posição da estrutura do vetor é passado um ID que identifica qual é este momento. Ela pode ter como conteúdo:
| ID | MOMENTO DE EXECUÇÃO DO PONTO DE ENTRADA |
| MODELPRE | Antes da alteração de qualquer campo do modelo. Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário Retorno: Requer um retorno lógico |
| MODELPOS | Na validação total do modelo. Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário Retorno: Requer um retorno lógico |
| FORMPRE | Antes da alteração de qualquer campo do formulário. Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário Retorno: Requer um retorno lógico |
| FORMPOS | Na validação total do formulário. Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário Retorno: Requer um retorno lógico |
| FORMLINEPRE | Antes da alteração da linha do formulário FWFORMGRID. Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário 4 N Número da Linha da FWFORMGRID 5 C Ação da FWFORMGRID 6 C Id do campo Retorno: Requer um retorno lógico |
| FORMLINEPOS | Na validação total da linha do formulário FWFORMGRID. Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário 4 N Número da Linha da FWFORMGRID Retorno: Requer um retorno lógico |
| MODELCOMMITTTS | Após a gravação total do modelo e dentro da transação. Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário Retorno: Não espera retorno |
| MODELCOMMITNTTS | Após a gravação total do modelo e fora da transação. Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário Retorno: Não espera retorno |
| FORMCOMMITTTSPRE | Antes da gravação da tabela do formulário. Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário 4 L Se .T. indica novo registro (Inclusão) se .F. registro já existente (Alteração / Exclusão) Retorno: Não espera retorno |
| FORMCOMMITTTSPOS | Após a gravação da tabela do formulário. Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário 4 L Se .T. indica novo registro (Inclusão) se .F. registro já existente (Alteração / Exclusão) Retorno: Não espera retorno |
| FORMCANCEL | No cancelamento do botão. Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário Retorno: Requer um retorno lógico |
| BUTTONBAR | Para a inclusão de botões na ControlBar. Para criar os botões deve-se retornar um array bi-dimensional com a seguinte estrutura de cada item: 1 C Titulo para o botão 2 C Nome do Bitmap para exibição 3 B CodeBlock a ser executado 4 C ToolTip (Opcional) Parâmetros Recebidos: 1 O Objeto do formulário ou do modelo, conforme o caso 2 C ID do local de execução do ponto de entrada 3 C ID do formulário Retorno: Requer um array de retorno com estrutura pré definida |
Observações:
· Quando o modelo de dados possui vários componentes (por exemplo, vários FWFORMGRIDs), a 3ª posição do vetor trará o ID deste componente
· Quando o tipo de retorno de um determinado momento de execução não for passado ou for passado com o tipo errado será exibida uma mensagem no console avisando sobre isso. Todos IDs que esperam retorno devem ser tratado no ponto de entrada
· Ao se escrever um fonte em MVC que será uma User Function, cuidado ao se atribuir o ID do modelo de dados (Model), pois ele não poderá ter o mesmo nome do fonte. Se o fonte tiver o nome FONT001, o ID do Modelo de Dados (Model) não poderá ser também FONT001,
Exemplo:
User Function JURA001()
Local aParam := PARAMIXB
Local xRet := .T.
Local oObj := ''
Local cIdPonto := ''
Local cIdModel := ''
Local lIsGrid := .F.
Local nLinha := 0
Local nQtdLinhas := 0
Local cMsg := ''
If aParam <> NIL
oObj := aParam[1]
cIdPonto := aParam[2]
cIdModel := aParam[3]
lIsGrid := ( Len( aParam ) > 3 )
If lIsGrid
nQtdLinhas := oObj:GetQtdLine()
nLinha := oObj:nLine
EndIf
If cIdPonto == 'MODELPOS'
cMsg := 'Chamada na validação total do modelo (MODELPOS).' + CRLF
cMsg += 'ID ' + cIdModel + CRLF
If !( xRet := ApMsgYesNo( cMsg + 'Continua ?' ) )
Help( ,, 'Help',, 'O MODELPOS retornou .F.', 1, 0 )
EndIf
ElseIf cIdPonto == 'FORMPOS'
cMsg := 'Chamada na validação total do formulário (FORMPOS).' + CRLF
cMsg += 'ID ' + cIdModel + CRLF
If cClasse == 'FWFORMGRID'
cMsg += 'É um FORMGRID com ' + Alltrim( Str( nQtdLinhas ) ) + ;
' linha(s).' + CRLF
cMsg += 'Posicionado na linha ' + Alltrim( Str( nLinha ) ) + CRLF
ElseIf cClasse == 'FWFORMFIELD'
cMsg += 'É um FORMFIELD' + CRLF
EndIf
If !( xRet := ApMsgYesNo( cMsg + 'Continua ?' ) )
Help( ,, 'Help',, 'O FORMPOS retornou .F.', 1, 0 )
EndIf
ElseIf cIdPonto == 'FORMLINEPRE'
If aParam[5] == 'DELETE'
cMsg := 'Chamada na pre validação da linha do formulário (FORMLINEPRE).' + CRLF
cMsg += 'Onde esta se tentando deletar uma linha' + CRLF
cMsg += 'É um FORMGRID com ' + Alltrim( Str( nQtdLinhas ) ) +;
' linha(s).' + CRLF
cMsg += 'Posicionado na linha ' + Alltrim( Str( nLinha ) ) +; CRLF
cMsg += 'ID ' + cIdModel + CRLF
If !( xRet := ApMsgYesNo( cMsg + 'Continua ?' ) )
Help( ,, 'Help',, 'O FORMLINEPRE retornou .F.', 1, 0 )
EndIf
EndIf
ElseIf cIdPonto == 'FORMLINEPOS'
cMsg := 'Chamada na validação da linha do formulário (FORMLINEPOS).' +; CRLF
cMsg += 'ID ' + cIdModel + CRLF
cMsg += 'É um FORMGRID com ' + Alltrim( Str( nQtdLinhas ) ) + ;
' linha(s).' + CRLF
cMsg += 'Posicionado na linha ' + Alltrim( Str( nLinha ) ) + CRLF
If !( xRet := ApMsgYesNo( cMsg + 'Continua ?' ) )
Help( ,, 'Help',, 'O FORMLINEPOS retornou .F.', 1, 0 )
EndIf
ElseIf cIdPonto == 'MODELCOMMITTTS'
ApMsgInfo('Chamada apos a gravação total do modelo e dentro da transação (MODELCOMMITTTS).' + CRLF + 'ID ' + cIdModel )
ElseIf cIdPonto == 'MODELCOMMITNTTS'
ApMsgInfo('Chamada apos a gravação total do modelo e fora da transação (MODELCOMMITNTTS).' + CRLF + 'ID ' + cIdModel)
//ElseIf cIdPonto == 'FORMCOMMITTTSPRE'
ElseIf cIdPonto == 'FORMCOMMITTTSPOS'
ApMsgInfo('Chamada apos a gravação da tabela do formulário (FORMCOMMITTTSPOS).' + CRLF + 'ID ' + cIdModel)
ElseIf cIdPonto == 'MODELCANCEL'
cMsg := 'Chamada no Botão Cancelar (MODELCANCEL).' + CRLF + 'Deseja Realmente Sair ?'
If !( xRet := ApMsgYesNo( cMsg ) )
Help( ,, 'Help',, 'O MODELCANCEL retornou .F.', 1, 0 )
EndIf
ElseIf cIdPonto == 'BUTTONBAR'
ApMsgInfo('Adicionando Botao na Barra de Botoes (BUTTONBAR).' + CRLF + 'ID ' + cIdModel )
xRet := { {'Salvar', 'SALVAR', { || Alert( 'Salvou' ) }, 'Este botao Salva' } }
EndIf
EndIf
Return xRet