> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doglytdc.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar uma função

> Passo a passo para criar uma função do Painel Dev com tela, item no menu, ligação e traduções, com três exemplos completos.

Uma função é uma pasta em `painel-dev/funcoes/<id>/` com dois arquivos. O `<id>` é o nome da pasta e também o endereço: `?tab=<id>`.

**1. Escolha o id**

Minúsculas, números e `-`, de 2 a 32 caracteres, começando com letra. Não pode ser o id de uma função fixa (`home`, `code`, `sales`…).

**2. Crie funcao.json**

O item do menu (`@nav`) e de onde vêm os dados (`connect`).

**3. Crie tela.html**

O desenho, com as [peças](https://docs.doglytdc.dev/pt-BR/scripts/dev-panel/pieces.md).

**4. Adicione os textos**

Cada `@t.chave` nova em todos os arquivos de `traducoes/`.

**5. Valide e faça merge**

`dev_panel_validate` na branch, depois merge na main. Ou use `dev_panel_function_create` no MCP, que cria a pasta e valida de uma vez.

## funcao.json

| Campo | Regra |
| - | - |
| `@nav.id` | Igual ao nome da pasta |
| `@nav.label` | Até 40 caracteres ou `@t.chave` |
| `@nav.icon` | Um nome da lista de ícones |
| `@nav.position` | Inteiro de 1 a 999 |
| `@nav.group` | Opcional. Sem ele, vai para **Funções do painel** |
| `description` | Opcional, até 160 caracteres |
| `connect` | Obrigatório. Veja [Ligações e ações](https://docs.doglytdc.dev/pt-BR/scripts/dev-panel/connections.md) |

Limite: **30 funções** por script.

## Exemplo 1 — Avisos (configuração)

Edita campos da configuração remota do script. O script lê esses valores em `window.DoglyScript.config`.

```json painel-dev/funcoes/avisos/funcao.json theme={null}
{
  "@nav": { "id": "avisos", "label": "@t.aviso.titulo", "icon": "megaphone", "position": 100 },
  "description": "Mensagem que aparece para quem usa o script.",
  "connect": { "type": "config", "keys": ["aviso_ativo", "aviso_texto", "aviso_tipo", "aviso_cor"] }
}
```

```html painel-dev/funcoes/avisos/tela.html theme={null}
<section class="dt-stack">
  <h2>@t.aviso.titulo</h2>
  <p>@t.aviso.descricao</p>
  <dt-switch bind="aviso_ativo" label="@t.aviso.ativo" />
  <dt-textarea bind="aviso_texto" label="@t.aviso.texto" placeholder="@t.aviso.placeholder" />
  <dt-select bind="aviso_tipo" label="@t.aviso.tipo">
    <dt-option value="info" label="@t.aviso.tipo.info" />
    <dt-option value="alerta" label="@t.aviso.tipo.alerta" />
  </dt-select>
  <dt-color bind="aviso_cor" label="@t.aviso.cor" hint="@t.aviso.cor.dica" />
  <footer>
    <dt-button action="@reload" label="@t.comum.recarregar" tone="ghost" icon="refresh" />
    <dt-button action="@save" label="@t.comum.salvar" icon="check" />
  </footer>
</section>
```

Cada `bind` precisa estar em `connect.keys`. O painel só lê e salva esses campos; o resto da configuração não é tocado.

## Exemplo 2 — Cupons (função do servidor)

Chama uma função do servidor do script, que decide o que mostrar e o que fazer em cada botão.

```json painel-dev/funcoes/cupons/funcao.json theme={null}
{
  "@nav": { "id": "cupons", "label": "@t.cupons.titulo", "icon": "ticket", "group": "Pessoas", "position": 45 },
  "description": "Cria e lista cupons de desconto.",
  "connect": { "type": "function", "name": "cupons" }
}
```

```html painel-dev/funcoes/cupons/tela.html theme={null}
<section class="dt-stack">
  <h2>@t.cupons.titulo</h2>
  <div class="dt-grid">
    <dt-stat bind="ativos" label="@t.cupons.ativos" icon="ticket" />
    <dt-stat bind="usos" label="@t.cupons.usos" icon="chart" />
  </div>
  <dt-text bind="codigo" label="@t.cupons.codigo" placeholder="BEMVINDO10" />
  <dt-select bind="tipo" label="@t.cupons.tipo" placeholder="@t.cupons.tipo.escolher">
    <dt-option value="pct" label="@t.cupons.tipo.pct" />
    <dt-option value="valor" label="@t.cupons.tipo.valor" />
  </dt-select>
  <dt-number bind="desconto" label="@t.cupons.desconto" min="1" max="100" step="1" />
  <dt-button action="@call:criar" label="@t.cupons.criar" icon="plus" />
  <hr />
  <dt-table bind="lista" columns="codigo,tipo,desconto,usos" empty="@t.cupons.vazio" />
</section>
```

O que acontece em cada botão está em [Ligações e ações](https://docs.doglytdc.dev/pt-BR/scripts/dev-panel/connections.md#function-função-do-servidor).

## Exemplo 3 — Relatório (coleção, só leitura)

Mostra até 100 registros de uma coleção do script. Coleções são **só leitura** no Painel Dev: só `dt-table`, `dt-stat` e `@reload`.

```json painel-dev/funcoes/relatorio/funcao.json theme={null}
{
  "@nav": { "id": "relatorio", "label": "@t.relatorio.titulo", "icon": "bar-chart", "position": 110 },
  "connect": { "type": "collection", "name": "acessos" }
}
```

```html painel-dev/funcoes/relatorio/tela.html theme={null}
<section class="dt-stack">
  <header>
    <h2>@t.relatorio.titulo</h2>
    <dt-button action="@reload" label="@t.comum.recarregar" tone="ghost" icon="refresh" />
  </header>
  <dt-alert tone="info">@t.relatorio.aviso</dt-alert>
  <dt-table bind="itens" columns="usuario,pagina,quando" empty="@t.relatorio.vazio" />
</section>
```

## Os textos

```json painel-dev/traducoes/pt-BR.json theme={null}
{
  "@lang": "Português (BR)",
  "aviso.titulo": "Avisos",
  "aviso.descricao": "Mensagem mostrada para quem usa o script.",
  "aviso.ativo": "Mostrar aviso",
  "aviso.texto": "Texto",
  "aviso.placeholder": "Ex.: Nova versão disponível!",
  "aviso.tipo": "Tipo",
  "aviso.tipo.info": "Informação",
  "aviso.tipo.alerta": "Alerta",
  "aviso.cor": "Cor",
  "aviso.cor.dica": "Cor da faixa do aviso.",
  "comum.salvar": "Salvar",
  "comum.recarregar": "Recarregar",
  "cupons.titulo": "Cupons",
  "cupons.criar": "Criar cupom",
  "relatorio.titulo": "Relatório"
}
```

Faça o mesmo em `en.json`, `es.json` e nos idiomas extras. A tela **Traduções** mostra as chaves que faltam.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.