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 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 por JavaScript após o carregamento da página. O backend transmite ao frontend apenas dados técnicos, incluindo 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 através do Composer

Aceda ao diretório raiz do projeto Magento.

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

Os dados de acesso ao repositório Composer, endereço de e-mail do cliente e token de licença, serão enviados por e-mail após a compra. Também estão disponíveis na área de cliente depois de 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 irá 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

Em ambiente de produção, normalmente também deve executar os comandos de implementação usados 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á 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 usar 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 de posicionamento do contador

O campo Category Placement determina 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 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].

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 usa 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 selecionar o intervalo de unidades de tempo apresentado no contador.

Modelos 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.

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

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

Exemplos:

• campo vazio - o contador é apresentado imediatamente após as condições da promoção serem 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 limitação.

Definições de aparência

O módulo permite configurar a aparência 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 moldura,
• Font Size - tamanho do tipo de letra.

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

#ffffff#333333#d32f2f

O tamanho do tipo de letra é selecionado a partir da lista:

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

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

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

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

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 aponta para 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 página do produto, use Product Page Custom CSS Selector.

As alterações de aparência não estão visíveis

Limpe a cache do Magento:

bin/magento cache:flush

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