Instruções de instalação, configuração e implementação do módulo Kowal TrustedUs

Objetivo do módulo

Kowal TrustedUs é um módulo Magento 2 universal para apresentar empresas, clientes, parceiros, fornecedores, marcas e estudos de caso na loja.

O módulo pode ser utilizado como:

• secção 'Confiaram em nós',
• lista de parceiros ou fornecedores,
• portefólio de realizações,
• base de estudos de caso,
• secção que mostra utilizações dos produtos,
• ferramenta para reforçar a ligação interna na loja.

Após a expansão mais recente, os widgets podem encaminhar para páginas internas de estudos de caso, por exemplo:

/trusted-us/vitcas

Nessa página são apresentadas entradas do mesmo grupo e os produtos a elas associados.

Requisitos

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

• funciona em Magento 2,
• tem acesso ao Composer,
• tem acesso ao repositório do módulo,
• tem um token GitHub configurado, se o repositório for privado,
• permite executar comandos bin/magento,
• tem backup do código e da base de dados antes da implementação em produção.

Instalação através do Composer

1. Adicionar o repositório Composer

No diretório raiz do Magento, execute:

composer config repositories.kowal.trusted.us vcs https://github.com/kowalco/trusted-us

2. Adicionar o token de acesso

Se o repositório for privado, adicione o token GitHub:

composer config --global --auth github-oauth.github.com 

3. Instalação do módulo

composer require kowal/module-trustedus

4. Ativação do módulo

Nome do módulo Magento:

Kowal_TrustedUs

Ative o módulo:

php bin/magento module:enable Kowal_TrustedUs

5. Atualização do esquema da base de dados

php bin/magento setup:upgrade

Este comando irá criar ou atualizar as tabelas do módulo, incluindo o campo group_slug utilizado para páginas internas de estudos de caso.

6. Limpeza da cache

php bin/magento cache:flush

Instalação em modo de produção

Em ambiente de produção, recomenda-se o processo de implementação Magento padrão.

Sequência de exemplo:

composer require kowal/module-trustedusphp bin/magento module:enable Kowal_TrustedUsphp bin/magento setup:upgrade --keep-generatedphp bin/magento setup:di:compilephp bin/magento setup:static-content:deploy -fphp bin/magento cache:flush

Se a loja tiver o seu próprio pipeline CI/CD, os passos acima devem ser ajustados ao processo de implementação da loja.

Atualização de uma instalação existente

Se o módulo já estiver instalado, atualize-o através do Composer:

composer update kowal/module-trustedus

Em seguida, execute:

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

Em modo de produção:

php bin/magento setup:upgrade --keep-generatedphp bin/magento setup:di:compilephp bin/magento setup:static-content:deploy -fphp bin/magento cache:flush

Configuração no painel de administração

Aceder à lista de empresas

Após a instalação, aceda no painel Magento a:

Content -> Zaufali nam -> Firmy

Consoante a configuração do menu, a entrada também pode estar disponível na secção:

Trusted Us -> Firmy

Adicionar uma empresa ou estudo de caso

Ao adicionar uma nova entrada, preencha os dados básicos:

• Nome da empresa - nome do cliente, parceiro, fornecedor, marca ou projeto.
• Endereço do website (URL) - endereço externo opcional; atualmente, os widgets criam links internos se a entrada tiver o slug de grupo definido.
• Grupo de estudo de caso / slug URL - slug global utilizado para agrupar entradas e construir o link interno.
• Nome do projeto - título da realização ou estudo de caso descritivo.
• Breve descrição do projeto - conteúdo apresentado junto da entrada.
• Ícone - logótipo da empresa ou marca.
• Ativa - determina se a entrada é visível no frontend.
• Mostrar no widget de empresas destacadas - determina se a entrada será incluída no widget destacado.
• Ordem - ordenação das entradas.
• Products - produtos associados à entrada.

Configuração de agrupamento e links internos

O campo Grupo de estudo de caso / slug URL serve para ligar várias entradas da mesma empresa numa única página interna.

Exemplo:

vitcas

Todas as entradas ativas com o mesmo slug ficarão visíveis na página:

/trusted-us/vitcas

Se introduzir um valor com espaços ou letras maiúsculas, o módulo irá guardá-lo como um slug seguro.

Exemplo:

Tandem Baits

será guardado como:

tandem-baits

Configuração de produtos associados

Na secção Produtos / módulos associados selecione os produtos que devem ser associados a determinada empresa, realização ou estudo de caso.

Estas associações são utilizadas em dois locais:

• na página de produto, onde o módulo pode mostrar empresas ou realizações associadas,
• na página de estudo de caso /trusted-us/{slug}, onde os produtos são apresentados numa grelha semelhante à das categorias de produtos.

Configuração do widget padrão

Na edição de uma página CMS, página inicial, landing page ou bloco CMS, adicione o widget:

Kowal: Zaufali nam

Parâmetros disponíveis:

• Título - cabeçalho da secção.
• Limite - número máximo de entradas apresentadas.
• Mostrar nome do projeto - define se o nome do projeto deve ficar visível abaixo do logótipo.

Se a entrada tiver o campo group_slug preenchido, o clique no logótipo conduz à página interna:

/trusted-us/{slug}

Se group_slug estiver vazio, a entrada permanece sem link.

Configuração do widget de empresas destacadas

Na edição CMS, adicione o widget:

Kowal: Zaufali nam - wyróżnione firmy

Parâmetros disponíveis:

• Cabeçalho - texto principal da secção.
• Limite - número máximo de entradas apresentadas.

O widget mostra apenas entradas ativas que tenham marcada a opção:

Pokaż w widgecie wyróżnionych firm

Tal como o widget padrão, pode criar links para páginas internas de estudos de caso com base no campo group_slug.

Secção na página de produto

Se o produto tiver empresas ou estudos de caso associados, o módulo pode mostrar automaticamente uma secção na página de produto.

A secção apresenta:

• logótipo da empresa,
• nome da empresa,
• nome do projeto,
• breve descrição do projeto.

Isto permite mostrar a utilização real do produto e reforçar a credibilidade da oferta.

Páginas de estudos de caso

As páginas de estudos de caso estão disponíveis no endereço:

/trusted-us/{slug}

Exemplo:

/trusted-us/vitcas

Na página são apresentados:

• todas as entradas ativas com o mesmo group_slug,
• descrições dos estudos de caso,
• logótipo da empresa,
• produtos associados a cada entrada,
• grelha de produtos semelhante à grelha de categorias.

Estas páginas aumentam o número de links internos e criam um percurso adicional:

widget -> case study -> produkt

Suporte para várias store views

O módulo suporta conteúdos dependentes da store view para os campos:

• nome do projeto,
• breve descrição do projeto.

Campos globais, como nome da empresa, logótipo, estado de atividade, ordenação, produtos associados e group_slug, são comuns a toda a entrada.

Diretório de media

Os logótipos são guardados no diretório:

pub/media/kowal/trustedus/

Antes da implementação, certifique-se de que o diretório pub/media é corretamente partilhado ou sincronizado entre ambientes, se a loja funcionar numa arquitetura multiservidor.

Checklist de implementação

Antes da implementação:

• faça backup da base de dados,
• faça backup do código ou certifique-se de que a implementação é reproduzível a partir do repositório,
• verifique o acesso ao repositório Composer,
• verifique o token GitHub, se for necessário,
• planeie uma janela de implementação, se a loja estiver em produção.

Após a implementação:

• execute setup:upgrade,
• limpe a cache,
• em modo de produção, execute a compilação DI e o deployment static content,
• verifique se o módulo está ativo,
• adicione ou edite uma empresa de teste,
• defina group_slug,
• associe um produto,
• adicione o widget numa página CMS de teste,
• clique no logótipo e verifique a página /trusted-us/{slug},
• verifique se a grelha de produtos apresenta os produtos associados ao estudo de caso,
• verifique a página de produto com entradas associadas.

Comandos de diagnóstico

Verificar o estado do módulo:

php bin/magento module:status Kowal_TrustedUs

Verificar a lista de módulos Kowal:

php bin/magento module:status | grep Kowal

Limpar a cache:

php bin/magento cache:flush

Recompilação DI:

php bin/magento setup:di:compile

Problemas mais frequentes

O widget não cria link para a página de estudo de caso

Verifique se a entrada tem o campo preenchido:

Grupa case study / slug URL

Um elemento sem group_slug não é ligado a uma página interna.

A página /trusted-us/{slug} não funciona

Verifique:

• se existe uma entrada ativa com o respetivo group_slug,
• se setup:upgrade foi executado,
• se a cache foi limpa,
• se o módulo Kowal_TrustedUs está ativo.

Os produtos não aparecem na página de estudo de caso

Verifique:

• se os produtos estão associados à entrada da empresa,
• se os produtos estão ativos,
• se os produtos estão visíveis no catálogo ou na pesquisa,
• se os produtos estão disponíveis na store view atual.

As alterações não ficam visíveis após a implementação

Limpe a cache Magento:

php bin/magento cache:flush

Em modo de produção, execute também:

php bin/magento setup:di:compilephp bin/magento setup:static-content:deploy -f

Desinstalação

Desativar o módulo:

php bin/magento module:disable Kowal_TrustedUsphp bin/magento setup:upgradephp bin/magento cache:flush

Remover o pacote Composer:

composer remove kowal/module-trustedus

Antes de remover o módulo da produção, deve verificar se a loja não utiliza widgets, blocos CMS ou conteúdos dependentes do módulo.