Istruzioni di installazione e configurazione di Countdown Promotion per Magento 2

Il modulo Kowal_CountdownPromotion aggiunge a Magento 2 un contatore di fine promozione. Il contatore può essere visibile nel listing di categoria e nella scheda prodotto quando il prodotto ha un prezzo speciale attivo e una data di fine promozione impostata.

Il contatore visibile viene creato da JavaScript dopo il caricamento della pagina. Il backend passa al frontend solo dati tecnici, tra cui l’ID del prodotto e il timestamp di fine promozione.

Requisiti

Prima dell’installazione assicurati che il negozio soddisfi i requisiti:

• Magento Open Source o Adobe Commerce 2.4.x,
• PHP 7.4 oppure PHP 8.1+ in base alla versione di Magento,
• possibilità di installare pacchetti Composer di tipo magento2-module,
• accesso alla CLI di Magento,
• accesso al repository del modulo.

Installazione tramite Composer

Vai alla directory principale del progetto Magento.

Per un repository Git, aggiungi il repository del modulo alla configurazione Composer:

composer config --global --auth github-oauth.github.com composer config repositories.kowal-countdown-promotion vcs https://github.com/kowalco/countdown-promotioncomposer require kowal/module-countdown-promotion

Dopo l’installazione, Composer collocherà il modulo nella directory:

vendor/kowal/module-countdown-promotion

Abilitazione del modulo in Magento

Esegui i comandi Magento dalla directory principale del negozio:

bin/magento module:enable Kowal_CountdownPromotionbin/magento setup:upgradebin/magento cache:flush

Nell’ambiente di produzione di solito è necessario eseguire anche i comandi di deployment utilizzati nel progetto:

bin/magento setup:di:compilebin/magento setup:static-content:deploy -fbin/magento indexer:reindexbin/magento cache:flush

Configurazione del prodotto

Per ogni prodotto accanto al quale deve comparire il contatore:

1. Imposta Countdown Promotion su Yes.
2. Imposta Special Price.
3. Imposta Special Price To Date.
4. Facoltativamente imposta Special Price From Date.

Il contatore verrà visualizzato solo se sono soddisfatte tutte le condizioni:

• l’attributo countdown_promotion è abilitato,
• special_price è impostato,
• il prezzo speciale è inferiore al prezzo regolare,
• special_from_date è vuoto oppure la promozione è già iniziata,
• special_to_date è impostato su una data futura.

Per i prodotti configurabili, abilita Countdown Promotion sul prodotto padre. Il modulo può usare la data di promozione del prodotto padre oppure le date di promozione attive dei prodotti semplici associati, quando la promozione è impostata sulle varianti.

Configurazione del modulo

Le opzioni del modulo sono disponibili nel pannello di amministrazione Magento:

Stores > Configuration > Catalog > Countdown Promotion > Appearance

Dopo aver modificato la configurazione, svuota la cache:

bin/magento cache:flush

Impostazioni della posizione del contatore

Il campo Category Placement definisce la posizione del contatore nel listing di categoria.

Opzioni disponibili:

• Below price - contatore sotto il prezzo,
• Bottom of product image - contatore nella parte inferiore dell’immagine del prodotto,
• Top of product image - contatore nella parte superiore dell’immagine del prodotto,
• Custom CSS selector - contatore accanto all’elemento indicato da un selettore CSS personalizzato.

Quando selezioni Custom CSS selector, compila il campo Category Custom CSS Selector. L’elemento selezionato dovrebbe avere data-product-id oppure trovarsi nel riquadro prodotto che contiene .price-box[data-product-id].

Selettori di esempio:

.price-box[data-product-id].product-item-info .price-box[data-product-id].product-item-details .price-box[data-product-id]

Il campo Product Page Custom CSS Selector riguarda solo la scheda prodotto. Inserisci il selettore dell’elemento dopo il quale deve essere aggiunto il contatore.

Esempi:

.product-info-main .product-info-price#custom-price-target

Se il campo è vuoto, il modulo usa il selettore predefinito:

.product-info-main .price-box

Impostazioni dei testi e del formato del tempo

Il campo Text Before Countdown imposta il testo prima del contatore, ad esempio:

Promocja kończy się za:

Se il campo è vuoto, l’etichetta prima del contatore non viene visualizzata e il solo valore del conto alla rovescia viene centrato.

Il campo Text Before End Date imposta il testo prima della data di fine promozione, ad esempio:

Promocja do:

Se il campo è vuoto, sotto il contatore viene visualizzata solo la data.

Il campo Displayed Time Template consente di scegliere l’intervallo delle unità di tempo mostrate nel contatore.

Template disponibili:

• 00d 00g 00m 00s,
• 00d 00g 00m,
• 00d 00g,
• 00d,
• 00g 00m 00s,
• 00m 00s.

I simboli delle unità di tempo possono essere modificati con campi separati:

• Days Symbol, per impostazione predefinita d,
• Hours Symbol, per impostazione predefinita g,
• Minutes Symbol, per impostazione predefinita m,
• Seconds Symbol, per impostazione predefinita s.

Esempio: se imposti Hours Symbol su h, il contatore può visualizzare 02d 05h 30m 10s invece di 02d 05g 30m 10s.

Visualizzazione del contatore solo prima della fine della promozione

Il campo Show Countdown Days Before End definisce quanti giorni prima della fine della promozione il contatore deve diventare visibile.

Esempi:

• campo vuoto - il contatore viene mostrato subito dopo il soddisfacimento delle condizioni della promozione,
• 1 - il contatore comparirà nell’ultimo giorno della promozione,
• 3 - il contatore comparirà negli ultimi 3 giorni della promozione,
• 7 - il contatore comparirà negli ultimi 7 giorni della promozione.

Il campo accetta numeri interi. Un valore vuoto indica nessuna limitazione.

Impostazioni dell’aspetto

Il modulo consente di configurare l’aspetto del contatore senza modifiche al codice.

Campi disponibili:

• Background Color - colore di sfondo,
• Text Color - colore base del testo,
• Label Color - colore dell’etichetta prima del contatore,
• Timer Color - colore del valore del conto alla rovescia,
• Border Color - colore del bordo,
• Font Size - dimensione del carattere.

I campi colore usano un color picker e salvano valori hex, ad esempio:

#ffffff#333333#d32f2f

La dimensione del carattere viene scelta da un elenco:

• 12px,
• 14px,
• 16px,
• 18px.

Controllo dopo l’implementazione

Dopo l’installazione e la configurazione, verifica:

1. Prodotto semplice con promozione attiva nella scheda prodotto.
2. Prodotto semplice con promozione attiva nel listing di categoria.
3. Prodotto senza prezzo speciale attivo.
4. Prodotto con data Special Price To Date nel passato.
5. Prodotto con Special Price To Date vuoto.
6. Prodotto con prezzo speciale uguale o superiore al prezzo regolare.
7. Configurazione Show Countdown Days Before End.
8. Diversi template Displayed Time Template.
9. Modifica dei simboli delle unità di tempo.
10. Modifica dei colori e della dimensione del carattere dopo lo svuotamento della cache.
11. Console del browser, per verificare che non siano presenti errori JavaScript.
12. Sorgente HTML grezzo, per verificare che non contenga un elemento .countdown-promotion già pronto.

Limitazioni note

Il modulo utilizza promozioni basate sui campi standard di Magento:

• special_price,
• special_from_date,
• special_to_date.

Le regole catalogo, Adobe Commerce Scheduled Updates e le varianti di prodotti configurabili con date di promozione completamente indipendenti possono richiedere un’integrazione separata.

I temi che modificano in modo significativo il rendering del prezzo o la struttura del riquadro prodotto possono richiedere l’impostazione di selettori CSS personalizzati.

Problemi più frequenti

Il contatore non è visibile

Verifica che:

• il prodotto abbia Countdown Promotion = Yes,
• il prodotto abbia Special Price impostato,
• il prezzo speciale sia inferiore al prezzo regolare,
• Special Price To Date sia impostato su una data futura,
• Special Price From Date non indichi una data futura,
• la cache Magento sia stata svuotata,
• per la categoria il selettore CSS impostato indichi l’elemento prodotto corretto.

Il contatore è nel posto sbagliato

Modifica Category Placement oppure imposta un Category Custom CSS Selector personalizzato. Nella scheda prodotto usa Product Page Custom CSS Selector.

Le modifiche dell’aspetto non sono visibili

Svuota la cache Magento:

bin/magento cache:flush

In produzione può essere necessario anche aggiornare gli asset statici in base al processo di deployment del negozio.