Instruções de instalação e configuração do Countdown Promotion para Magento 2

O módulo Kowal_CountdownPromotion adiciona ao Magento 2 um contador de fim de promoção. O contador pode ficar visível na listagem de categorias e na ficha do produto quando o produto tem um preço especial ativo e uma data de fim da promoção definida.

O contador visível é criado por JavaScript após o carregamento da página. O backend envia para o frontend apenas dados técnicos, entre outros o ID do produto e o timestamp de fim da promoção.

Requisitos

Antes da instalação, certifique-se de que a loja cumpre os requisitos:

• Magento Open Source ou Adobe Commerce 2.4.x,
• PHP 7.4 ou PHP 8.1+ de acordo com a versão do Magento,
• possibilidade de instalar pacotes Composer do tipo magento2-module,
• acesso à CLI do Magento,
• acesso ao repositório do módulo.

Instalação via Composer

Aceda ao diretório raiz do projeto Magento.

Para o repositório Git, adicione o repositório do módulo à configuração do 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

Após a instalação, o Composer colocará o módulo no diretório:

vendor/kowal/module-countdown-promotion

Ativação do módulo no Magento

Execute os comandos Magento a partir do diretório raiz da loja:

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

Num ambiente de produção, normalmente também é necessário executar os comandos de implementação utilizados no projeto:

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

Configuração do produto

Para cada produto junto do qual o contador deve aparecer:

1. Defina Countdown Promotion como Yes.
2. Defina Special Price.
3. Defina Special Price To Date.
4. Opcionalmente, defina Special Price From Date.

O contador só será apresentado quando todas as condições forem cumpridas:

• o atributo countdown_promotion está ativado,
• special_price está definido,
• o preço especial é inferior ao preço regular,
• special_from_date está vazio ou a promoção já começou,
• special_to_date está definido no futuro.

Para produtos configuráveis, ative Countdown Promotion no produto principal. O módulo pode utilizar a data da promoção do produto principal ou as datas de promoção ativas dos produtos simples associados, quando a promoção está definida nas variantes.

Configuração do módulo

As opções do módulo estão disponíveis no painel de administração do Magento:

Stores > Configuration > Catalog > Countdown Promotion > Appearance

Depois de alterar a configuração, limpe a cache:

bin/magento cache:flush

Definições da posição do contador

O campo Category Placement define a posição do contador na listagem de categorias.

Opções disponíveis:

• Below price - contador abaixo do preço,
• Bottom of product image - contador na parte inferior da imagem do produto,
• Top of product image - contador na parte superior da imagem do produto,
• Custom CSS selector - contador junto ao elemento indicado por um seletor CSS personalizado.

Quando selecionar Custom CSS selector, preencha o campo Category Custom CSS Selector. O elemento selecionado deve ter data-product-id ou estar dentro do bloco do produto que contém .price-box[data-product-id].

Seletores de exemplo:

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

O campo Product Page Custom CSS Selector aplica-se apenas à ficha do produto. Introduza o seletor do elemento após o qual o contador deve ser adicionado.

Exemplos:

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

Se o campo estiver vazio, o módulo utiliza o seletor predefinido:

.product-info-main .price-box

Definições de textos e formato de tempo

O campo Text Before Countdown define o texto antes do contador, por exemplo:

Promocja kończy się za:

Se o campo estiver vazio, a etiqueta antes do contador não é apresentada e o próprio valor da contagem decrescente é centrado.

O campo Text Before End Date define o texto antes da data de fim da promoção, por exemplo:

Promocja do:

Se o campo estiver vazio, apenas a data é apresentada por baixo do contador.

O campo Displayed Time Template permite selecionar o intervalo de unidades de tempo apresentadas no contador.

Templates disponíveis:

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

Os símbolos das unidades de tempo podem ser alterados em campos separados:

• Days Symbol, por defeito d,
• Hours Symbol, por defeito g,
• Minutes Symbol, por defeito m,
• Seconds Symbol, por defeito s.

Exemplo: se definir Hours Symbol como h, o contador pode apresentar 02d 05h 30m 10s em vez de 02d 05g 30m 10s.

Apresentar o contador apenas antes do fim da promoção

O campo Show Countdown Days Before End define quantos dias antes do fim da promoção o contador deve ficar visível.

Exemplos:

• campo vazio - o contador é apresentado assim que as condições da promoção forem cumpridas,
• 1 - o contador aparecerá no último dia da promoção,
• 3 - o contador aparecerá nos últimos 3 dias da promoção,
• 7 - o contador aparecerá nos últimos 7 dias da promoção.

O campo aceita números inteiros. Um valor vazio significa ausência de limite.

Definições de aspeto

O módulo permite configurar o aspeto do contador sem alterações no código.

Campos disponíveis:

• Background Color - cor de fundo,
• Text Color - cor base do texto,
• Label Color - cor da etiqueta antes do contador,
• Timer Color - cor do valor da contagem decrescente,
• Border Color - cor da borda,
• Font Size - tamanho da fonte.

Os campos de cor usam um color picker e guardam valores hex, por exemplo:

#ffffff#333333#d32f2f

O tamanho da fonte é selecionado a partir de uma lista:

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

Verificação após a implementação

Após a instalação e configuração, verifique:

1. Produto simples com promoção ativa na ficha do produto.
2. Produto simples com promoção ativa na listagem de categorias.
3. Produto sem preço especial ativo.
4. Produto com a data Special Price To Date no passado.
5. Produto com Special Price To Date vazio.
6. Produto com preço especial igual ou superior ao preço regular.
7. A configuração Show Countdown Days Before End.
8. Diferentes templates Displayed Time Template.
9. A alteração dos símbolos das unidades de tempo.
10. A alteração das cores e do tamanho da fonte depois de limpar a cache.
11. A consola do navegador, para verificar se não existem erros JavaScript.
12. O código-fonte HTML bruto, para verificar se não contém um elemento .countdown-promotion pronto.

Limitações conhecidas

O módulo utiliza promoções baseadas nos campos padrão do Magento:

• special_price,
• special_from_date,
• special_to_date.

Regras de catálogo, Adobe Commerce Scheduled Updates e variantes de produtos configuráveis com datas de promoção totalmente independentes podem exigir uma integração separada.

Temas que alteram significativamente a renderização do preço ou a estrutura do bloco do produto podem exigir a definição de seletores CSS personalizados.

Problemas mais frequentes

O contador não está visível

Verifique se:

• o produto tem Countdown Promotion = Yes,
• o produto tem Special Price definido,
• o preço especial é inferior ao preço regular,
• Special Price To Date está definido no futuro,
• Special Price From Date não indica uma data futura,
• a cache do Magento foi limpa,
• para a categoria, o seletor CSS definido aponta para o elemento correto do produto.

O contador está no local errado

Altere Category Placement ou defina um Category Custom CSS Selector personalizado. Na ficha do produto, utilize Product Page Custom CSS Selector.

As alterações de aspeto não estão visíveis

Limpe a cache do Magento:

bin/magento cache:flush

Em produção, também pode ser necessário atualizar os assets estáticos de acordo com o processo de implementação da loja.