Child Themes PrestaShop: Guía de personalización Classic y Hummingbird

Qué es un Child Theme y por qué es importante

Un child theme hereda plantillas y assets de un tema padre, permitiéndole sobrescribir únicamente lo que modifica. Sin uno, cada ajuste de CSS o edición de plantilla reside en los archivos del tema padre — y se sobrescribe con la siguiente actualización.

Un child theme es una capa transparente. PrestaShop busca primero en el child theme. Si encuentra un archivo, lo utiliza. Si no, recurre al tema padre. Usted solo incluye lo que cambia.

Utilice un child theme para modificaciones específicas — colores, ajustes de maquetación, sobrescrituras de plantillas, CSS/JS personalizados. Construya un tema completamente personalizado solo cuando necesite una arquitectura fundamentalmente diferente.

Para nuevos proyectos en PrestaShop 8.1+, elija Hummingbird — es el tema predeterminado orientado al futuro y el único mantenido activamente por el proyecto PrestaShop.

Estructura de un Child Theme

Un child theme se ubica junto a su tema padre dentro de /themes/. El child theme mínimo viable requiere solo dos archivos:

themes/my-child-theme/
  config/
    theme.yml             <-- requerido: configuración del tema
  preview.png             <-- requerido: vista previa del tema 200x200

A medida que crecen las personalizaciónes, el directorio refleja la estructura del padre pero solo contiene los archivos modificados:

themes/my-child-theme/
  config/theme.yml
  assets/
    css/custom.css
    js/custom.js
  templates/
    catalog/product.tpl
    _partials/header.tpl
  modules/
    ps_featuredproducts/views/templates/hook/
      ps_featuredproducts.tpl
  translations/en-US/Shop/Theme.xlf
  preview.png

Agregue únicamente los archivos que esté modificando. Cada archivo que añade es un archivo que debe mantener. Un child theme vacío que hereda todo es mejor que uno saturado con copias sin modificar.

La configuración theme.yml

El archivo config/theme.yml es el corazón de su child theme. La línea crítica es parent: classic (o parent: hummingbird) — esta establece la cadena de herencia:

parent: classic
name: my-child-theme
display_name: My Child Theme
version: 1.0.0
author:
  name: "Your Name"
  email: "you@example.com"
  url: "https://yoursite.com"

meta:
  compatibility:
    from: 1.7.0.0
    to: ~

assets:
  use_parent_assets: true

theme_settings:
  default_layout: layout-full-width
  layouts:
    category: layout-left-column

Crear un Child Theme para Classic

Classic es el tema predeterminado original de PrestaShop desde la versión 1.7. El proceso consta de cuatro pasos:

# 1. Crear el directorio
mkdir -p themes/my-classic-child/config

# 2. Crear config/theme.yml con parent: classic (ver arriba)

# 3. Añadir preview.png (200x200)

# 4. Activar desde Back Office > Design > Theme & Logo
#    O por CLI: php bin/console prestashop:theme:enable my-classic-child

Con use_parent_assets: true y sin sobrescrituras, obtiene una copia idéntica de Classic. Plantillas, CSS, JS, tipos de imagen, layouts y sobrescrituras de plantillas de módulos se heredan automáticamente.

Crear un Child Theme para Hummingbird

Hummingbird utiliza Bootstrap 5.3 (propiedades personalizadas CSS), CSS Layers (@layer), TypeScript compilado con Webpack 5 y nomenclatura tipo BEM (.product__name, .product__description-short). La configuración es idéntica a Classic — cree theme.yml con parent: hummingbird y compatibilidad from: 9.0.0. La diferencia está en la personalización de assets.

Sistema de CSS Layers de Hummingbird

Hummingbird define este orden de capas en su SCSS:

@layer vendors, bs-base, bs-components, bs-custom-components,
       ps-base, ps-components, ps-pages, ps-modules, utilities;

Los estilos en capas posteriores sobrescriben a los anteriores independientemente de la especificidad del selector. Coloque las reglas personalizadas en la capa apropiada:

@layer ps-components {
  .product__name {
    font-family: 'Your Custom Font', sans-serif;
  }
}

@layer ps-pages {
  .page--category .product-miniature {
    border: 1px solid #eee;
    border-radius: 8px;
  }
}

Compilación SCSS

Para SCSS personalizado, añada un paso de compilación. Cree package.json con sass como dependencia de desarrollo y scripts para build:css (sass src/scss/custom.scss assets/css/custom.css --style=compressed) y watch:css. Luego ejecute npm install && npm run build:css para compilar.

Dart Sass puede anteponer un BOM UTF-8 al CSS compilado, causando que los navegadores ignoren reglas silenciosamente. Elimínelo: sed -i '1s/^\xEF\xBB\xBF//' assets/css/custom.css

Sobrescrituras de plantillas

Las sobrescrituras de plantillas son donde los child themes destacan. PrestaShop utiliza Smarty, que soporta un modelo de herencia limpio.

Orden de resolución de plantillas

1. Child theme — themes/my-child/templates/
2. Tema padre — themes/hummingbird/templates/

Método 1: Copia completa (Simple, menos mantenible)

Copie la plantilla del padre y edítela. Su versión reemplaza la del padre por completo:

cp themes/hummingbird/templates/catalog/product.tpl \
   themes/my-child/templates/catalog/product.tpl

Desventaja: Usted es responsable del archivo completo. Las actualizaciones del padre a esa plantilla no le llegarán.

Método 2: Smarty {extends} (Preferido)

Extienda la plantilla del padre y sobrescriba solo bloques específicos:

{extends file='parent:catalog/listing/category.tpl'}

{block name='product_list_header'}
  <div class="custom-category-header">
    <h1>{$category.name}</h1>
    <p>{$listing.págination.total_items} products</p>
  </div>
{/block}

El prefijo parent: es crítico — sin él, Smarty encuentra el propio archivo del child y crea un bucle infinito.

Modificadores de bloque

En lugar de reemplazar un bloque por completo, añada o anteponga contenido:

{extends file='parent:catalog/product.tpl'}

{block name='product_description' append}
  <div class="shipping-notice">Free shipping on orders over $50</div>
{/block}

{block name='product_prices' prepend}
  <span class="price-badge">Best Price</span>
{/block}

Estructura de bloques de Hummingbird

Puntos clave de sobrescritura en la página de producto de Hummingbird (catalog/product.tpl):

{block name='product_cover_thumbnails'}   — imágenes del producto
{block name='product_header'}              — nombre del producto (h1)
{block name='product_manufacturer'}        — enlace de marca
{block name='product_prices'}              — visualización de precios
{block name='product_description_short'}   — descripción corta
{block name='product_variants'}            — selectores de combinaciones
{block name='product_add_to_cart'}         — botón añadir al carrito
{block name='product_tabs'}               — acordeón de descripción/detalles
{block name='product_accessories'}         — productos relacionados

Para encontrar los bloques disponibles en cualquier página, lea el archivo de plantilla del tema padre — cada {block name='...'} es un punto de sobrescritura.

Personalización de CSS

Registrar CSS en theme.yml

assets:
  use_parent_assets: true
  css:
    all:
      - id: my-child-custom-style
        path: assets/css/custom.css
        media: all
        priority: 200

Los valores de priority más altos se cargan después, permitiéndole sobrescribir los estilos del padre. Para Hummingbird, prefiera declaraciones @layer en lugar de luchar contra la especificidad. Para Classic, iguale la profundidad de selectores del padre. Evite !important.

Cambiar el esquema de colores

Para Hummingbird (Bootstrap 5), sobrescriba las propiedades personalizadas CSS:

:root {
  --bs-primary: #2563eb;
  --bs-primary-rgb: 37, 99, 235;
  --bs-body-font-family: 'Inter', system-ui, sans-serif;
}

Personalización de JavaScript

Registrar JS en theme.yml

assets:
  use_parent_assets: true
  js:
    all:
      - id: my-child-custom-js
        path: assets/js/custom.js
        priority: 200

Reemplace all con un nombre de página para limitar los scripts: product, category, cart, checkout, cms, index (página de inicio), o cualquier nombre de controlador.

Eventos JavaScript de PrestaShop

Sus scripts pueden escuchar eventos de PrestaShop a través del objeto global prestashop:

prestashop.on('updatedProduct', function(event) { /* combination changed */ });
prestashop.on('updateCart', function(event) { /* cart updated */ });

Disponibilidad de jQuery

En Classic, jQuery se carga globalmente. En Hummingbird, jQuery 3.x aún se carga por compatibilidad con módulos, pero el tema en sí utiliza TypeScript. Para código nuevo de child theme, prefiera JavaScript vanilla.

No elimine jQuery de su child theme — romperá módulos de terceros que dependen de él. Pero para su propio código, JavaScript vanilla ofrece mejor rendimiento y compatibilidad futura.

Sobrescrituras de plantillas de módulos

Puede sobrescribir cómo se renderiza cualquier módulo colocando plantillas en el directorio modules/ de su tema.

Orden de resolución

1. Child theme: themes/my-child/modules/module_name/views/templates/...
2. Tema padre: themes/parent/modules/module_name/views/templates/...
3. El propio módulo: modules/module_name/views/templates/...

Cómo sobrescribir

Localice la plantilla del módulo (por ejemplo, modules/ps_featuredproducts/views/templates/hook/ps_featuredproducts.tpl), cópiela a la ruta correspondiente bajo themes/my-child/modules/ y edite la copia. El módulo puede actualizarse libremente sin afectar su versión.

Las sobrescrituras del tema tienen prioridad absoluta. Si un módulo actualiza su plantilla para corregir un problema de seguridad y su tema tiene una copia anterior, la versión antigua seguirá utilizándose. Compare periódicamente sus sobrescrituras con las versiones actuales de los módulos.

Traducciones en Child Themes

Orden de resolución de traducciones:

1. Traducciones de base de datos (Back Office > International > Translations)
2. Directorio translations/ del child theme
3. Directorio translations/ del tema padre
4. Traducciones del módulo
5. Traducciones del core

El enfoque más sencillo es el Back Office (International > Translations). Para traducciones con control de versiones, cree archivos XLIFF en themes/my-child/translations/en-US/Shop/Theme/Global.xlf:

<xliff xmlns="urn:oasis:names:tc:xliff:document:1.2" version="1.2">
  <file original="shop-theme-global" source-language="en-US"
        target-language="en-US" datatype="plaintext">
    <body>
      <trans-unit id="add_to_cart" approved="yes">
        <source>Add to cart</source>
        <target>Add to bag</target>
      </trans-unit>
    </body>
  </file>
</xliff>

Para tiendas multilingües, cree archivos por locale (translations/fr-FR/, translations/de-DE/). Limpie la caché después de los cambios: php bin/console cache:clear

Personalizaciones comunes

Maquetación personalizada del encabezado

{extends file='parent:_partials/header.tpl'}

{block name='header_nav'}
  <nav class="custom-header-nav container">
    <div class="row align-items-center">
      <div class="col-md-3">{hook h='displayNav1'}</div>
      <div class="col-md-6 text-center">
        <a href="{$urls.base_url}"><img src="{$shop.logo}" alt="{$shop.name}"></a>
      </div>
      <div class="col-md-3 text-end">{hook h='displayNav2'}</div>
    </div>
  </nav>
{/block}

Fuentes personalizadas

Coloque los archivos WOFF2 en assets/fonts/ y referéncielos en el CSS:

@font-face {
  font-family: 'CustomFont';
  src: url('../fonts/CustomFont-Regular.woff2') format('woff2');
  font-weight: 400;
  font-display: swap;
}
body { font-family: 'CustomFont', system-ui, sans-serif; }

Utilice siempre font-display: swap para evitar texto invisible durante la carga. Precargue las fuentes críticas: <link rel="preload" as="font" type="font/woff2" crossorigin>.

Reorganizar la página de producto

{extends file='parent:catalog/product.tpl'}

{block name='product_description_short'}
  <div class="product__description-short">{$product.description_short nofilter}</div>
  {if $product.description}
    <div class="product__description-full mt-3">{$product.description nofilter}</div>
  {/if}
{/block}

{block name='product_description'}{/block} {* removed from tabs *}

Cambios en temas de PS 9

• Hummingbird es el tema predeterminado. Classic sigue disponible, pero el desarrollo activo se centra en Hummingbird.
• Smarty se mantiene en el front office. Twig es solo para el panel de administración. Sus sobrescrituras con {extends} y {block} funcionan como antes.
• Bootstrap 5.3 reemplaza a Bootstrap 4. Consulte la guía de migración si migra desde Classic.
• CSS Layers (@layer) cambian el funcionamiento de la especificidad en Hummingbird.
• WebP por defecto para imágenes. Nueva clave framework en theme.yml: bootstrap-v5.3.3.
• Algunos globales JS legacy eliminados. Pruebe exhaustivamente al migrar desde PS 8.

Twig podría eventualmente llegar al front office en una futura versión mayor. Escribir plantillas limpias con sobrescrituras mínimas fácilitará cualquier futura transición.

Depuración de problemas con temas

Primero, limpie todas las cachés: php bin/console cache:clear. Para desarrollo, configure la caché de plantillas en "Forzar compilación" y desactive CCC en Advanced Parameters > Performance.

Durante el desarrollo, fuerce siempre la compilación de plantillas y desactive CCC. Sin esto, estará depurando archivos en caché.

Active la depuración de Smarty añadiendo ?SMARTY_DEBUG a cualquier URL del front. Esto muestra las plantillas cargadas, rutas de archivos y variables. Actívelo en config/defines.inc.php con _PS_SMARTY_FORCE_COMPILE_ y _PS_SMARTY_CONSOLE_ establecidos en 1.

Errores comunes

Si la caché persiste, elimine también var/cache/prod/smarty/compile/ y var/cache/prod/smarty/cache/.

Actualizaciones con Child Themes

Aquí es donde los child themes se pagan solos. Cuando el tema padre se actualiza:

• Archivos solo en el padre — se actualizan normalmente, el child los hereda automáticamente.
• Archivos sobrescritos en el child — la versión del child continúa utilizándose, la actualización del padre es invisible.
• Archivos exclusivos del child — no se ven afectados en absoluto.

Antes de actualizar: haga una copia de seguridad, liste sus sobrescrituras (find themes/my-child/templates -name "*.tpl"), actualice en un entorno de pruebas (guía de desarrollo local), compare con diff las plantillas padre modificadas contra sus sobrescrituras y pruebe cada página personalizada.

Las sobrescrituras dirigidas con {extends} son superiores a las copias completas de archivos. Con sobrescrituras de bloques, los nuevos bloques del padre se incluyen automáticamente. Las copias completas de archivos los omiten por completo.

Lista de verificación pre-lanzamiento del Child Theme

Configuración: theme.yml tiene parent: y name: correctos (minúsculas, sin espacios). use_parent_assets: true está configurado. preview.png existe. El rango de compatibilidad coincide con su versión de PS.

Plantillas: Todas las sobrescrituras usan {extends file='parent:...'} donde sea posible. Los nombres de bloques coinciden exactamente con los del padre. Sin errores de Smarty en var/logs/. Sobrescrituras de módulos probadas contra las versiones actuales de los módulos. nofilter utilizado para variables HTML.

Assets: El CSS personalizado se carga después del padre (alta priority). Sin abuso de !important. Las fuentes usan font-display: swap y WOFF2. Sin errores en la consola JS. CCC activado sin causar problemas.

Pruebas: Escritorio (Chrome, Firefox, Safari, Edge), móvil (iOS Safari, Android Chrome), puntos de corte responsive. Verificar: página de inicio, categorías, producto, carrito, checkout, cuenta de cliente, CMS, búsqueda, 404.

Mantenimiento: Child theme en Git. Plantillas sobrescritas documentadas. Proceso de compilación documentado (consulte nuestra guía de herramientas de desarrollo). El equipo sabe que no debe editar archivos del padre.