Lo básico

Esta página cubre cómo construir el markup de un template set desde cero, para cuando duplicar y re-estilizar uno de los integrados (ver Temas y variables CSS) no sea suficiente.

Archivos de un template set

Archivo Función
layout.html La estructura exterior —el contenedor de resultados, y opcionalmente un campo de búsqueda, un botón de cierre, el panel de filtros y demás elementos alrededor. Se renderiza una vez al inicializar el widget.
card.html Se renderiza una vez por producto. Su salida se repite por cada resultado en la rejilla.
filter_term.html Se renderiza una vez por cada faceta de valores discretos (ej. Marca, Categoría) —ver Filtros.
filter_range.html Se renderiza una vez por cada faceta de rango numérico (ej. Precio).
styles.css El CSS de todo lo anterior. Escribe selectores contra los nombres de clase que uses en tu propio markup.

Un layout.html mínimo

<div class="my-widget" data-ss-root data-ss-anchor>
  <div data-ss-grid></div>
</div>
  • data-ss-root — obligatorio en todo template set. Marca el elemento raíz del widget; los colores configurados en el panel se inyectan como propiedades CSS personalizadas con este elemento como ámbito.
  • data-ss-anchor — opcional. Presente, el widget se renderiza anclado, en línea bajo el campo de búsqueda; ausente, se renderiza como superposición. Ver Conceptos básicos para qué significa cada uno. Esto es lo único que lo determina —no hay ningún otro ajuste de layout que configurar por separado.
  • data-ss-grid — obligatorio. Aquí es donde se inyecta la salida de card.html de cada producto, uno por resultado.

Eso es todo lo mínimo necesario para un widget funcional, aunque muy básico. Todo lo demás —un campo de búsqueda propio, un botón de cierre, filtros, búsqueda por voz, búsquedas recientes o populares— es markup opcional que añades encima, usando los hooks data-ss-* que el widget busca. Consulta Dar soporte a los switches de diseño para los que están ligados a un interruptor del panel.

Un card.html mínimo

<a href="{{link}}" class="my-card">
  <img src="{{image}}" alt="{{title}}">
  <div class="my-card-title">{{title}}</div>
  {{#price_regular}}<span>{{price_regular}}</span>{{/price_regular}}
</a>

card.html se renderiza una vez por producto, con los campos del producto disponibles directamente como {{campo}} —consulta Campos disponibles más abajo para la lista completa. Para la sintaxis de condicionales ({{#campo}}, {{^campo}}...) consulta Condicionales avanzados.

Campos disponibles

Cualquier campo de abajo se puede imprimir como valor con {{campo}} dentro de card.html (y de filter_term.html/filter_range.html, donde aplique) —esto no es solo cosa de condicionales, la interpolación simple funciona igual.

Del feed

Todos los campos del feed conectado están disponibles por su nombre interno —los campos estructurales que tiene todo feed (id, title, link, image, price, sku, sale_price, brand, description, categories, disable_add_to_cart...) más cualquier campo personalizado que hayas añadido tú. Consulta Formato SoloSearch para la lista estructural completa, y Añadir campos personalizados para los tuyos.

Esto incluye también effective_price —sale_price cuando el producto está en oferta, price en caso contrario. Se calcula una sola vez al parsear el feed, no en el widget, por eso es también el campo que se usa en el resto del panel para ordenar por precio, filtros de rango y boosts por valor. Consulta Campos calculados.

Calculados por el widget

Un puñado de campos no vienen del feed en absoluto —el widget los calcula en el momento de renderizar, solo para mostrarlos:

Campo Valor
price_regular price, formateado con la moneda del producto —solo tiene valor cuando el producto no está en oferta.
price_sale sale_price, formateado —solo tiene valor cuando el producto sí está en oferta.
price_original price, formateado —el precio "anterior" pensado para mostrarse tachado junto a price_sale. Solo tiene valor cuando el producto está en oferta.
price_raw price como número plano, sin formatear con moneda —para plantillas que quieran formatearlo por su cuenta.
sale_price_raw sale_price como número plano, sin formatear con moneda.
discount_percent El descuento como string redondeado, ej. -20% —vacío cuando no hay oferta.

price_regular y price_sale/price_original son mutuamente excluyentes por diseño —un producto está en oferta o no lo está—, por eso las plantillas de fábrica los combinan con condicionales en vez de imprimir los dos:

{{#price_sale}}<span class="ss-price-original">{{price_original}}</span><span class="ss-price-sale">{{price_sale}}</span>{{/price_sale}}
{{#price_regular}}<span class="ss-price">{{price_regular}}</span>{{/price_regular}}

Los interruptores de visibilidad como show_price o show_brand son otra cosa —vienen de las Display options del panel, no de los datos del producto. Consulta Dar soporte a los switches de diseño.

Un styles.css mínimo

.my-widget { position: fixed; background: #fff; border: 1px solid #ddd; }
.my-card { display: flex; gap: 8px; padding: 8px; text-decoration: none; color: inherit; }

Nada especial aquí —CSS normal contra los nombres de clase que hayas elegido arriba. Consulta Temas y variables CSS para las propiedades personalizadas --ss-* sobre las que escriben los selectores de color del panel, y cómo enganchar tu propia hoja de estilos a ellas.

Siguientes pasos