Un nuevo Theme (basado en secciones y bloques) organiza su código en carpetas con responsabilidades bien delimitadas: sections, blocks y snippets separan lo editable de lo estructural, templates/ define la composición de páginas, y config/ centraliza los settings globales del Theme.
Vista general
theme/
├── blocks/ # Bloques reutilizables con schema (se usan dentro de sections)
├── config/
│ ├── settings_schema.json # Schema de settings globales del Theme
│ └── settings_data.json # Valores guardados de los settings globales
├── layouts/
│ ├── layout.tpl # Wrapper HTML principal (head, header, content, footer)
│ └── resources/
│ ├── icons-sprite.tpl # Sprite SVG inline
│ └── style-tokens.tpl # Custom properties CSS (fuentes, colores)
├── sections/ # Sections de página con schema (header, footer, hero, banners, ...)
├── snippets/ # Partials sin schema (cart/, payments/, product/, forms/, ...)
├── static/
│ ├── css/
│ │ ├── style-critical.css # CSS crítico inlinado en <head>
│ │ ├── style-utilities.css # Clases utilitarias inlinadas en <head>
│ │ └── style-async.css # CSS no crítico, carga asincrónica
│ ├── js/
│ │ ├── store.js # Lógica client-side del Theme (vanilla JS)
│ │ ├── libraries-standalone.js
│ │ └── libraries.js.tpl
│ └── checkout.scss.tpl # Estilos de branding para el checkout
├── templates/
│ ├── pages/ # Templates de página (home.json, product.json, ...)
│ │ └── account/ # Páginas de cuenta (login, register, orders, ...)
│ └── layout/ # Templates de layout (header.json, footer.json)
└── translations/
├── <locale>.json # Strings del storefront (orientados al comprador)
└── <locale>.schema.json # Labels del editor (orientados al usuario)| Carpeta | Propósito |
|---|---|
blocks/ |
Componentes reutilizables con schema, usados dentro de sections. |
config/ |
Schema y valores guardados de los settings globales del Theme. |
layouts/ |
El wrapper HTML dentro del que se renderiza toda página. |
sections/ |
Unidades de ancho completo con schema, settings, blocks y presets. |
snippets/ |
Fragmentos sin schema para funcionalidades de experiencia de compra. |
static/ |
CSS compilado, JavaScript y estilos de checkout. |
templates/ |
Archivos JSON que definen cómo se componen las páginas. |
translations/ |
Traducciones de storefront (*.json) y labels del editor (*.schema.json). |
Detalle por carpeta
layouts/
Contiene el wrapper HTML que envuelve toda página, más los assets inline compartidos.
| Archivo | Qué hace |
|---|---|
layout.tpl |
HTML principal: <head>, fuentes, CSS crítico, tokens de estilo, header, {{ page_template_content }}, footer, modales, notificaciones.
|
resources/icons-sprite.tpl |
Sprite SVG inline, incluido cerca del inicio de <body>.
|
resources/style-tokens.tpl |
Custom properties CSS (tokens de fuentes y colores) inyectados como <style> inline en el <head>.
|
La página activa se renderiza a través de:
<main id="MainContent" class="main-content main-container" role="main">
{{ page_template_content }}
</main>
El header y el footer se renderizan desde layout templates compartidos entre todas las páginas:
{% layout_template 'header' %}
{# ... contenido de página ... #}
{% layout_template 'footer' %}
Estas dos llamadas renderizan templates/layout/header.json y templates/layout/footer.json respectivamente.
config/
Settings de alcance global del Theme (colores, tipografía, defaults de header/footer, …) como JSON. Solo dos archivos: uno para el schema, otro para los valores guardados.
| Archivo | Qué hace |
|---|---|
settings_schema.json |
Schema de settings globales — favicon, colores, tipografía, botones, header, footer, product card, carrito, checkout, etc. |
settings_data.json |
Valores guardados de los settings globales. |
Los settings globales son accesibles desde cualquier .tpl vía settings.*:
{{ settings.background_color }}
{{ settings.font_headings }}
sections/
Las sections son las unidades de ancho completo de una página. Se agrupan en familias:
| Grupo | Archivos representativos | Propósito |
|---|---|---|
| Layout | header.tpl, footer.tpl, announcement-bar.tpl |
Componentes compartidos en todas las páginas. |
| Contenido principal | main-product.tpl, main-cart.tpl, main-products-grid.tpl, main-blog.tpl, … |
Contenido central de un tipo de página específico. |
| Marketing / marca | hero.tpl, banners.tpl, slideshow.tpl, video.tpl, image-with-text.tpl, testimonials.tpl, featured-brands.tpl, newsletter.tpl, rich-text.tpl, faq.tpl, timer-offers.tpl |
Sections reutilizables de storytelling y merchandising. |
| Producto | product-list.tpl, featured-product.tpl, related-products.tpl, product-description.tpl |
Presentación de productos a lo largo de las páginas. |
Cada archivo de section termina con un bloque {% schema %}. El nombre que aparece en el editor proviene del campo name del schema (una clave t:).
blocks/
Los blocks se renderizan dentro de sections y se agrupan por función:
| Categoría |
Ejemplos |
|---|---|
| Contenido genérico |
heading.tpl, text.tpl, image.tpl, button.tpl, video.tpl, menu.tpl, group.tpl, accordion.tpl |
| Slideshow / banners |
slide.tpl, carousel-slide.tpl, banner.tpl |
| Producto |
product-media.tpl, product-info.tpl, purchase-info.tpl, products.tpl, description.tpl, product-recommendations.tpl |
| Categorías / marcas |
category-nav.tpl, category-item.tpl, brand-group.tpl, brand-logo.tpl |
| FAQ / testimonios / icon-text | faq-group.tpl, faq-list.tpl, faq-item.tpl, testimonial-group.tpl, testimonial.tpl, icon-text-group.tpl, icon-text-item.tpl |
| Header / footer | header-logo.tpl, header-navigation.tpl, header-utilities.tpl, footer-institutional.tpl, footer-menu.tpl, footer-newsletter.tpl |
| Formularios / utilidades | newsletter-form.tpl, announcement.tpl, payment-icons.tpl |
Cada archivo de block también termina con un {% schema %}.
snippets/
Fragmentos sin schema, organizados por dominio de experiencia de compra:
| Subcarpeta |
Cubre |
|---|---|
cart/ |
Ítems del carrito, modal/drawer, totales, fulfillment, cross-selling. |
payments/ |
Cuotas, medios de pago, bancos, detalle de pago. |
product/ |
Formulario de producto, variantes, galería de imágenes, video, cantidad, detalle de pago. |
product-list/ |
Card de grilla de productos, filtros (precio, propiedades, categoría), paginación, orden. |
forms/ | Inputs, selects, dropdowns, formularios de login/registro, reCAPTCHA. |
shipping/ | Calculadora de envío, opciones, sucursales, progreso de envío gratis. |
header/ | Formulario de búsqueda, navegación mobile, selector de idioma. |
navigation/ | Paneles de navegación, menú hamburguesa. |
footer/ | Links legales, info de claim, logos de medios de pago y envío. |
social/ | Botones de share, links de contacto, chat de WhatsApp. |
subscriptions/ | Planes de suscripción, precio, alertas. |
promotions/ | Labels de promoción, mensajes de regalo, tablas de descuento. |
placeholders/ | Skeleton loaders. |
modals/ | Modal de quick-shop, wrapper de modal genérico. |
| (raíz) | icon.tpl, image.tpl, card.tpl, breadcrumbs.tpl, labels.tpl, notification.tpl. |
Los snippets se incluyen con {% include 'snippets/<path>.tpl' %}, opcionalmente con contexto:
{% include 'snippets/notification.tpl' with { type: 'add_to_cart' } %}
static/
CSS compilado, JavaScript y el template SCSS de checkout. Se referencian desde layouts/layout.tpl.
| Archivo |
Qué hace |
|---|---|
css/style-critical.css |
CSS above-the-fold, inlinado en <head>. |
css/style-utilities.css |
Clases utilitarias, inlinadas en <head>. |
css/style-async.css |
CSS below-the-fold, cargado de forma asincrónica. |
js/libraries-standalone.js |
Librerías de terceros empaquetadas (Swiper, lazysizes, …). |
js/libraries.js.tpl | Loader con template para librerías adicionales y configuración. |
js/store.js | Lógica client-side del Theme (vanilla JS). |
checkout.scss.tpl | Estilos de branding para el checkout. |
templates/
Archivos JSON que componen páginas y regiones de layout compartidas. Hay dos tipos:
Page templates — templates/pages/*.json. Definen qué se renderiza dentro de <main> para cada tipo de página.
| Archivo |
Página |
|---|---|
pages/home.json |
Página de inicio. |
pages/product.json |
Detalle de producto. |
pages/category.json |
Categoría / colección. |
pages/cart.json |
Carrito de compras. |
pages/search.json | Resultados de búsqueda. |
pages/blog.json, pages/blog-post.json | Listado de blog y post. |
pages/page.json | Página personalizada genérica. |
pages/contact.json | Formulario de contacto. |
pages/password.json | Tienda protegida con contraseña. |
pages/404.json | Error 404. |
pages/account/*.json | Páginas de cuenta (login, register, reset, newpass, info, addresses, address, orders, order). |
Layout templates — templates/layout/*.json. Definen las regiones de header y footer compartidas entre todas las páginas. Se renderizan desde {% layout_template 'header' %} y {% layout_template 'footer' %} en layouts/layout.tpl.
| Archivo |
Región |
|---|---|
layout/header.json |
Header del sitio, compartido entre todas las páginas. |
layout/footer.json |
Footer del sitio, compartido entre todas las páginas. |
translations/
Dos tipos de archivos de locale: strings del storefront (orientados al comprador) y labels del editor (orientados al administrador).
| Patrón de archivo |
Propósito |
|---|---|
<locale>.json (ej. en.json, es.json, pt.default.json) |
Strings que se muestran al comprador en el storefront. |
<locale>.schema.json (ej. en.schema.json, es.schema.json) |
Labels que se muestran al usuario en el editor. |
Locales disponibles: en, es, es_AR, es_CL, es_CO, es_MX, pt.default.
Fallback de locale — cuando el storefront solicita un locale (por ejemplo pt_BR), el resolver busca el archivo de traducción en este orden:
translations/pt_BR.json— coincidencia exacta.translations/pt.json— coincidencia solo por idioma.translations/<anything>.default.json— el default regional para ese idioma (ej.translations/pt.default.json).
El mismo fallback aplica a los archivos .schema.json. Esto permite distribuir un único default regional (ej. pt.default.json) y agregar archivos por país solo cuando el copy necesita diferenciarse.