Blocos em Temas

Os templates de bloco vivem em builder/block_templates/ e são o que torna os dados de um bloco em HTML. Esta página mostra exatamente como o builder liga os tipos de bloco aos templates : e o que o seu tema ou um novo tipo de bloco pode esperar.

O pipeline de resolução

Para cada bloco, o builder executa uma subrotina que decide a saída inteira:

Ciclos são apanhados primeiro. Um bloco que re-referencia a si mesmo renderiza um marcador de comentário em vez de uma recursão infinita.
Busca por idioma com fallback : o bloco é buscado pelo nome no idioma da página; quando ausente, a versão de idioma padrão do mesmo nome é usada em vez dele. Um bloco não encontrado em nenhum dos idiomas torna-se um comentário HTML “not found”; não quebra nada.
As variáveis chegam preparadas. A linha do bloco é passada ao seu template as-is: todas as colunas escalares tornam-se variáveis de template, e seu content_json é decodificado em content_data (array ou hash, dependendo do tipo).
Sobrescritas de colocação vencem. Qualquer sobrescrita por colocação (a sobrescrita de uma atribuição de stack, por exemplo) funde-se sobre os campos armazenados do bloco antes da renderização.
Código de cola consciente de tipo executa. Alguns tipos ganham contexto extra antes de o template deles executar:
- page_list com um pai definido publica um array pages dos filhos sob aquele pai, com um heading auto-gerado “Also in ” quando nenhum é definido
- blocos newsletter e form incorporam os campos do formulário configurado e roteiam as submissões ao sistema de formulários
- blocos document carregam o registro de documento referenciado, com as linhas de detalhe a mostrar passadas como booleanos (show_thumbnail, show_description, show_size, show_download_count, show_date)
- blocos faq recebem um fragmento de dados estruturados JSON-LD pré-computado e escapado, por segurança
- blocos columns e grid resolvem shortcodes {{block:…}} dentro das células deles, de modo que blocos aninhados funcionem ali também
Imagens auto-enriquecem. Se a URL de imagem do bloco casa com um arquivo de mídia enviado com derivativos responsivos, image_srcset_jpg / image_srcset_webp chegam ao template pré-construídos para saída estilo <img srcset>.
Erros permanecem contidos. Um erro de renderização no próprio template de um bloco renderiza um comentário “render error” em vez de abortar a página inteira.

Onde os blocos são colocados

Em corpos de página e post : via o shortcode {{block:name}} resolvido inline em tempo de build; tudo o que o page.tt / post.tt / blog_index.tt / landing.tt do seu tema recebe tem o HTML de blocos já renderizado.
Em stacks : stacks compõem vários blocos em um fragmento; o fragmento renderiza com seu próprio id de contêiner e seu id de layout (usados por stacks em temas para styling alvejado). Stacks também podem conter stacks aninhadas : com o mesmo guard de ciclo.
Seus templates veem HTML impresso, não objetos de bloco crus : a var de corpo que um template recebe tem os shortcodes já substituídos.

O que um template de bloco lembra

Cada tipo de bloco tem exatamente um arquivo Template Toolkit: builder/block_templates/<type>.tt (por exemplo cta.tt, gallery.tt). Esses arquivos embarcam fora do seu tema : descrevem a marcação de um bloco e são os mesmos para cada tema, de modo que seu tema os estiliza por nome de classe em vez de mudar sua marcação.

O template recebe as variáveis de linha do bloco mais content_data (JSON decodificado), variáveis de campos de formulário quando um formulário vinculado está configurado, e quaisquer enriquecimentos específicos de tipo acima aplicáveis.
page_list, document, e blocos “espertos” similares têm seus dados dependentes materializados nas variáveis de template, de modo que um tema apenas precisa imprimir campos.

O contrato de CSS

O _head.tt do seu tema deve estilizar as classes wrapper de cada tipo de bloco que os templates emitem. As tabelas de referência embutida de blocos documentam a wrapper e a classe interna de cada tipo; a stylesheet do tema padrão as implementa exatamente. Um bloco não estilizado ainda renderiza seu HTML : nunca quebra o build, apenas parece inacabado no navegador.

Adicionando um novo tipo de bloco

A receita de ligação : três passos, com o registro de Block Types como o porteiro:

Registre o slug do tipo na tela de Block Types : essa tabela decide quais tipos são válidos para create_block e a troca de tipo de bloco.
Crie builder/block_templates/<type>.tt : o template de renderização. Acerte as variáveis e regras de enriquecimento acima e você está quase lá.
Crie templates/admin/blocks/types/<type>.html.ep : o partial de formulário de admin, que preenche os campos planos e opcionalmente um editor de linhas de content_json.

Escape os dados controlados por usuário ao escrever um template: escape tudo para HTML por padrão; apenas os corpos embutidos e os campos body dentro dos dados de conteúdo de accordion/columns é que se pretendem carregar HTML cru.

Ponha blocos em templates de tema personalizados

Quando você autor um tema personalizado, você não re-incorpora blocos nem invoca o resolvedor você mesmo : o builder resolve os shortcodes no texto do corpo antes de o seu template executar. Seu tema apenas imprime o corpo, que chega como HTML já renderizado. Se você quer layouts dirigidos por blocos em toda parte, use stacks: são sequências de blocos com conteúdo sobrescrevível e regras de exibição condicional, e renderizam como uma unidade por atribuição.