Shortcodes públicos

Dados

[#data resource#]

Carrega todos os registros de um recurso em data.<resource>.

[#data articles#]
[#data articles sort=date|desc#]
[#data articles filter=published:1#]
[#data articles search=nimbly#]
[#data articles var=featured filter=featured:yes#]
[#data users.abc123#]           → loads single record into data.users.abc123
[#data users uuid=abc123#]      → same
[#data articles filter=published:1 sort=date|text|desc limit=20 offset=40#]   → the third page of 20

Parâmetros:

• sort - field|asc, field|desc, vários: date|desc,title|asc
• filter - field:value, vários: published:1,status:new, negação: status:!draft, ou: status:new||todo
• search - busca no texto completo de todos os campos
• var - nome próprio para a variável em vez de data.<resource>
• op - read (padrão) ou list (só UUIDs)
• limit, offset - uma página da lista: no máximo limit registros, depois de pular offset. O número de registros antes do corte fica em data.<resource>-total (ou <var>-total)

Com limit ou offset, a lista é respondida sem ler todos os registros. Para cada campo citado em filter e sort, os valores de todos os registros ficam juntos num arquivo de cache (ext/data/.tmp/cache/_data/list/<resource>/<field>), criado na primeira vez que o campo é pedido; só os registros da página são lidos. Uma escrita acrescenta uma linha a esses arquivos, um pull do Git faz com que sejam reconstruídos, e ./nimbly data:cache:clear os remove. Use isso em toda lista de um recurso grande; uma ordenação com tipo (date|text|desc, price|num|asc) é a rápida. search continua lendo todos os registros. A partir do PHP: data_query($resource, ['filter' => …, 'sort' => …, 'limit' => 20, 'offset' => 40]) em core/lib/data-list.php devolve ['records' => …, 'total' => …].

[#repeat data.articles#]

Percorre uma variável de dados e exibe, para cada item, o template com o mesmo nome.

[#repeat data.articles#]
[#repeat data.articles tpl=article-card#]
[#repeat data.articles limit=3#]
[#repeat data.articles filter=published:1#]
[#repeat record.related_items csv tpl=related-item#]
[#repeat data.articles var=post#]   → item variable named "post" instead of "item"

Dentro do template, os campos de cada registro estão disponíveis como item.<field>:

<h2>[#get item.title#]</h2>
<p>[#get item.intro#]</p>

Também disponíveis em cada repetição:

• item.ix - índice numérico (a partir de 0)
• item.x - chave do registro
• item.key - chave do registro (string)

Em campos de referência com UUIDs separados por vírgula, não crie uma biblioteca só para carregar uma parte. Carregue o recurso de destino uma vez com [#data#], depois repita a lista de UUIDs com csv e leia da variável do recurso carregado:

[#data participants#]
[#repeat stories.participants csv tpl=story-participant-item#]

<!-- ext/tpl/story-participant-item/index.tpl -->
<a href="[#get data.participants.[#item.key#].link#]">
    [#get data.participants.[#item.key#].name#]
</a>

Isso usa a camada de dados do core e o cache dela, mantém a ordem dos UUIDs do registro de origem e dispensa código de backend próprio para exibir relações simples.

[#data-sort data.articles sort=title|string|asc#]

Ordena uma variável de dados existente no próprio lugar.

[#data-sort data.articles sort=date|desc#]
[#data-sort data.articles sort=title|string|asc#]
[#data-sort data.articles sort=price|numeric|asc#]

[#data-join a b#]

Junta data.a e data.b em data.join. Cada registro ganha um campo resource_type com o nome do recurso de origem.

[#data-count resource#]

Exibe o número de registros de um recurso.

---

Variáveis

[#set key=value#]

Define uma variável de template.

[#set page-title="About us"#]
[#set active-nav=about#]
[#set body-classes=editor-role append#]    → appends with a space separator
[#set tags=news append=,#]                 → appends with a custom separator
[#set key=value session#]                  → persists in session
[#set key=value overwrite#]                → replaces value even if already set

O parâmetro append acrescenta em vez de definir. Sem separador, ele coloca um espaço entre o valor existente e o novo; informe um caractere para usar outro separador. Útil para montar listas de classes CSS ou textos separados por vírgula:

[#set body-classes=site-body#]
[#set body-classes=editor-role append#]    → "site-body editor-role"
[#set body-classes=dark-mode append#]      → "site-body editor-role dark-mode"

[#set#] não sobrescreve por padrão. Se a variável já tem um valor, um [#set#] simples não faz nada. Isso facilita definir valores de reserva em templates compartilhados ou do core, enquanto os templates de rota podem substituí-los antes. Só acrescente overwrite quando quiser substituir de propósito um valor existente (por exemplo, ao passar dados para um template reutilizável).

[#get varname#]

Exibe um valor. [#get#] é a forma única de ler valores.

Ordem de busca:

1. Variável simples: variáveis de sessão, depois variáveis do sistema. A URL e os cookies só são lidos quando o template pede, com from (veja abaixo)
2. Caminho com pontos em variáveis do sistema aninhadas, usando o maior início de variável que corresponda
3. Recurso aos dados para caminhos resource.uuid.field
4. Escolha automática do idioma quando o resultado é um objeto com os códigos de idioma configurados como chaves

A entrada da requisição é opt-in: from=url lê o parâmetro de consulta com o mesmo nome, from=cookie um cookie, from=url,cookie (ou url|cookie) os dois na ordem dada, e from=(any) o cookie e depois a URL. Uma variável de página com esse nome sempre vence. [#if#] aceita o mesmo from nas suas condições.

[#get page-title#]
[#get item.title default="Untitled"#]
[#get q from=url#]
[#get language#]
[#get data.settings.theme#]
[#get users.abc123.name empty="Unknown"#]
[#get item.title lang=nl#]
[#get item json#]

Os padrões antigos [#get-key#], [#jget#], [#get-i18n#] e [#lookup#] devem ser migrados para [#get#].

[#fmt var=data.articles json#]

Formata uma variável para a saída.

[#fmt var=data.records json#]              → JSON encode
[#fmt var=myvar empty={} json#]            → JSON with fallback
[#fmt var=item.date type=date fmt="d-m-Y"#]
[#fmt var=item.body type=html#]            → strips all tags
[#fmt var=item.body type=plain#]           → strips tags and decodes entities
[#fmt var=item.size type=bytes#]           → human-readable bytes
[#fmt var=item.hours type=hours#]          → 3h 30m, 6m, 37h (whole minutes)
[#fmt var=item.created type=ago#]          → "3 days ago"
[#fmt val=[#data-count users#] type=number round=-2 round_mode=floor#]
[#fmt var=item.invoice type=file#]         → file download markup
[#fmt var=item.order type=pad length=4#]   → zero-padded number

Tipos: text, plain, html, date, ago, json, bytes, hours, number, boolean, image, file, pad

var= lê uma variável; val= recebe o próprio valor, normalmente um shortcode aninhado. O tipo é type=, ou uma palavra solta como último parâmetro: [#fmt var=list empty={} json#] codifica, [#fmt var=list json empty={}#] não.

[#count varname#]

Exibe o número de itens de uma variável array.

[#count data.articles#]

---

Controle de fluxo

[#if condition action#]

[#if user=(empty) redirect=login#]
[#if language=en tpl=intro-en#]
[#if status=published echo=yes#]
[#if user=(not-empty) tpl=dashboard tpl_else=login#]
[#if score=0 echo_else=[#get score#]#]
[#if not role=admin redirect=home#]
[#if lang=en or lang=nl tpl=western-layout#]

Condições: key=value, key=(empty), key=(not-empty) Ações: tpl=, tpl_else=, echo=, echo_else=, redirect= Modificadores: not, or, and

[#if#] é sempre uma única tag que se fecha sozinha; não existe forma de bloco ([#if#]...[#/if#]), e isso é de propósito. Os templates não contêm lógica de negócio. O conteúdo condicional sempre fica num template separado, chamado com tpl=. Nunca escreva um bloco [#if#]…[#/if#] num template.

[#redirect url#]

Redireciona na hora.

[#redirect login#]
[#redirect [#base-url#]/dashboard#]

---

URL e caminho

[#base-url#]

Devolve o caminho base da instalação na URL. Use em todos os links internos.

<a href="[#base-url#]/about">About</a>
<link href="[#base-url#]/ext/static/app.css">

Em JavaScript, [#base-url#] não está disponível como tag de template. Use nb.base_url; o core a define antes de qualquer script da página rodar. Isso é essencial ao montar URLs de imagens ou caminhos da API no código, principalmente quando o site roda sob um alias ou uma subpasta (como no staging). Nunca escreva /img/ ou /api/ como caminho solto em JS.

// wrong - breaks on staging aliases
return '/img/' + uuid + '/240w';

// correct
return nb.base_url + '/img/' + uuid + '/240w';

[#base-path#]

Devolve o caminho no sistema de arquivos até a raiz da instalação. Para incluir arquivos no servidor.

[#url#]

Devolve a URL completa atual.

[#is-url segment#]

Define is-url como true se a URL atual começa com o segmento informado. Use para o estado ativo na navegação.

[#is-url about#]
[#if is-url=true echo=active#]

[#is-url (home) =#]   → exact match for homepage

Conteúdo

[#get-html field#]

Exibe um campo de conteúdo HTML editável. Permite edição na página pelos administradores.

[#get-html main_text#]
[#get-html content.home.intro default="<p>Edit this text</p>"#]

Os links no conteúdo são escritos a partir da raiz do site, /contact ou /en/article/deep-space, sem [#base-url#]. Quando o site roda numa subpasta (staging sob um alias), get-html coloca o caminho base na frente ao exibir a página, e o editor o retira ao salvar, então o link guardado funciona em todos os ambientes. Um link que já começa com o caminho base, e um link para outro site, ficam como estão.

Os campos i18n são resolvidos automaticamente por [#get#] e [#fmt#] quando o valor é um objeto com os códigos de idioma configurados como chaves. Use lang= para forçar um idioma.

[#get item.title#]
[#get item.title lang=en#]
[#fmt var=item.title type=plain lang=nl#]

[#text Label_key#]

Exibe um rótulo traduzido dos arquivos .po. Use sublinhados no lugar de espaços na chave.

[#text Search#]
[#text Save_changes#]
[#text No_results_found#]

As traduções ficam em ext/data/.i18n/text.<lang>.po.

[#cfield field#]

Determina o caminho completo com pontos de um campo de conteúdo no contexto atual do template. É usado com [#get-html#] para conteúdo fixo da página, editável na própria página, guardado no recurso .content.

O recurso .content guarda, por chave, blocos de HTML editáveis que não pertencem a nenhum registro de dados. Cada bloco é identificado por content.<page>.<field>. Quando [#get-html#] aponta para um caminho de .content que ainda não existe, ele cria o registro automaticamente e exibe o valor default.

<!-- In ext/tpl/about-intro/index.tpl -->
[#get-html content.about.intro default="<p>Edit this text</p>"#]
[#get-html content.about.body default="<p>Body text here</p>"#]

[#cfield field#] determina o caminho do campo a partir do contexto atual do template; útil quando o mesmo template é usado em vários lugares:

[#get-html [#cfield intro#] default="<p>Edit this</p>"#]

Esse padrão exige que o módulo user esteja ativo (carregado automaticamente).

[#get-img-html uuid sizes="..." mode=w#]

A forma recomendada de exibir imagens. Gera um <img> responsivo com srcset, sizes, carregamento lazy e limites que evitam ampliar a imagem. Use sempre em vez de uma tag <img> escrita à mão.

[#get-img-html [#record.main_img#] sizes="sm-100,md-50,lg-33"#]

Parâmetro sizes: pares de breakpoint e porcentagem separados por vírgula. Cada parte é breakpoint-vw, em que vw é a porcentagem da largura da tela que a imagem ocupa a partir daquele breakpoint. Breakpoints omitidos usam 100vw.

Parâmetro mode: define como o servidor dimensiona a imagem:

Exemplo de recorte quadrado:

[#get-img-html [#record.avatar#] sizes="sm-50,md-25" mode=w?ratio=1.0#]

Os estilos inline max-width/max-height no <img> gerado só evitam ampliar a imagem; não atrapalham o object-fit: cover do CSS nem layouts em grid quando as imagens são maiores que o tamanho exibido (o que sempre acontece com conteúdo real).

---

Página HTML

[#html#]

Exibe a shell HTML completa da página (doctype, head, body). Coloque no fim dos templates de rota.

Estas variáveis influenciam a shell HTML quando definidas antes de [#html#]:

[#set page-title="[#get record.title#]"#]
[#set og-type=article#]
[#set og-image=[#record.main_img#]#]
[#set page-description="[#fmt var=record.main_text type=html max_length=160#]"#]
[#set page-settings-link="[#base-url#]/nb-admin/event/[#record.uuid#]"#]
[#set body-classes=site-body#]
[#html#]

A imagem OG padrão do projeto é definida uma vez em ext/tpl/meta/index.tpl, sem overwrite, para que os valores por página sempre tenham prioridade. Há dois utilitários de imagem como shortcode:

• [#img-url UUID-or-path-or-URL#] - transforma qualquer referência de imagem numa URL absoluta (útil fora do meta, por exemplo em JSON-LD)
• [#first-img-uuid var=record.main_text#] - extrai o UUID da primeira imagem incorporada num campo HTML; devolve (empty) quando não há nenhuma

Importar registros de recursos de DOCX

Os formulários de criação de registros podem exibir a ação Import document do core. Ela aceita um .docx, extrai os parágrafos e hiperlinks e envia o texto limitado do documento ao endpoint de importação da OpenAI configurado, para propor valores para os campos do recurso. Os editores revisam o formulário preenchido antes de salvar; a importação não cria registro sozinha.

A extração de DOCX exige a extensão ZIP do PHP, porque um documento Office Open XML é um arquivo ZIP. Todo runtime de CLI e web/FPM que possa executar a importação ou os testes dela precisa ter ZipArchive. No Debian e no Ubuntu, ela costuma ser instalada com o pacote php-zip da versão correspondente; as imagens Docker do Nimbly para desenvolvimento e produção incluem php-zip explicitamente. Verifique um servidor configurado à mão com:

php -r 'echo class_exists("ZipArchive") ? "available\n" : "missing\n";'
php core/tests/docx-test.php

Não deduza a disponibilidade na web só pela CLI quando a CLI e o PHP-FPM carregam configurações separadas. Confirme a extensão nos dois runtimes depois da instalação e teste a importação de documentos pela aplicação web.

Documentos PDF

Instale a dependência do módulo PDF do core com php core/cli/nimbly.php module:install pdf. As rotas da aplicação fornecem o próprio HTML e usam a biblioteca PDF do core para gerar, guardar em cache por conteúdo e baixar com segurança no navegador:

load_library('pdf');
$pdf_bytes = pdf_render_cached_document([
    'paper_size' => 'a4',
    'orientation' => 'portrait',
    'margins' => ['top' => 20, 'right' => 18, 'bottom' => 20, 'left' => 18],
    'pages' => [$document_html],
]);
pdf_send_download($pdf_bytes, 'Document-123.pdf');
exit();

pdf_render_document() sempre gera bytes novos. Para downloads, prefira pdf_render_cached_document(): a identidade do cache inclui a configuração completa do documento e os arquivos do renderizador do core, então conteúdo ou código de renderização alterados invalidam o cache automaticamente. Não monte timestamps de recursos nem listas de dependências de templates em rotas individuais. pdf_send_download() limpa o nome do arquivo e envia cabeçalhos de download de PDF privados, que o navegador não guarda em cache.

---

Utilitários

[#include file=path#]

Inclui um arquivo no servidor. O caminho precisa ficar dentro do projeto; caso contrário, não exibe nada.

[#include file=[#base-path#]ext/tpl/head-scripts/index.tpl#]

A normalização de UUID, salt, slug, MD5 e chaves de recurso, e a remoção de formatação para texto simples, são funções auxiliares do PHP em core/lib/util.php, não shortcodes. Use-as em bibliotecas PHP, arquivos de rota, scripts de instalação e scripts de CLI:

load_library('util');

$uuid = generate_uuid();
$salt = generate_salt();
$slug = make_slug($title);
$hash = md5_uuid($slug);
$text = plain_text($html);

[#env KEY default=value#]

Devolve um valor do .env, com default quando a chave falta. As configurações que o core mantém em segredo (PEPPER, STATS_KEY, ADMIN_PASSWORD, SMTP_PASSWORD, AGENT_REMOTE_PASSWORD, OPENAI_API_KEY, RESEND_API_KEY, GIT_TOKEN) nunca são exibidas: leia-as no PHP com env().

[#env STRIPE_LINK_ANNUAL#]
[#env MAIL_SERVICE default=resend#]

[#logged-in#]

Devolve "logged-in" se há uma sessão de usuário ativa.

[#if logged-in=(empty) redirect=login#]

[#feature-cond features=name#]

Exibe conteúdo conforme o usuário atual tenha ou não uma permissão específica.

[#feature-cond features=edit-articles tpl=edit-button#]
[#feature-cond features=view-admin-dashboard echo="<a href='/nb-admin'>Admin</a>"#]
[#feature-cond features=view-admin-dashboard tpl=admin-panel tpl_else=access-denied#]
[#feature-cond features=edit-articles,view-reports tpl=dashboard#]

Parâmetros:

• features - lista de permissões separadas por vírgula; o acesso é dado se o usuário tem qualquer uma delas, ou (all) (admin)
• tpl - template exibido quando há acesso
• tpl_else - template exibido quando não há acesso
• echo - texto exibido quando há acesso
• echo_else - texto exibido quando não há acesso

As permissões têm a forma <operation>-<resource_id>, por exemplo view-articles, create-products, edit-.content ou delete-users. Ids de recursos ocultos mantêm o ponto inicial nas permissões guardadas. manage-<resource_id> dá todas as operações padrão daquele recurso. A função admin sempre tem (all), que pula todas as verificações de permissão.

As permissões são atribuídas às funções em /nb-admin/roles/. Use a tela de permissões da função para editar as permissões com caixas de seleção; tokens próprios ainda podem ser guardados para verificações específicas do projeto. Tokens antigos como manage-content, (any), get_<resource>, add-<resource> e (any)_<resource> são convertidos ao carregar a sessão e na migração de atualização, mas o código novo usa a forma padrão.

[#date input fmt=Y-m-d#]

Formata uma data. A entrada pode ser um timestamp Unix, um texto de data ou omitida (hoje). Use fmt=full, long, medium ou short para uma saída legível no idioma da página. Qualquer outro valor de fmt usa a sintaxe de data do PHP para um formato técnico exato. Informe lang= para substituir o idioma detectado.

[#date fmt=d-m-Y#]                        → today in d-m-Y format
[#date item.date fmt="j F Y"#]            → formats item.date
[#date 1741265734 fmt=Y-m-d#]             → formats Unix timestamp
[#date item.date fmt=long#]               → locale-aware long date

[#fmt var=item.date type=date fmt=long#] usa o mesmo formatador de datas. Os formatos com nome usam a extensão intl do PHP quando disponível e, sem quebrar a página, recorrem a formatos fixos em inglês do PHP.

[#get-first dataset#]

Guarda o primeiro item de um conjunto de dados em first (ou numa variável própria).

[#get-first data.articles#]
[#get first.title#]

[#get-first data.articles var=latest#]
[#get latest.date#]

[#last-update#]

Devolve um timestamp Unix do arquivo-fonte modificado mais recentemente em ext/ e core/. Útil com [#fmt type=ago#] para mostrar quando o site foi atualizado pela última vez.

[#fmt val=[#last-update#] type=ago#]   → "3 days ago"
[#fmt val=[#last-update#] type=date fmt=d-m-Y#]

[#obfuscate text#]

Exibe um texto com caracteres Unicode invisíveis e Alpine.js, de modo que bots e scrapers não o veem, mas os usuários conseguem ler. Use para endereços de e-mail e números de telefone.

[#obfuscate info@example.com#]

[#uri-path#]

Devolve o caminho no sistema de arquivos da pasta da rota atual.

[#url-key#]

Devolve uma chave normalizada da URL atual, útil para classes do body ou para reconhecer a página em JS.

[#set body-classes=[#url-key#]#]

/admin/users/ → admin_users, página inicial → _home.

[#http-header type#]

Envia um cabeçalho Content-Type na resposta. Use no topo de rotas que não devolvem HTML.

[#http-header json#]
[#http-header css#]
[#http-header csv#]

Tipos: css, js, json, xml, txt, woff, csv, 403, 404, 500.

Um segundo parâmetro também envia cabeçalhos de cache longo (Cache-Control: private, Expires, Last-Modified) e responde 304 a uma requisição condicional: [#http-header css cached#].

[#system-messages#]

Exibe as mensagens do sistema na fila (definidas no servidor pela sessão). Use no template HTML ou no layout para mostrar avisos rápidos.

[#empty-img#]

Devolve um GIF transparente de 1×1 como data URI. Use como src provisório antes de haver uma imagem real.

[#max-upload-size#]

Exibe o valor upload_max_filesize do PHP em forma legível. Útil como dica em formulários de envio.

[#unquote varname#]

Exibe o valor de uma variável com as aspas escapadas em HTML (" → ", ' → '). Seguro para colocar valores dentro de atributos HTML.

<div x-data='{"title": "[#unquote item.title#]"}'></div>

[#collect-script path#]

Adia a inclusão de um script para que todos sejam exibidos juntos no fim da página, sem duplicatas. Chame sem argumentos para exibir todos os scripts coletados.

[#collect-script [#base-url#]/ext/static/chart.js#]
...
[#collect-script#]   ← renders all collected scripts here

[#is-dev-env#]

Exibe DEV ou PROD. Útil para saída de depuração ou comportamento por ambiente.

[#if [#is-dev-env#]=DEV tpl=debug-panel#]

[#detect-language#]

Devolve o código do idioma ativo. Ordem de detecção:

1. Prefixo da URL (/en/, /nl/)
2. Preferência do usuário (?lang=en)
3. TLD do domínio (.en, .nl)
4. Cabeçalho de idioma do navegador
5. Alternativa: o primeiro idioma definido na configuração do site

[#debug#]

Exibe informações de depuração. Use só durante o desenvolvimento.

[#debug#]
[#debug variables session#]

[#log message#]

Grava em ext/data/.tmp/logs/system.log.

[#nop#]

Não faz nada. Use para desativar shortcodes temporariamente.

Classificação da API de shortcodes

O inventário abaixo é gerado a partir das implementações *_sc() em core/lib e core/modules/*/lib e conferido com o uso no ext/ local. Os shortcodes públicos são estáveis para templates de projeto. Os shortcodes internos e do admin são suportados em templates e módulos do core, mas não devem ser tratados como API para projetos.

---

Outras interfaces públicas

Estas notas descrevem shortcodes públicos do inventário do framework cujo uso não foi detalhado acima. Use os guias específicos para fluxos completos.

Limites de validação e limpeza

O inventário inclui hoje validate e sanitize, mas esses shortcodes não validam nem limpam nada. Não confie na chamada dessas tags para proteger a entrada. Use as funções reais de validação do PHP e o tratamento de campos e da API do framework, como descrito em Formulários e Pontos de extensão do PHP.

feature-cond e a apresentação baseada em funções escolhem quais templates exibir. Os processadores do backend continuam verificando as permissões de cada ação protegida.