Anatomía de un tema

Un tema OmniBuy es un directorio dentro de themes/ con una estructura predecible. Cada archivo tiene un rol específico.

Estructura de directorios

themes/<tu-tema>/
├── theme.json              ← Manifest del tema
├── sections.json           ← Schema del visual editor
├── config/
│   ├── settings_schema.json ← Configuración global del tema
│   └── settings_data.json   ← Valores por defecto
├── sections/
│   ├── hero.html           ← Módulos de contenido reordenables
│   ├── banner.html
│   └── ...
├── snippets/
│   ├── product-card.html   ← Componentes reutilizables
│   └── ...
├── templates/
│   ├── index.html          ← Template de la homepage
│   ├── product.html        ← Template de página de producto
│   ├── collection.html     ← Template de colección
│   ├── cart.html           ← Carrito
│   ├── page.html           ← Páginas CMS
│   └── ...
├── locales/
│   ├── es.json             ← Traducciones español
│   └── en.json             ← Traducciones inglés
└── assets/
    ├── theme.css           ← Estilos del tema
    └── theme.js            ← JavaScript del tema

theme.json — Manifest del tema

Declara las capacidades del tema: qué secciones ofrece, qué addons activa por defecto, y qué industria apunta.

{
  "name": "Cielo",
  "industry": "moda",
  "sections": [
    "banner", "blog_posts", "collection_list", "collections",
    "custom_links", "directory", "featured_products", "footer",
    "hair_color_tryon", "html_block", "image_gallery", "image_split",
    "logo_list", "marquee", "media", "newsletter", "rich_text",
    "slideshow", "value_props"
  ],
  "addons": [
    { "id": "reviews", "enabled_by_default": true },
    { "id": "complaints", "enabled_by_default": true },
    { "id": "size-fit", "enabled_by_default": false },
    { "id": "tryon-ar", "enabled_by_default": false }
  ],
  "templates": ["index", "product", "collection", "cart", "page", "..."]
}

Campo	Descripción
name	Nombre visible del tema
industry	Industria objetivo (moda, lujo, general)
sections	IDs de secciones de contenido disponibles en el editor
addons	Addons que el tema soporta y si se activan por defecto
templates	Templates que el tema provee

Templates

Los templates definen la estructura de cada página. Usan Liquid-like syntax o Go templates.

Template	Página	Contexto principal
index.html	Homepage	.HeroSlides, .FeaturedProducts, .Collections
product.html	PDP	.Product, .RelatedProducts
collection.html	PLP	.Collection, .Filters, .Pagination
cart.html	Carrito	.Cart, .Customer
checkout.html	Checkout	.Checkout, .CSRFToken
confirmation.html	Post-purchase	.Confirmation
page.html	CMS pages	.ContentPage
search.html	Resultados de búsqueda	.Search, .SearchQuery
blog.html	Blog listing	.BlogPosts
article.html	Blog article	.Article
customer.html	Mi cuenta	.Customer, .AccountOrder
categories.html	Directorio de categorías	.CategoryCards
collections.html	Directorio de colecciones	.CollectionCards

Cada template recibe el StoreContext completo — todos los objetos de contexto están disponibles, pero solo los relevantes están poblados.

Sections — Módulos de contenido

Las secciones son módulos reordenables que el merchant configura desde el Theme Editor. Cada sección es un archivo HTML en sections/ que define su propio template Go o Liquid.

<!-- sections/banner.html -->
{{define "sections/banner"}}
<div class="banner" style="background-color: {{.section.bg_color}}">
  <h2>{{.section.title}}</h2>
  <p>{{.section.subtitle}}</p>
  {{if .section.cta_text}}
    <a href="{{.section.cta_url}}">{{.section.cta_text}}</a>
  {{end}}
</div>
{{end}}

Las secciones se acceden en los templates a través de .ThemeSettings.<section_id>.

Snippets — Componentes reutilizables

Los snippets son fragmentos de template que se renderizan con {% render "snippet_name" %} o {{template "snippets/nombre" .}}.

themes/_base/snippets/
├── breadcrumb.html        ← Navegación de migas de pan
├── css_vars.html          ← Variables CSS del tema
├── product-card.html      ← Card de producto (used in grids)
├── seo_head.html          ← Meta tags SEO
├── head.html              ← <head> completo
└── page-sections.html     ← Renderiza secciones de una página

Los temas pueden overridear snippets de _base o dawn creando un archivo con el mismo nombre.

Assets

Los assets son archivos estáticos (CSS, JS, imágenes, fuentes) servidos directamente. OmniBuy aplica fingerprinting automático a los assets del tema para cache-busting:

<!-- En el template se usa el filter asset() -->
<link rel="stylesheet" href="{{ 'theme.css' | asset_url }}">
<script src="{{ 'theme.js' | asset_url }}"></script>

El filter asset_url resuelve la URL fingerprinted del asset.

Locales (i18n)

Cada tema puede tener traducciones propias en locales/es.json y locales/en.json. Se usan con el filter t:

{{ t .Lang "sections.banner.title" }}

sections.json — Schema del visual editor

Define los campos editables de cada sección para el Theme Editor visual. Es un array de objetos con id, fields y defaults:

{
  "sections": [
    {
      "id": "banner",
      "name": "Banner",
      "icon": "image",
      "category": "content",
      "global": false,
      "fields": [
        { "key": "title", "type": "text", "label": "Título" },
        { "key": "subtitle", "type": "textarea", "label": "Subtítulo" },
        { "key": "image_url", "type": "image", "label": "Imagen" },
        { "key": "bg_color", "type": "color", "label": "Color de fondo", "default": "#FFFFFF" },
        { "key": "cta_text", "type": "text", "label": "Texto del botón" },
        { "key": "cta_url", "type": "url", "label": "URL del botón" }
      ],
      "defaults": {
        "bg_color": "#FFFFFF",
        "full_width": false
      }
    }
  ]
}