# Roteamento

Pastas como endereços, rotas dinâmicas, idiomas e subdomínios.

A estrutura de pastas de `ext/uri/` é a estrutura de URLs do site. Uma pasta é um endereço; o `index.tpl` dela o responde.

Cada rota é uma tela em branco: o que o template produz é a resposta. Pode ser a página padrão via `[#html#]`, um documento HTML seu, JSON, XML, um arquivo ou qualquer outra coisa. Veja [O que uma rota devolve](/pt/docs/guides/responses/).

## Rotas estáticas

```text
ext/uri/index.tpl                 /
ext/uri/about/index.tpl           /about
ext/uri/en/contact/index.tpl      /en/contact
ext/uri/feed.xml/index.tpl        /feed.xml
```

Uma rota estática não precisa de mais nada: nem registro, nem `route.inc`. O nome da pasta pode conter um ponto, então uma rota pode responder num endereço como `/feed.xml` ou `/llms.txt`.

Uma pasta de rota normalmente contém:

| Arquivo | Papel |
|---|---|
| `index.tpl` | Roda primeiro. Define variáveis da página e gera a resposta, normalmente com `[#html#]` |
| `main.tpl` | O corpo da página dentro da shell |
| `header.tpl`, `footer.tpl` | Cabeçalho e rodapé dentro da shell |
| `index.js` | Script só desta rota, carregado pela shell |
| outros arquivos `.tpl` | Templates usados só por esta rota, como um cartão |

Uma subpasta é sempre uma nova rota. Um arquivo `.tpl` solto ao lado do `index.tpl` é um template só dessa rota, chamado pelo nome.

## Rotas dinâmicas

Um nome de pasta entre parênteses corresponde a qualquer segmento único:

```text
ext/uri/projects/(slug)/index.tpl     /projects/harbour-atlas
ext/uri/(lang)/news/(slug)/           /en/news/opening-day
```

Uma rota dinâmica tem um `route.inc` que decide se a requisição é dela:

```php
<?php
$parts = router_match(__FILE__);
if ($parts === false) return;

$slug = $parts[0];
if (!preg_match('/^[a-z0-9-]{1,120}$/', $slug)) return;

load_library('data');
load_library('util');
$records = data_read_index('projects', 'title_slug', md5_uuid($slug));
if (empty($records)) return;

set_variable_dot('project', reset($records));
router_accept();
```

| Função | Faz |
|---|---|
| `router_match(__FILE__)` | Devolve os valores dos segmentos dinâmicos, ou `false` quando o endereço não corresponde |
| `router_accept()` | Aceita a requisição; o `index.tpl` da rota é executado |
| `router_deny()` | Recusa; a próxima rota é tentada. Retornar sem aceitar tem o mesmo efeito |

Não confie em nenhum valor vindo do endereço. Verifique a sintaxe exata que você aceita, o tamanho e o intervalo antes de usá-lo numa busca, num caminho de arquivo ou num cálculo. Mantenha o `route.inc` em corresponder, verificar e definir uma ou duas variáveis; a lógica de negócio pertence a uma [biblioteca](/pt/docs/concepts/libraries/).

As rotas dinâmicas são registradas no recurso `.routes`, para que o roteador saiba quais pastas consultar. Depois de adicionar ou renomear uma, rode:

```bash
./nimbly routes:sync
```

Uma rota estática nunca tem `route.inc`. A lógica de uma página estática vai num shortcode chamado a partir do `index.tpl` dela.

## Idiomas no endereço

Um site multilíngue normalmente dá a cada idioma seu próprio prefixo, `/en/` e `/nl/`, como pastas em `ext/uri/`. Cada idioma pode ter sua própria estrutura, ou compartilhar templates. Para ligar uma página à equivalente em outro idioma, coloque um `i18n-url.json` ao lado do `index.tpl` dela:

```json
{
  "nl": "nl/projecten/[#get project.title_slug lang=nl#]/",
  "en": "en/projects/[#get project.title_slug lang=en#]/"
}
```

O `[#language-switch#]` gera, a partir desses mapeamentos, links para todos os idiomas do site. Veja [Conteúdo multilíngue](/pt/docs/guides/languages/).

## Subdomínios

Um subdomínio faz parte do site, não é uma instalação separada. As rotas dele ficam numa pasta com o nome dele:

```text
ext/uri/(subdomain-docs)/index.tpl          docs.example.com/
ext/uri/(subdomain-docs)/guide/index.tpl    docs.example.com/guide
```

Aponte o subdomínio para a mesma raiz de documentos; não há mais nada para configurar. Num subdomínio, a pasta dele é procurada primeiro, e tudo o que ela não tem, como o admin, a API e o login, vem do site. Templates, recursos e usuários são compartilhados, e o login também. `[#subdomain-url docs#]` e `[#subdomain-url#]` criam links entre o subdomínio e o site principal. Localmente, `docs.localhost` chega à mesma pasta. Uma página do site principal que também é acessada pelo subdomínio mantém o site principal como endereço canônico. Num site servido a partir de uma subpasta, como um host de staging compartilhado, defina `SUBDOMAIN_HOST` no `.env` para que os links de subdomínio levem ao subdomínio real.

## Scripts de rota

Um `index.js` na pasta de uma rota é carregado pela shell da página só nessa rota. Use-o para o comportamento próprio de uma página, para que ele fique fora do bundle compartilhado.