Instalação e configuração do módulo

Este documento descreve a instalação do módulo Kowal_RelatedProductsProfiles e a configuração básica de um perfil de recomendação de produtos no painel Magento.

Requisitos

• Magento 2 com suporte para módulos Composer.
• PHP compatível com o projeto: ^8.1, ^8.2 ou ^8.3.
• Módulo base kowal/base instalado, porque o menu administrativo utiliza a estrutura Kowal.co > Modules.
• Acesso administrativo à CLI do Magento.

Instalação via Composer

1. Adicione o repositório do módulo:

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

2. Configure os dados de acesso ao repositório Composer Kowal:

composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

3. Instale o módulo:

composer require kowal/module-related-products-profiles

4. Ative o módulo:

php bin/magento module:enable Kowal_RelatedProductsProfiles

5. Execute a atualização da base de dados:

php bin/magento setup:upgrade

Durante setup:upgrade, o módulo cria a tabela de perfis e executa um data patch com três perfis de exemplo: related, crossel, upsell. O patch não substitui perfis existentes com os mesmos códigos.

6. No modo de produção, reconstrua a dependency injection:

php bin/magento setup:di:compile

7. Limpe a cache:

php bin/magento cache:flush

Configuração global básica

Aceda a:

Stores > Configuration > Kowal > Related Product Profiles

Defina:

• Enable Frontend Output: Yes
• Enable Debug Logging: No em produção, Yes apenas para diagnosticar o funcionamento dos perfis

Guarde a configuração e limpe a cache se o Magento o solicitar.

Permissões administrativas

O módulo adiciona recursos ACL para perfis e configuração.

Acesso à lista de perfis:

Kowal > Modules > Related Product Profiles > Profiles

Acesso à configuração:

Stores > Settings > Configuration > Related Product Profiles Configuration

Para um utilizador demo que deve gerir apenas perfis, atribua a permissão Profiles. Se o utilizador também deve alterar a definição global de ativação do módulo, atribua também o recurso de configuração.

Onde gerir perfis

A lista de perfis está no menu:

Kowal.co > Modules > Related Product Profiles > Profiles

Na lista, pode adicionar um novo perfil, editar um perfil existente ou eliminar um perfil.

Exemplo de configuração de perfil Related Products

O exemplo abaixo cria um perfil que substitui o bloco nativo Magento Related Products na página de produto. Os produtos serão selecionados de acordo com o mesmo attribute_set_id, ou seja, do mesmo conjunto de atributos que o produto visualizado pelo cliente.

1. Criação do perfil

Aceda a:

Kowal.co > Modules > Related Product Profiles > Profiles

Clique em Add New Profile.

2. Secção General

Defina:

• Name: Related Products
• Code: related
• Is Active: selecionado
• Sort Order: 0
• Placements: selecione Product Page
• Store Views: selecione All Store Views
• Customer Groups: selecione All Customer Groups
• Context Strategy: First matching item
• From Date: vazio
• To Date: vazio

Notas:

• Na página de produto, o contexto é sempre o produto atualmente visualizado.
• Context Strategy tem significado prático sobretudo para o carrinho e o checkout.
• Code deve ser único.

3. Secção Activation Conditions

Adicione a condição:

Significado:

• O perfil será executado apenas se o produto de contexto estiver ativo.
• Se a condição não for cumprida, todo o perfil será ignorado.

4. Secção Matching Rules

Adicione a regra:

Significado:

• O módulo obterá attribute_set_id do produto atual.
• Depois encontrará produtos com o mesmo attribute_set_id.
• Required significa que o produto de destino deve cumprir esta regra.

Exemplos alternativos de regras:

• brand -> brand, operador Equals: produtos da mesma marca.
• category_ids -> category_ids, operador Category Intersects: produtos de pelo menos uma categoria em comum.
• color -> color, operador Equals: produtos da mesma cor.

5. Secção Target Product Filters

Adicione o filtro:

Significado:

• Nos resultados serão apresentados apenas produtos ativos.

Opcionalmente, pode adicionar um filtro de visibilidade:

6. Secção Sorting & Display

Defina:

• Sort Attribute: entity_id
• Sort Direction: DESC
• Secondary Sort Attribute: vazio
• Secondary Sort Direction: None
• Title: Related Products
• Subtitle: vazio
• Products Limit: 8
• Template Variant: Slider
• Image Role: category_page_grid
• Show Price: selecionado
• Show Old Price: não selecionado
• Show Add To Cart: selecionado
• Show Product Name: selecionado
• Show Short Description: não selecionado
• Show Badges: não selecionado
• Hide If Empty: selecionado
• Exclude Current Product: selecionado
• Exclude Quote Products: selecionado
• Exclude Out Of Stock: selecionado

Significado dos campos principais:

• Template Variant controla o aspeto da lista: Grid, Slider ou Compact.
• Products Limit limita o número de produtos nos resultados.
• Exclude Current Product impede que o produto atualmente visualizado apareça nos resultados.
• Exclude Out Of Stock remove produtos indisponíveis.

7. Secção Native Magento Lists

Para Related Products, defina:

• checkbox Related Products: selecionada
• Mode: Replace
• Position: Magento default position

Significado:

• Selecionar a checkbox significa que o módulo assume o bloco nativo Magento Related Products.
• Replace significa que no bloco assumido serão apresentados apenas produtos do perfil.
• Append significa que o módulo apresentará produtos nativos Magento mais produtos do perfil.
• Position permite mover o bloco para outro local da página de produto.

Exemplos de posições:

• Magento default position: deixa o bloco no local definido pelo tema Magento.
• sidebar.additional: move o bloco para a sidebar adicional.
• sidebar.main: move o bloco para a sidebar principal.
• content: move o bloco para o conteúdo principal da página.
• content.aside: move o bloco para a área lateral do content.
• product.info.main: move o bloco para a coluna principal de informações do produto.
• product.info.media: move o bloco para a área da galeria do produto.
• product.info.details: move o bloco para a área de detalhes ou separadores do produto.

Se o contentor selecionado não existir no tema atual, o Magento deixará o bloco no local predefinido.

Para Upsell Products e Crosssell Products, neste exemplo deixe as checkboxes não selecionadas.

8. Secção Layout XML

Para este exemplo, deixe os campos vazios:

• Product Page XML: vazio
• Edit Cart XML: vazio
• Checkout XML: vazio

Não é necessário adicionar XML se utilizar a secção Native Magento Lists. O XML é útil quando o perfil deve ser renderizado como um bloco adicional do módulo fora das listas nativas do Magento.

9. Guardar o perfil

Clique em:

• Save Profile, para guardar e voltar à lista de perfis
• Save and Continue, para guardar e permanecer no formulário

Depois de guardar, limpe a cache do Magento se o resultado não ficar imediatamente visível no frontend.

Exemplo de configuração de Upsell na sidebar

Se quiser mover Upsell Products para sidebar.additional:

1. Em Placements, selecione Product Page.
2. Em Native Magento Lists, selecione Upsell Products.
3. Defina Mode:
   • Append, se quiser apresentar upsells nativos Magento mais produtos do perfil.
   • Replace, se quiser apresentar apenas produtos do perfil.
4. Defina Position: Additional sidebar - sidebar.additional.
5. Escolha Template Variant: normalmente Compact adapta-se bem à sidebar.

Exemplo de configuração de Crosssell no carrinho

Para crosssell:

1. Em Placements, selecione Edit Cart.
2. Em Native Magento Lists, selecione Crosssell Products.
3. Defina Mode: geralmente Replace.
4. Position não está disponível para crosssell, porque atualmente o posicionamento aplica-se apenas aos blocos na página de produto.

Diagnóstico

Se o perfil não apresentar produtos:

1. Verifique se o módulo está ativado na configuração.
2. Verifique se o perfil tem Is Active selecionado.
3. Verifique se Placements corresponde ao local onde está a testar o perfil.
4. Verifique as condições em Activation Conditions.
5. Verifique se o produto de contexto tem valores dos atributos usados em Matching Rules.
6. Desative temporariamente Exclude Out Of Stock se estiver a testar em produtos sem stock.
7. Ative Enable Debug Logging apenas durante o diagnóstico.

Comandos após a implementação de alterações

Depois de atualizar o módulo, execute:

php bin/magento setup:upgradephp bin/magento cache:flush

No modo de produção, execute adicionalmente:

php bin/magento setup:di:compile