Roteamento

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.

Rotas estáticas

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:

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:

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
$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();

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.

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:

./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:

{
  "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.

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:

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.