Blocks en los Themes

Las block templates viven en builder/block_templates/ y son lo que convierte los datos de un block en HTML. Esta página te muestra exactamente cómo el builder conecta los tipos de block con las templates, y qué puede esperar tu theme o un nuevo tipo de block.

El pipeline de resolución

Para cada block, el builder ejecuta una subrutina que decide toda la salida:

1. Los ciclos se atrapan primero. Un block que se referencia a sí mismo renderiza un marcador de comentario en lugar de una recursión infinita.
2. Búsqueda por idioma con fallback: el block se busca por nombre en el idioma de la página; cuando falta, se usa la versión del idioma por defecto con el mismo nombre. Un block que no se encuentra en ninguno de los dos idiomas se convierte en un comentario HTML de "not found"; no rompe nada.
3. Las variables llegan preparadas. La fila del block se pasa a su template tal cual: todas las columnas escalares se convierten en variables de template, y su content_json se decodifica en content_data (array o hash, según el tipo).
4. Los overrides de placement ganan. Cualquier override por placement (los overrides de una asignación de stack, por ejemplo) se fusiona sobre los campos almacenados del block antes de renderizar.
5. Corre el código pegamento consciente del tipo. Algunos tipos reciben contexto extra antes de que corra su template:
   • page_list con un padre definido publica un array pages de los hijos bajo ese padre, con un encabezado auto-generado "Also in <category>" cuando no se define ninguno
   • los blocks newsletter y form incrustan los campos del formulario configurado y enrutan los envíos al sistema de formularios
   • los blocks document cargan el registro del documento referenciado, con qué filas de detalle mostrar pasado como booleanos (show_thumbnail, show_description, show_size, show_download_count, show_date)
   • los blocks faq reciben un fragmento de datos estructurados JSON-LD precalculado y escapado por seguridad
   • los blocks columns y grid resuelven los shortcodes {{block:…​}} dentro de sus celdas para que los blocks anidados también funcionen ahí
6. Las imágenes se auto-enriquecen. Si la URL de imagen del block coincide con un archivo multimedia subido con derivados responsive, image_srcset_jpg / image_srcset_webp llegan a la template preconstruidos para salida tipo <img srcset>.
7. Los errores quedan atrapados. Un error de renderizado en la template propia de un block renderiza un comentario de "render error" en lugar de abortar la página completa.

Dónde se colocan los blocks

• En los cuerpos de páginas y posts: vía el shortcode {{block:name​}} resuelto inline en tiempo de build; todo lo que reciben las page.tt / post.tt / blog_index.tt / landing.tt de tu theme ya trae el HTML de los blocks renderizado.
• En stacks: los stacks componen varios blocks en un fragmento; el fragmento se renderiza con su propio id de contenedor y su id de layout (usado por los stacks en los themes para estilización dirigida). Los stacks también pueden contener stacks anidados, con la misma protección de ciclo.
• Tus templates ven HTML impreso, no objetos de block crudos: la variable body que recibe una template ya tiene los shortcodes reemplazados.

Cómo se ve una block template

Cada tipo de block tiene exactamente un archivo Template Toolkit: builder/block_templates/<type>.tt (por ejemplo cta.tt, gallery.tt). Estos archivos se envían fuera de tu theme; describen el marcado de un block y son iguales para todos los themes, así que tu theme los estiliza por nombre de clase en lugar de cambiar su marcado.

• La template recibe las variables de la fila del block más content_data (JSON decodificado), las variables de campos de formulario cuando hay un formulario vinculado configurado, y los enriquecimientos específicos de tipo que correspondan de los descritos arriba.
• page_list, document y blocks "inteligentes" similares reciben sus datos dependientes materializados en las variables de la template, así que al theme solo le queda imprimir campos.

El contrato CSS

La _head.tt de tu theme debe estilizar las clases wrapper que las templates de cada tipo de block emiten. Las tablas de referencia de blocks integradas documentan la clase wrapper y la clase interna de cada tipo; la hoja de estilos del theme por defecto las implementa exactamente. Un block sin estilos igualmente renderiza su HTML: nunca rompe el build, solo se ve sin terminar en el navegador.

Añadir un nuevo tipo de block

La receta de cableado: tres pasos, con el registro de Block Types como guardián:

1. Registra el slug del tipo en la pantalla Block Types: esa tabla decide qué tipos son válidos para create_block y para el cambio de tipo de block.
2. Crea builder/block_templates/<type>.tt: la template de renderizado. Consigue que las variables y las reglas de enriquecimiento de arriba estén correctas y ya tienes gran parte del camino.
3. Crea templates/admin/blocks/types/<type>.html.ep: el parcial del formulario de admin, que llena los campos planos y opcionalmente un editor de filas content_json.

Escapa los datos controlados por el usuario al escribir una template: escapa todo en HTML por defecto; solo los cuerpos y los campos body dentro de los datos de contenido de accordion/columns están pensados para llevar HTML crudo.

Poner blocks en templates de theme personalizadas

Cuando autoras un theme personalizado, no vuelves a incrustar blocks ni invocas el resolver tú mismo: el builder resuelve los shortcodes en el texto del cuerpo antes de que corra tu template. Tu theme solo imprime el body, que llega como HTML ya renderizado. Si quieres layouts dirigidos por blocks en todas partes, usa stacks: son secuencias de blocks con contenido sobrescribible y reglas de visualización condicional, y se renderizan como una unidad por asignación.