Saltar al contenido principal

Introducción

Obtén plantillas de visualización que controlan cómo se renderizan las páginas, bloques, productos e imágenes en tu aplicación.

Más información sobre las plantillas en el panel de administración de OneEntry: https://doc.oneentry.cloud/docs/category/templates

🎯 ¿Qué hace este módulo?​

El módulo de Templates te permite cambiar la estructura y apariencia de tu proyecto sin alterar su código fuente. Creas plantillas en el panel de administración de OneEntry (Configuración > Plantillas), etiquetas tus componentes con ellas, y este módulo obtiene esas configuraciones para que tu aplicación pueda renderizar contenido con un estilo consistente.

Esta separación de la estructura del código te permite alternar entre implementaciones de plantillas para influir en cómo se renderizan las entidades, todo sin necesidad de redeplegar. El SDK es de solo lectura: no puedes crear plantillas a través de él.

🚀 Inicio Rápido​

Inicializa el módulo desde defineOneEntry:


const { Templates } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Obtén plantillas y lee su configuración:

// Fetch all templates of a given BlockType.
const productTemplates = await Templates.getTemplateByType("product", "en_US");

productTemplates.forEach((tpl) => {
  console.log(tpl.identifier, tpl.title, tpl.generalTypeName);
});

// Or fetch a single template by its marker.
const card = await Templates.getTemplateByMarker("product_thumbnail", "en_US");
console.log(card.attributeValues);

✨ Conceptos Clave​

¿Qué es una Plantilla?​

Una Plantilla (ITemplateEntity) es una configuración de visualización que define cómo debe aparecer el contenido:

  • Tipo General (generalTypeName) - La categoría de entidad a la que se aplica la plantilla, un BlockType como product, common_page, common_block, form o order
  • Título (title) - Nombre de la plantilla que se muestra en el panel de administración (no único)
  • Marcador (identifier) - Identificador único para referencia de código (usa esto, no el ID)
  • Valores de Atributo (attributeValues) - Mapa de valores de atributo indexados por marcador
  • Conjunto de Atributos (attributeSetIdentifier) - Conjunto de atributos asociado opcional

Estructura de la Plantilla (ITemplateEntity):

interface ITemplateEntity {
  id: number;                              // Unique identifier
  title: string;                           // Template name (non-unique)
  identifier: string;                      // Template marker (unique)
  generalTypeId: number;                   // Type ID reference
  version: number;                         // Version number
  generalTypeName: BlockType;              // General type name
  attributeSetIdentifier: string | null;   // Associated attribute set
  attributeValues: IAttributeValues;       // Map of attribute values keyed by marker
  position: number;                        // Sort position
}

Tipos de Plantilla (BlockType)​

El tipo de una plantilla es su generalTypeName, un valor de BlockType. getTemplateByType(type) acepta el mismo BlockType. Valores comunes:

TipoCategoría de EntidadCasos de Uso Ejemplares
productProductosDetalle del producto, visualización del producto
catalog_pagePáginas de catálogoListado de categorías, resultados de búsqueda
common_pagePáginas regularesPublicación de blog, página de aterrizaje, página de información
error_pagePáginas de errorPágina 404, página 500, diseños de error personalizados
common_blockBloques de contenidoTarjetas de contenido, banners, secciones, widgets
formFormulariosFormulario de contacto, formulario de registro, encuesta
orderPedidosConfirmación de pedido, historial de pedidos
serviceEntidades de servicioContenido relacionado con servicios

📋 Lo Que Necesitas Saber​

Las plantillas se crean en el panel de administración​

No puedes crear plantillas a través del SDK - se crean en el panel de administración de OneEntry (Configuración > Plantillas). Cada plantilla necesita un Nombre (no único), un Marcador único y un Tipo (la categoría de entidad a la que se aplica). El SDK es para obtener configuraciones de plantillas, no para crearlas.

Usa marcadores, no IDs​

Siempre referencia las plantillas por su marcador (identifier) en tu código - los marcadores son estables entre entornos, los IDs no lo son. Usa getTemplateByMarker(marker) para una sola plantilla, getTemplateByType(type) para todas las plantillas de un BlockType, y getAllTemplates() para cada plantilla agrupada por tipo.

Plantillas faltantes​

Los métodos devuelven un objeto de error (IError) cuando no se encuentra una plantilla. Siempre verifica que los marcadores existan y maneja las plantillas faltantes de manera adecuada.

Caché​

Las plantillas rara vez cambian - almacénalas en caché (localStorage/sessionStorage en el frontend, Redis/memoria en el backend; ~1 hora de TTL es un punto de partida razonable).

📊 Tabla de Referencia Rápida​

MétodoDescripciónCaso de Uso
getAllTemplates()Obtener todas las plantillas agrupadas por tipoListar todas las plantillas disponibles
getTemplateByType()Obtener plantillas por tipo de entidadObtener plantillas para un tipo de entidad específico
getTemplateByMarker()Obtener una plantilla por marcadorObtener una configuración de plantilla específica

❓ Preguntas Comunes (FAQ)​

¿Cuál es la diferencia entre Plantillas y TemplatePreviews?​

Las plantillas configuran la visualización general del contenido (páginas, bloques, productos), mientras que TemplatePreviews manejan específicamente las imágenes de atributos de productos (muestras de color, vistas previas de material). Usa Plantillas para contenido principal, TemplatePreviews para imágenes de atributos.

¿Cómo obtengo una plantilla específica?​

Usa getTemplateByMarker(marker) para una sola plantilla por su identificador, o getTemplateByType(type) para obtener todas las plantillas de un BlockType dado (por ejemplo, product, common_page). Usa getAllTemplates() para recuperar cada plantilla agrupada por tipo.

¿Qué sucede si hago referencia a una plantilla que no existe?​

Los métodos devuelven un objeto de error (IError). Siempre verifica que existan los marcadores de plantilla y maneja las plantillas faltantes de manera adecuada.

¿Qué tipos de plantilla debo usar para mi contenido?​

Elige según el tipo de entidad: common_page para páginas estándar, catalog_page para listados de productos, common_block para bloques de contenido, product para detalles de productos. Alinea el tipo de plantilla con la categoría de tu contenido.

🎓 Mejores Prácticas​

  • Usa marcadores, no IDs - los marcadores son estables entre entornos.
  • Crea marcadores semánticos - product_card, no tpl_1.
  • Almacena en caché las plantillas - reduce las llamadas a la API para datos que cambian raramente.
  • Maneja las plantillas faltantes - verifica la forma de retorno de IError.

🔗 Documentación Relacionada​