advpl-mvc

Files (7)

• SKILL.md
• custom.mvc.confirmationOfReceipt.tlpp · exemplos/
• custom.mvc.customers.tlpp · exemplos/
• custom.mvc.monitors.tlpp · exemplos/
• custom.mvc.quote.tlpp · exemplos/
• custom.mvc.transferOrder.tlpp · exemplos/
• reference.md

SKILL.md (first lines)

# advpl-mvc — Framework MVC do Protheus

A partir do release 11 da TOTVS, cadastros e processos no Protheus passaram a usar o framework **MVC** (FWMVC). Antes era `AxCadastro`/`Modelo2`/`Modelo3` — hoje deprecado (`MOD-004`).

Uma rotina MVC tem **3 funções estáticas obrigatórias** + um menu:

- `MenuDef()` → retorna `aRotina` (entradas de menu, ações disponíveis).
- `ModelDef()` → retorna `oModel` (estrutura de dados, validações, hooks).
- `ViewDef()` → retorna `oView` (interface gráfica, vinculação ao model).

## Quando usar

- Usuário pede para criar/editar cadastro Protheus (CRUD).
- Edit em arquivo cujo nome bate com pattern de cadastro novo (rotina nova) ou usuário menciona "MVC", "ModelDef", "ViewDef".
- Adicionar validação a cadastro existente — quase sempre via hook do model.
- Consultar `/plugadvpl:tables` retornou um cadastro MVC.

## Estrutura mínima

```advpl
#include "TOTVS.CH"

User Function XYZCAD()
    Local oBrowse := FWMBrowse():New()
    oBrowse:SetAlias("ZZZ")
    oBrowse:SetMenuDef("XYZCAD")
    oBrowse:SetDescription("Cadastro XYZ")
    oBrowse:Activate()
Return Nil

Static Function MenuDef()
    Local aRotina := {}
    aAdd(aRotina, {"Pesquisar",  "AxPesqui",          0, 1, 0, .F.})
    aAdd(aRotina, {"Visualizar", "VIEWDEF.XYZCAD",    0, 2, 0, .F.})
    aAdd(aRotina, {"Incluir",    "VIEWDEF.XYZCAD",    0, 3, 0, .F.})
    aAdd(aRotina, {"Alterar",    "VIEWDEF.XYZCAD",    0, 4, 0, .F.})
    aAdd(aRotina, {"Excluir",    "VIEWDEF.XYZCAD",    0, 5, 0, .F.})
Return aRotina

Static Function ModelDef()
    Local oModel    := MPFormModel():New("XYZCADMD", , {|oModel| MyTudoOk(oModel)}, {|oModel| MyCommit(oModel)})
    Local oStruZZZ  := FWFormStruct(1, "ZZZ")

    oModel:AddFields("ZZZMASTER", , oStruZZZ)
    oModel:GetModel("ZZZMASTER"):SetPrimaryKey({"ZZZ_FILIAL", "ZZZ_COD"})

    oModel:SetVldActivate({|oModel| MyPreVld(oModel)})
    oModel:GetModel("ZZZMASTER"):SetPosValidation({|oModel| MyPosVld(oModel)})

Return oModel

Static Function ViewDef()
    Local oModel  := FWLoadModel("XYZCAD")
    Local oView   := FWFormView():New()
    Local oStruZZZ := FWFormStruct(2, "ZZZ")

    oView:SetModel(oModel)
    oView:AddField("VIEW_ZZZ", oStruZZZ, "ZZZMASTER")
    oView:CreateHorizontalBox("PRINCIPAL", 100)
    oView:SetOwnerView("VIEW_ZZZ", "PRINCIPAL")

Return oView
```

## `aRotina` — formato de cada linha

```advpl
{Descricao, FuncaoAcionada, Reservado, OPERACAO, Acesso, Pula}
```

Campo **OPERACAO** (4ª posição):

| Valor | Operação      | Constante `MODEL_OPERATION_*` |
|-------|---------------|-------------------------------|
| 1     | Pesquisar     | —                             |
| 2     | Visualizar    | `MODEL_OPERATION_VIEW` (1)    |
| 3     | Incluir       | `MODEL_OPERATION_INSERT` (3)  |
| 4     | Alterar       | `MODEL_OPERATION_UPDATE` (4)  |
| 5     | Excluir       | `MODEL_OPERATION_DELETE` (5)  |
| 8     | Imprimir      | —                             |
| 9     | Copiar        | `MODEL_OPERATION_INSERT`      |

Nota: em código de hooks use as **constantes** (mais legível): `if oModel:GetOperation() == MODEL_OPERATION_INSERT`.

## `FWFormStruct(1, alias)` × `FWFormStruct(2, alias)`

- `FWFormStruct(1, "ZZZ")` → estrutura para **MODEL** (campos, validações, gatilhos).
- `FWFormStruct(2, "ZZZ")` → estrutura para **VIEW** (apresentação, ordem visual, agrupamentos).

A estrutura é lida do **SX3** (dicionário). Customizações ad-hoc (esconder campo, mudar default) usam métodos `:AddField()`, `:SetProperty()`, `:RemoveField()` na estrutura.

## Hooks — o coração da customização

Hooks são code blocks (`{|oModel| ...}`) executados em momentos específicos do ciclo de vida. Para customizar comportamento sem alterar fontes TOTVS, **adicione hooks via PE** (`<Rotina>MOD` ou similar) ou no próprio model.

| Hook                    | Quando executa                                | Onde plugar                                   |
|-------------------------|-----------------------------------------------|-----------------------------------------------|
| `SetVldActivate`        | Antes do model abrir                          | Validação prévia (ex: usuário tem acesso?)    |
| `bPreVld` / `SetPreValidation` | Antes de validar o sub-model           | Bloquear edição condicional                   |
| `bLineOk` / `SetLinePre/PostValidation` | Linha (grids) validada               | Validação por linha em grid                   |
| `bPosVld` / `SetPosValidation` | Depois de validar o sub-model           | Validação cross-campo do sub-model            |
| `bTudoOk`               | Validação geral do model inteiro              | Validação que cruza todos os sub-models       |
| `bCommit`               | Imediatamente antes do COMMIT no banco        | Atualizar tabelas auxiliares, log de auditoria|
| `OnAfterCommit`         | Depois do COMMIT bem sucedido                 | Notificações, e-mails, integrações externas   |

Exemplo de hook de commit:

```advpl
Static Function MyCommit(oModel)
    Local lOk := .T.
    Local cCod := oModel:GetValue("ZZZMASTER", "ZZZ_COD")

    Begin Sequence
        // Grava log de auditoria
        RecLock("ZZL", .T.)
        ZZL->ZZL_FILIAL := xFilial("ZZL")
        ZZL->ZZL_COD    := cCod
        ZZL->ZZL_DTHR   := DtoS(Date()) + Time()
        MsUnlock()

From replybr/plugadvpl, MIT.

More from replybr/plugadvpl