Templates

Templates são arquivos simples no formato de saída, normalmente HTML, com shortcodes entre [# e #]. Um template tem a extensão .tpl.

<h1>[#get project.title#]</h1>
[#data projects filter=published:1#]
<ul>[#repeat data.projects tpl=card-project#]</ul>

Sem lógica, por princípio

Um template exibe valores, repete um template para uma lista e, no máximo, escolhe qual template vem a seguir. Não há blocos de lógica, laços com condições nem expressões dentro de um template. Decisões, cálculos e preparação de dados ficam em bibliotecas, onde podem ser lidos e testados num só lugar.

Isso mantém o markup fácil de ler e de mudar para todos que trabalham na interface, e mantém as regras da aplicação numa única camada.

Templates reutilizáveis

Uma pasta em ext/tpl/ com um index.tpl é um template que você chama pelo nome:

ext/tpl/site-header/index.tpl     [#site-header#]
ext/tpl/card-project/index.tpl    [#card-project#]

Um template lê as variáveis ao redor dele. Para passar um valor, defina a variável antes da chamada:

[#set back_url=/projects overwrite#]
[#back-link#]

Dentro do template, [#get back_url default=/#] lê esse valor. Uma convenção de nomes mantém um projeto em crescimento fácil de navegar: primeiro o tipo, depois o assunto, como em page-about, section-home-hero, card-project, icon-arrow.

Shortcodes

Shortcode	Faz
`[#get name#]`	Exibe uma variável, um campo de registro (`project.title`) ou um valor de um caminho aninhado
`[#set name=value#]`	Define uma variável, se ela ainda não tiver valor
`[#data resource#]`	Carrega registros em `data.<resource>`, com `filter`, `sort`, `limit` e `offset`
`[#repeat list tpl=name#]`	Exibe um template para cada item, com o item em `item`
`[#if condition tpl=name#]`	Exibe um template, imprime um valor ou redireciona quando uma condição vale
`[#get-html field#]`	Exibe texto formatado, editável na página pelos editores
`[#get-img-html uuid sizes=...#]`	Exibe uma imagem responsiva
`[#text Label#]`	Exibe um texto traduzido da interface
`[#fmt ...#]`	Formata um valor como data, número, texto simples, JSON e mais

A lista completa está na referência de shortcodes.

`[#set#]` mantém o primeiro valor

Um [#set#] simples não faz nada quando a variável já tem valor. Assim, uma rota pode definir cedo o título da página, e o padrão da shell nunca o sobrescreve. Acrescente overwrite quando quiser substituir um valor de propósito, por exemplo ao passar dados para um template reutilizável.

Para acrescentar a um valor, use append. Ele adiciona o novo valor depois de um espaço, ou depois do separador que você informar:

[#set body-classes="faq" append#]      adds faq to the classes already set
[#set tags="news" append=,#]           adds news after a comma
[#set body-classes="faq" overwrite#]   replaces whatever was set

`[#if#]` é uma tag única

O [#if#] não tem forma de bloco. Ele diz o que fazer, e o markup condicional fica num template próprio:

[#if project.cover=(not-empty) tpl=project-cover tpl_else=project-placeholder#]
[#if status=published echo=Live#]
[#if user=(empty) redirect=login#]

Compondo nomes

Shortcodes podem ser aninhados, inclusive no nome de um shortcode. Isso transforma um campo de tipo numa escolha de template, sem ramificações:

[#card-[#get item.type default=generic#]#]

Para um item do tipo news, isso exibe [#card-news#]; sem tipo, exibe [#card-generic#].

Templates para outros formatos

Um template não se limita a HTML. Uma rota pode gerar JSON, XML, CSV ou texto simples a partir de um template, com os mesmos shortcodes. Veja O que uma rota devolve.

Leia a seguir

Sintaxe de templates e Shortcodes na referência.
Bibliotecas para a lógica por trás de um template.