# 5. Uso do Modo Editor

Use o **Modo Editor** para ajustes “cirúrgicos” no que a IA gerou. Use o **Chat AI** para mudanças maiores, com várias telas e regras.

{% hint style="info" %}
Se você quer a referência completa (tipos de campo, eventos e estrutura), veja também [**Modo Editor**](https://docs.madrix.dev/br/documentacao/modo-editor).
{% endhint %}

### Pré-requisitos

* Você tem permissão de edição no projeto.
* Seu app abre no **Preview**.

### Backend (exemplo final)

Objetivo do exemplo: um módulo **Gestor de Tarefas** com entidade **Tarefa**, campos comuns, relacionamento e regra de status.

{% stepper %}
{% step %}

### 1) Ajuste o módulo e menus

No Editor, abra **Módulos** e edite (ou crie) um módulo:

* **Nome do módulo:** `Tarefas`
* **Ícone:** escolha um que facilite identificar o card.
* **Display Name Translations:**
  * `pt-BR`: `Tarefas`

Crie um menu dentro do módulo:

* **Nome:** `Minhas tarefas`
* **URL Path:** `/tarefas`

{% hint style="warning" %}
Evite trocar **URL Path** depois. Isso quebra links e favoritos.
{% endhint %}

**Resultado esperado:** o card do módulo aparece na Home. O menu navega.
{% endstep %}

{% step %}

### 2) Crie/ajuste o componente (entidade)

Crie um **Componente**:

* **Nome (lowercase):** `tarefa`
* **Módulo:** `Tarefas`
* **Display Name Translations:**
  * `pt-BR`: `Tarefa`

Ao salvar, use estas opções (quando aparecerem):

* **Create frontend files:** sim (se você quer scaffold de telas)
* **Create menu automatically:** opcional (se você já criou o menu manualmente)

**Resultado esperado:** o componente existe e já tem estrutura de UI (se marcado).
{% endstep %}

{% step %}

### 3) Modele campos (com exemplos prontos)

Dentro de `tarefa`, crie os campos abaixo:

* `titulo`
  * **Tipo:** `String`
  * **Obrigatório:** sim
* `descricao`
  * **Tipo:** `Text`
* `status`
  * **Tipo:** `Picklist`
  * **Opções:** `Novo | Em Progresso | Revisão | Concluído`
  * **Obrigatório:** sim
* `prioridade`
  * **Tipo:** `Picklist`
  * **Opções:** `Baixa | Média | Alta`
* `dataVencimento`
  * **Tipo:** `Date`
* `atribuidoA`
  * **Tipo:** `User`
* `anexos`
  * **Tipo:** `Attachments`

Dica rápida:

* Se a lista ficar “apertada”, ajuste a **Largura na grid** por campo.

**Resultado esperado:** o form de Tarefa tem todos os campos. A lista exibe os principais.
{% endstep %}

{% step %}

### 4) Adicione um relacionamento (1-N) com Projeto

Crie um segundo componente:

* **Nome:** `projeto`
* Campos mínimos:
  * `nome` (`String`, obrigatório, único)

Agora volte para `tarefa` e crie um campo:

* `projeto`
  * **Tipo:** `Component`
  * **Componente relacionado:** `projeto`
  * **Cardinalidade:** 1 (uma tarefa pertence a um projeto)
  * **Display Field:** `nome`

{% hint style="danger" %}
Só marque `deleteCascade` se você aceitar apagar dados em massa.
{% endhint %}

**Resultado esperado:** no form de Tarefa, você seleciona um Projeto.
{% endstep %}

{% step %}

### 5) Crie uma consulta reaproveitável (opcional, mas útil)

Em `tarefa`, crie uma **Consulta** chamada `Atrasadas`:

* Filtro: `dataVencimento` menor que hoje
* E `status` diferente de `Concluído`

**Resultado esperado:** você reaproveita esse filtro em listas e relatórios.
{% endstep %}

{% step %}

### 6) Regra de negócio via Script (sem “código” no frontend)

Regra do exemplo: **não permitir voltar status**.

Implemente como script no evento do componente `tarefa`:

* Evento recomendado: **Before Update**
* Validação:
  * Permitir apenas avanço: `Novo → Em Progresso → Revisão → Concluído`
  * Bloquear qualquer regressão
* Mensagem de erro clara:
  * “Não é permitido voltar o status.”

Teste no Preview:

* Crie uma tarefa em `Novo`
* Avance para `Em Progresso`
* Tente voltar para `Novo` e valide o bloqueio

**Resultado esperado:** a regra funciona no backend. Vale para UI e API.
{% endstep %}
{% endstepper %}

### Frontend (scaffold gerado)

O scaffold só existe se você marcou **Create frontend files** ao salvar o componente.

#### O que você ganha (resumo)

* Rotas base do app.
* Páginas protegidas por módulo.
* Forms e listas gerados por componente.
* Tema e estilos base.

<details>

<summary>Onde normalmente ficam as telas do seu módulo</summary>

Procure por uma estrutura como:

* `pages/protected/`
  * `{modulo}/` (ex: `tarefas/`)
    * telas de listar, criar e editar

</details>

#### O que editar vs o que evitar

Edite com segurança:

* Páginas do módulo (telas).
* Componentes de UI do seu app.
* Tema (cores, tipografia).

Evite editar:

* Arquivos marcados como **locked** (gerenciados pela plataforma).

#### Checklist de validação (Preview)

* [ ] Card do módulo aparece na Home.
* [ ] Menu abre a listagem.
* [ ] Criar/editar Tarefa funciona.
* [ ] Picklists têm as opções corretas.
* [ ] Relacionamento com Projeto seleciona e salva.
* [ ] Regra de status bloqueia regressão.

{% hint style="info" %}
Se o objetivo é mexer só em tema e textos, isso costuma ser mais rápido em **Configurações do Projeto**.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.madrix.dev/br/tutoriais-praticos/5.-uso-do-modo-editor.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.