# Recursos

Dados definidos uma vez num arquivo .meta, com admin, API, permissões e histórico.

Um recurso é um tipo de dado: projetos, membros, pedidos, páginas. Você o descreve uma vez num arquivo `.meta`, e o Nimbly fornece, a partir dessa descrição, o armazenamento, as telas do admin, os formulários, a API, as permissões e o histórico.

## Registros são arquivos

```text
ext/data/projects/
  .meta                 the definition
  4f1c9a2e7b...         one record, as JSON
  9d03b6e1c4...         another record
```

Cada registro é um arquivo JSON com o id como nome, uma sequência aleatória como `1ztuvo56o5vze6t0` que é a mesma em todos os ambientes. Não há servidor de banco de dados: um recurso pode ser lido, copiado, versionado no Git e restaurado como uma pasta. Por que o Nimbly funciona assim, e o que isso significa para um projeto, está em [Dados como arquivos](/pt/docs/concepts/data-as-files/). Todo registro também ganha `uuid`, `_created`, `_modified`, `_created_by` e `_modified_by`, mantidos pelo Nimbly.

## A definição

```json
{
  "name": {"singular": "Project", "plural": "Projects"},
  "fields": {
    "title": {"name": "Title", "type": "text", "required": true},
    "title_slug": {"name": "URL slug", "type": "slug", "source": "title"},
    "sector": {"name": "Sector", "type": "select", "options": {"culture": "Culture", "retail": "Retail"}},
    "published": {"name": "Published", "type": "boolean", "admin_filter": true},
    "cover": {"name": "Cover", "type": "image", "admin_col": false},
    "description": {"name": "Description", "type": "html", "buttons": "bold,italic,anchor", "admin_col": false}
  },
  "index": ["title_slug"],
  "sort": {"field": "title", "order": "asc"}
}
```

Os campos têm um tipo (text, html, date, select, image, gallery, file, number, boolean, location e mais), um rótulo, validação e configurações para o admin. Um `select` pode buscar suas opções em outro recurso; é assim que os recursos se referem uns aos outros. As referências de [tipos de campo](/pt/docs/reference/field-types/) e [metadados de recursos](/pt/docs/reference/metadata/) listam todas as opções.

## O que uma definição dá a você

| Você ganha | Onde |
|---|---|
| Uma visão geral com colunas, busca, filtros e paginação | `/nb-admin/<resource>` |
| Formulários para adicionar e editar, com validação | o admin, e qualquer formulário que você construir sobre o recurso |
| Uma API REST para listar, ler, criar, alterar e excluir | `/api/v1/<resource>` |
| Permissões por operação e função | `view-`, `create-`, `edit-`, `delete-` e `manage-<resource>` |
| Histórico de cada alteração, com restauração | o painel de ações do registro no admin |
| Busca por valor de campo | a lista `index` |

## Lendo dados

Num template:

```html
[#data projects filter=published:1 sort=year|numeric|desc limit=12#]
[#repeat data.projects tpl=card-project#]
```

Em PHP, `data_read()` lê um registro, `data_read_index()` encontra registros por um campo indexado e `data_query()` devolve uma página filtrada e ordenada com o total. As gravações passam por `data_create()`, `data_update()` e `data_delete()`, que validam, atualizam os índices e registram o histórico.

## Desempenho em escala

- **Índices.** Um campo listado em `index` ganha um caminho de busca, para que um slug num endereço encontre seu registro sem ler o recurso.
- **Cache de listas.** Filtros e ordenações guardam os valores dos campos envolvidos num arquivo de cache por campo, para que uma página de resultados leia só os registros dessa página.
- **Cache de consultas.** Os resultados das consultas ficam em cache e são invalidados a cada escrita, venha ela do site, da API, do Git ou de uma sincronização.
- **Diretórios divididos.** `"splitdir": true` espalha os arquivos de um recurso grande por subpastas.

Com diretórios divididos e índices, um recurso suporta cerca de 100.000 registros.

## Eventos

Um recurso pode declarar o que acontece depois que um registro é criado, alterado ou excluído: executar uma função, ou colocar um job em segundo plano na fila, como um e-mail de confirmação após o envio de um formulário. Veja [Trabalho em segundo plano](/pt/docs/guides/jobs/).

## Recursos ocultos

Um recurso cujo nome começa com um ponto, como `.config` ou `.content`, fica fora da visão geral de dados do admin. O Nimbly os usa para configurações do site, conteúdo das páginas, rotas e a fila de jobs.