Child Themes PrestaShop: Guida alla personalizzazione Classic e Hummingbird

Cos’è un Child Theme e Perché È Importante

Un child theme eredita i template e gli asset da un tema genitore, permettendovi di sovrascrivere solo ciò che modificate. Senza, ogni modifica CSS o modifica ai template risiede nei file del genitore — e viene sovrascritta al prossimo aggiornamento.

Un child theme è una sovrapposizione trasparente. PrestaShop cerca prima nel child. Se trova un file, lo utilizza. In caso contrario, ricade sul genitore. Includete solo ciò che modificate.

Usate un child theme per modifiche mirate — colori, aggiustamenti di layout, override dei template, CSS/JS personalizzati. Costruite un tema personalizzato completo solo quando avete bisogno di un’architettura fondamentalmente diversa.

Per nuovi progetti su PrestaShop 8.1+, scegliete Hummingbird — è il tema predefinito orientato al futuro e l’unico tema attivamente mantenuto dal progetto PrestaShop.

Struttura del Child Theme

Un child theme risiede accanto al suo genitore all’interno di /themes/. Il child theme minimo richiede solo due file:

themes/my-child-theme/
  config/
    theme.yml             <-- obbligatorio: configurazione del tema
  preview.png             <-- obbligatorio: anteprima 200x200 del tema

Man mano che le personalizzazioni crescono, la directory rispecchia la struttura del genitore ma contiene solo i file modificati:

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

Aggiungete solo i file che state modificando. Ogni file aggiunto è un file che dovete mantenere. Un child theme vuoto che eredita tutto è meglio di uno ingombro di copie invariate.

La Configurazione theme.yml

Il file config/theme.yml è il cuore del vostro child theme. La riga fondamentale è parent: classic (o parent: hummingbird) — questa stabilisce la catena di ereditarietà:

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

Creare un Child Theme per Classic

Classic è il tema predefinito originale di PrestaShop dalla versione 1.7. Il processo si svolge in quattro passaggi:

# 1. Create the directory
mkdir -p themes/my-classic-child/config

# 2. Create config/theme.yml with parent: classic (see above)

# 3. Add preview.png (200x200)

# 4. Activate via Back Office > Design > Theme & Logo
#    Or CLI: php bin/console prestashop:theme:enable my-classic-child

Con use_parent_assets: true e nessun override, ottenete una copia perfetta al pixel di Classic. Template, CSS, JS, tipi di immagine, layout e override dei template dei moduli vengono tutti ereditati.

Creare un Child Theme per Hummingbird

Hummingbird utilizza Bootstrap 5.3 (proprietà personalizzate CSS), CSS Layers (@layer), TypeScript compilato con Webpack 5 e nomenclatura BEM-like (.product__name, .product__description-short). La configurazione è identica a Classic — create theme.yml con parent: hummingbird e compatibilità from: 9.0.0. La differenza sta nella personalizzazione degli asset.

Il Sistema CSS Layer di Hummingbird

Hummingbird definisce questo ordine di layer nel suo SCSS:

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

Gli stili nei layer successivi sovrascrivono quelli precedenti indipendentemente dalla specificità del selettore. Posizionate le regole personalizzate nel layer appropriato:

@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;
  }
}

Compilazione SCSS

Per SCSS personalizzato, aggiungete uno step di build. Create package.json con sass come dipendenza di sviluppo e script per build:css (sass src/scss/custom.scss assets/css/custom.css --style=compressed) e watch:css. Poi npm install && npm run build:css per compilare.

Dart Sass può anteporre un BOM UTF-8 al CSS compilato, causando l’ignoramento silenzioso delle regole da parte dei browser. Rimuovetelo: sed -i '1s/^\xEF\xBB\xBF//' assets/css/custom.css

Override dei Template

Gli override dei template sono il punto di forza dei child theme. PrestaShop utilizza Smarty, che supporta un modello di ereditarietà pulito.

Ordine di Risoluzione dei Template

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

Metodo 1: Copia Completa (Semplice, Meno Manutenibile)

Copiate il template del genitore e modificatelo. La vostra versione sostituisce interamente quella del genitore:

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

Svantaggio: Diventate responsabili dell’intero file. Gli aggiornamenti del genitore a quel template non vi raggiungeranno.

Metodo 2: Smarty {extends} (Preferito)

Estendete il template del genitore e sovrascrivete solo blocchi specifici:

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

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

Il prefisso parent: è fondamentale — senza di esso, Smarty trova il file del child stesso e crea un loop infinito.

Modificatori di Blocco

Invece di sostituire un blocco interamente, aggiungete contenuto in coda o in testa:

{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}

Struttura dei Blocchi di Hummingbird

Punti chiave di override nella pagina prodotto di Hummingbird (catalog/product.tpl):

{block name='product_cover_thumbnails'}   → immagini prodotto
{block name='product_header'}              → nome prodotto (h1)
{block name='product_manufacturer'}        → link del brand
{block name='product_prices'}              → visualizzazione prezzo
{block name='product_description_short'}   → descrizione breve
{block name='product_variants'}            → selettori combinazioni
{block name='product_add_to_cart'}         → pulsante aggiungi al carrello
{block name='product_tabs'}               → accordion descrizione/dettagli
{block name='product_accessories'}         → prodotti correlati

Per trovare i blocchi disponibili in qualsiasi pagina, leggete il file template del tema genitore — ogni {block name='...'} è un punto di override.

Personalizzazione CSS

Registrare il CSS in theme.yml

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

Valori di priority più alti vengono caricati dopo, permettendovi di sovrascrivere gli stili del genitore. Per Hummingbird, preferite le dichiarazioni @layer invece di combattere la specificità. Per Classic, equiparate la profondità del selettore del genitore. Evitate !important.

Cambiare la Combinazione di Colori

Per Hummingbird (Bootstrap 5), sovrascrivete le proprietà personalizzate CSS:

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

Personalizzazione JavaScript

Registrare JS in theme.yml

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

Sostituite all con il nome di una pagina per limitare gli script: product, category, cart, checkout, cms, index (homepage), o qualsiasi nome di controller.

Eventi JavaScript di PrestaShop

I vostri script possono ascoltare gli eventi di PrestaShop tramite il globale prestashop:

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

Disponibilità di jQuery

In Classic, jQuery viene caricato globalmente. In Hummingbird, jQuery 3.x viene ancora caricato per la compatibilità con i moduli, ma il tema stesso utilizza TypeScript. Per il nuovo codice del child theme, preferite il JS vanilla.

Non rimuovete jQuery dal vostro child theme — rompereste i moduli di terze parti che ne dipendono. Ma per il vostro codice, il JS vanilla offre migliori prestazioni e compatibilità futura.

Override dei Template dei Moduli

Potete sovrascrivere il modo in cui qualsiasi modulo viene renderizzato posizionando i template nella directory modules/ del vostro tema.

Ordine di Risoluzione

1. Child theme: themes/my-child/modules/module_name/views/templates/...
2. Tema genitore: themes/parent/modules/module_name/views/templates/...
3. Modulo stesso: modules/module_name/views/templates/...

Come Sovrascrivere

Trovate il template del modulo (es. modules/ps_featuredproducts/views/templates/hook/ps_featuredproducts.tpl), copiatelo nel percorso corrispondente sotto themes/my-child/modules/ e modificate la copia. Il modulo può aggiornarsi liberamente senza influenzare la vostra versione.

Gli override del tema hanno priorità assoluta. Se un modulo aggiorna il suo template per correggere un problema di sicurezza e il vostro tema ha una copia più vecchia, la vecchia versione continua a essere utilizzata. Confrontate periodicamente i vostri override con le versioni attuali dei moduli.

Traduzioni nei Child Theme

Ordine di risoluzione delle traduzioni:

1. Traduzioni nel database (Back Office > International > Translations)
2. Directory translations/ del child theme
3. Directory translations/ del tema genitore
4. Traduzioni dei moduli
5. Traduzioni del core

L’approccio più semplice è il Back Office (International > Translations). Per traduzioni sotto controllo di versione, create file XLIFF in 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>

Per negozi multilingua, create file per ogni locale (translations/fr-FR/, translations/de-DE/). Svuotate la cache dopo le modifiche: php bin/console cache:clear

Personalizzazioni Comuni

Layout Header Personalizzato

{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}

Font Personalizzati

Posizionate i file WOFF2 in assets/fonts/ e referenziateli nel 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; }

Utilizzate sempre font-display: swap per evitare testo invisibile durante il caricamento. Precaricate i font critici: <link rel="preload" as="font" type="font/woff2" crossorigin>.

Riorganizzare la Pagina Prodotto

{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 *}

Modifiche ai Temi in PS 9

• Hummingbird è il tema predefinito. Classic rimane disponibile ma lo sviluppo attivo è rivolto a Hummingbird.
• Smarty resta per il front office. Twig è solo per il pannello di amministrazione. I vostri override {extends} e {block} funzionano come prima.
• Bootstrap 5.3 sostituisce Bootstrap 4. Consultate la guida alla migrazione se passate da Classic.
• CSS Layers (@layer) cambiano il funzionamento della specificità in Hummingbird.
• WebP predefinito per le immagini. Nuova chiave framework in theme.yml: bootstrap-v5.3.3.
• Alcune variabili globali JS legacy rimosse. Testate accuratamente durante la migrazione da PS 8.

Twig potrebbe eventualmente raggiungere il front office in una futura versione major. Scrivere template puliti con override minimi faciliterà qualsiasi futura transizione.

Debug dei Problemi del Tema

Per prima cosa, svuotate tutte le cache: php bin/console cache:clear. Per lo sviluppo, impostate la cache dei Template su “Forza compilazione” e disabilitate CCC in Parametri Avanzati > Prestazioni.

Durante lo sviluppo, forzate sempre la compilazione dei template e disabilitate CCC. Senza questo, state facendo debug su file in cache.

Abilitate il debug di Smarty aggiungendo ?SMARTY_DEBUG a qualsiasi URL del front-end. Questo mostra i template caricati, i percorsi dei file e le variabili. Abilitatelo in config/defines.inc.php con _PS_SMARTY_FORCE_COMPILE_ e _PS_SMARTY_CONSOLE_ impostati a 1.

Errori Comuni

Se la cache persiste, eliminate anche var/cache/prod/smarty/compile/ e var/cache/prod/smarty/cache/.

Aggiornamenti con i Child Theme

Qui i child theme ripagano l’investimento. Quando il genitore si aggiorna:

• File presenti solo nel genitore — vengono aggiornati normalmente, il child li eredita automaticamente.
• File sovrascritti nel child — la versione del child continua a essere utilizzata, l’aggiornamento del genitore è invisibile.
• File personalizzati solo nel child — completamente non influenzati.

Prima di aggiornare: fate un backup, elencate i vostri override (find themes/my-child/templates -name "*.tpl"), aggiornate in un ambiente di staging (guida allo sviluppo locale), confrontate con diff i template del genitore modificati rispetto ai vostri override e testate ogni pagina personalizzata.

Gli override mirati con {extends} sono superiori alle copie complete dei file. Con gli override dei blocchi, i nuovi blocchi del genitore vengono inclusi automaticamente. Le copie complete dei file li perdono interamente.

Checklist Pre-Lancio del Child Theme

Configurazione: theme.yml ha parent: e name: corretti (minuscolo, senza spazi). use_parent_assets: true è impostato. preview.png esiste. L’intervallo di compatibilità corrisponde alla vostra versione PS.

Template: Tutti gli override usano {extends file='parent:...'} dove possibile. I nomi dei blocchi corrispondono esattamente a quelli del genitore. Nessun errore Smarty in var/logs/. Gli override dei moduli sono testati rispetto alle versioni attuali dei moduli. nofilter utilizzato per le variabili HTML.

Asset: Il CSS personalizzato viene caricato dopo quello del genitore (alta priority). Nessun uso eccessivo di !important. I font usano font-display: swap e WOFF2. Nessun errore JS nella console. CCC abilitato senza causare problemi.

Test: Desktop (Chrome, Firefox, Safari, Edge), mobile (iOS Safari, Android Chrome), breakpoint responsive. Verificate: homepage, categorie, prodotto, carrello, checkout, account cliente, CMS, ricerca, 404.

Manutenzione: Child theme in Git. Template sovrascritti documentati. Processo di build documentato (consultate la nostra guida agli strumenti di sviluppo). Il team sa di non modificare i file del genitore.