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 do fim da promoção. O contador pode estar visível na listagem da categoria e na página 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 pelo JavaScript após o carregamento da página. O backend transmite para o frontend apenas dados técnicos, entre outros, o ID do produto e o timestamp do 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.

Adicione o repositório Composer Kowal à configuração do projeto:

Receberá os dados de acesso ao repositório Composer, endereço de e-mail do cliente e token de licença, por e-mail após a compra. Também estão disponíveis no painel do cliente após iniciar sessão em kowal.store. Substitua TWOJ_EMAIL_KLIENTA pelo endereço de e-mail da sua conta e TWOJ_TOKEN pelo token recebido. Execute os comandos no diretório raiz do Magento.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'composer 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

No ambiente de produção, normalmente também deve 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 em que 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ó aparecerá quando todas as condições forem cumpridas:

• o atributo countdown_promotion está ativo,
• special_price está definido,
• o preço especial é inferior ao preço normal,
• 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 estiver 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

Após 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 da categoria.

Opções disponíveis:

• Below price - contador por baixo 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 próprio.

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

Exemplos de seletores:

.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 à página 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 dos textos e do 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 fica 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 escolher o intervalo de unidades de tempo mostrado 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 predefinição d,
• Hours Symbol, por predefinição g,
• Minutes Symbol, por predefinição m,
• Seconds Symbol, por predefinição s.

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

Mostrar 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 tornar-se visível.

Exemplos:

• campo vazio - o contador é apresentado assim que as condições da promoção forem cumpridas,
• 1 - o contador aparece no último dia da promoção,
• 3 - o contador aparece nos últimos 3 dias da promoção,
• 7 - o contador aparece 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 margem,
• 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 página do produto.
2. Produto simples com promoção ativa na listagem da categoria.
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 normal.
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 após limpar a cache.
11. A consola do navegador, para verificar se não existem erros JavaScript.
12. O código-fonte HTML bruto, para confirmar que não contém um elemento .countdown-promotion já 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 próprios.

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 normal,
• 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 próprio. Na página 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.