Product Features - instalação, configuração e gestão de atributos

Este documento descreve a configuração do módulo kowal/module-product-features, o significado de todos os campos administrativos e o trabalho com atributos do lado do produto.

Instalação

O módulo foi concebido para instalação através do Composer.

composer config repositories.module.product.features vcs https://github.com/kowalco/product-featurescomposer config --global --auth github-oauth.github.com composer require kowal/module-product-featuresbin/magento module:enable Kowal_ProductFeaturesbin/magento setup:upgradebin/magento cache:flush

Após a implementação em produção, devem ser executados os comandos padrão adequados ao projeto, por exemplo, compilação DI e deploy de assets estáticos, de acordo com o modo de funcionamento do Magento.

Localização da configuração

A configuração do módulo encontra-se no painel de administração do Magento:

Stores > Configuration > Catalog > Product Features

As definições de aspeto encontram-se num grupo separado:

Stores > Configuration > Catalog > Product Features Appearance

Os campos de configuração estão disponíveis ao nível Default, Website e Store View. Graças a isso, diferentes vistas da loja podem ter secções de características ou aspetos diferentes.

Product Features

Enabled

Ativa ou desativa o módulo para o âmbito de configuração em questão.

Valores:

• Yes - as secções de características do produto são renderizadas na página do produto,
• No - o módulo não devolve secções e o bloco não aparece no frontend.

Utilização: desativação rápida do módulo para toda a loja, um Website selecionado ou um Store View sem remover a configuração das secções.

Feature Sections

Lista de secções renderizadas na página do produto. Cada linha define uma secção de frontend ou um grupo de secções, se for utilizado o tipo cms_blocks.

Enabled

Ativa ou desativa uma secção individual.

Valores:

• Yes - a secção participa na renderização,
• No - a secção é ignorada.

Utilização: ocultação temporária de uma secção sem apagar as suas definições.

Section Title

Título da secção visível na página do produto.

Exemplos:

• Características do produto,
• Aplicação desportiva,
• Especificações,
• Tecnologias,
• Entrega.

Utilização: o nome deve ser compreensível para o cliente, não tem de corresponder ao nome técnico do atributo.

Nota: para o tipo cms_blocks o título da secção filha é obtido a partir do título do bloco CMS.

Attribute Code

Atributo de produto único utilizado pela secção. O campo tem a forma de dropdown com a lista de atributos do produto.

Utilização: utilize este campo quando a secção se baseia num único atributo, por exemplo, sport_usage, blocks_id, material, technology_icon.

Attribute Codes

Lista de vários atributos de produto utilizados por uma única secção. O campo tem a forma de multiselect.

Utilização: utilize este campo quando uma secção deve agregar várias características, por exemplo, várias escalas na secção Características do produto ou vários parâmetros na secção Especificações.

Exemplo: a secção Características do produto pode conter os atributos fit, resistance, stretch e breathability, todos renderizados como escalas.

Display Type

Define a forma de apresentação do valor do atributo.

O valor vazio Auto significa seleção automática do renderer:

• blocks_id é renderizado como cms_blocks,
• swatch multiselect como swatch_list,
• select com 2 ou 3 opções como scale,
• select com maior número de opções como selected_label,
• multiselect como text_list,
• boolean como checkmark,
• date como date,
• price como price,
• textarea como text_block,
• image/media_image como image,
• os restantes tipos como text_inline.

Tipos disponíveis:

No painel de administração, algumas posições estão assinaladas como available in future release. Isto diz respeito a tipos que já estão visíveis na lista de configuração, mas que ainda não têm a sua apresentação final própria no frontend:

• table,
• badge,
• badge_list,
• icon_value,
• icon_list,
• swatch_grid.

Sort Order

Ordem das secções na página do produto. Um número mais baixo significa apresentação mais cedo.

Utilização: defina as secções mais importantes no início, por exemplo, 10 para características principais, 20 para aplicações, 30 para especificações.

Default State

Estado inicial da secção na página do produto.

Valores:

• Expanded - a secção está expandida por predefinição,
• Collapsed - a secção está recolhida por predefinição.

Utilização: os conteúdos mais importantes podem ser mostrados de imediato, e as informações auxiliares mais longas podem ficar recolhidas.

Hide Empty

Decide se a secção deve ser ocultada quando não há dados para mostrar.

Valores:

• Yes - a secção é ocultada se o produto não tiver valor de atributo ou se o renderer não devolver quaisquer elementos,
• No - a secção pode permanecer visível mesmo sem elementos.

Utilização: na maioria dos casos recomenda-se Yes, para não mostrar secções vazias ao cliente.

Appearance Profile

Seleção do perfil de aspeto definido no campo Appearance Profiles.

O campo tem a forma de dropdown. O administrador já não introduz manualmente o código, apenas escolhe um perfil pronto da lista, normalmente no formato code - label.

Utilização: permite dar a uma secção específica um aspeto diferente do global, por exemplo, perfil compact, highlight ou plain.

Se o campo estiver vazio e a opção Use global appearance estiver selecionada, a secção utiliza o aspeto global.

Ordem de trabalho recomendada:

1. defina o perfil em Appearance Profiles,
2. guarde a configuração,
3. volte a Feature Sections,
4. selecione o perfil na coluna Appearance Profile para a secção adequada.

CSS Class

Classe CSS adicional adicionada à secção.

Utilização: personalização individual do aspeto no tema frontend, por exemplo, product-features-section--technical.

Renderer Options JSON

Definições opcionais passadas ao renderer em formato JSON.

A utilização depende do tipo de apresentação. Exemplos:

{'unit':'cm','precision':1}

Para number_with_unit:

• unit - unidade, por exemplo, cm, %, g/m2,
• precision - número de casas decimais.

Para range_bar:

• min - valor mínimo do intervalo,
• max - valor máximo do intervalo,
• low_label - etiqueta do início do intervalo,
• high_label - etiqueta do fim do intervalo.

Para rating_dots:

• steps - número de pontos ou níveis.

O tipo radial_chart não exige opções adicionais. O renderer lê o valor do atributo ou a etiqueta da opção no formato x/y, por exemplo, 1/6, 4/6, 7/10.

Exemplo para a barra de intervalo:

{'min':0,'max':100,'low_label':'Baixa','high_label':'Alta'}

Exemplo para pontos:

{'steps':5}

Nota: o campo deve conter JSON válido. Um valor inválido é ignorado pelo renderer.

Appearance Profiles

Lista de perfis de aspeto opcionais que podem ser atribuídos às secções através do campo Appearance Profile.

Code

Código técnico do perfil.

Exemplos:

• compact,
• highlight,
• plain.

Utilização: o código identifica internamente o perfil e é utilizado como valor da opção no dropdown Appearance Profile na secção.

Label

Nome descritivo do perfil visível para o administrador.

Utilização: facilita o reconhecimento do perfil na configuração, por exemplo, Compacto, Destaque, Neutro. Em combinação com o código, cria uma etiqueta legível na lista de seleção de perfis em Feature Sections.

Background

Cor de fundo da secção para o perfil.

Utilização: destacar secções selecionadas ou adaptar ao tema.

Text

Cor do texto base na secção.

Heading

Cor do título da secção.

Accent

Cor do destaque, por exemplo, de elementos ativos, pontos de escala ou realces.

Accent Background

Cor de fundo dos elementos de destaque.

Border

Cor de linhas, separadores, eixos de escala e contornos.

Icon

Cor do ícone de expansão e recolha da secção.

Radius, e.g. 18px

Arredondamento dos cantos da secção.

Exemplos: 0, 8px, 18px.

Padding, e.g. 28px

Espaçamento interno da secção.

Exemplos: 16px, 24px, 28px.

Label Font Size, e.g. 21px

Tamanho do texto das etiquetas das características na secção.

Exemplos: 16px, 18px, 21px, 1.25rem.

Product Features Appearance

Este grupo contém o aspeto global das secções. As definições são convertidas em variáveis CSS e aplicadas ao wrapper do módulo.

Section Background Color

Cor de fundo da secção.

Por predefinição: #f4f4f4.

Section Text Color

Cor base do texto na secção.

Por predefinição: #000000.

Section Heading Color

Cor do cabeçalho da secção.

Por predefinição: #000000.

Muted Text Color

Cor de textos auxiliares e menos importantes.

Por predefinição: #555555.

Accent Color

Cor de elementos ativos e destaques.

Por predefinição: #000000.

Accent Background Color

Cor de fundo de elementos ativos, por exemplo, seleções.

Por predefinição: #ffffff.

Border Color

Cor de contornos, separadores e eixo da escala.

Por predefinição: #9b9b9b.

Icon Color

Cor do ícone + / - no cabeçalho da secção.

Por predefinição: #000000.

Selected Text Color

Cor do texto do valor selecionado.

Por predefinição: #000000.

Selected Font Weight

Espessura da letra do valor selecionado.

Por predefinição: 700.

Exemplos: 400, 500, 600, 700, bold.

Section Border Radius

Arredondamento do contentor da secção.

Por predefinição: 18px.

Section Padding

Espaçamento interno da secção.

Por predefinição: 28px.

Section Gap

Espaçamento entre secções.

Por predefinição: 16px.

Heading Font Size

Tamanho da letra do cabeçalho da secção.

Por predefinição: 20px.

Exemplos: 18px, 20px, 1.25rem, clamp(18px, 2vw, 22px).

Label Font Size

Tamanho da letra das etiquetas das características e das etiquetas dos valores.

Por predefinição: 21px.

Body Font Size

Tamanho da letra do conteúdo principal da secção.

Por predefinição: 16px.

Gestão de atributos do lado do produto

O módulo não cria um sistema separado de dados do produto. Utiliza atributos de produto do Magento, pelo que a gestão do conteúdo ocorre principalmente na edição do produto.

Edição de um único produto

1. Aceda a Catalog > Products.
2. Abra o produto para edição.
3. Preencha os atributos que são utilizados pelas secções do módulo.
4. Se o produto tiver de utilizar blocos CMS, vá ao grupo Product Features e defina o campo CMS Blocks.
5. Guarde o produto.
6. Limpe a cache, se o projeto o exigir.

A secção só aparecerá no frontend se:

• o módulo estiver ativado,
• a secção estiver ativada na configuração,
• o atributo existir,
• o produto tiver um valor de atributo,
• o renderer conseguir tratar o valor selecionado,
• a secção não tiver sido ocultada por Hide Empty.

Atributo blocks_id / CMS Blocks

Durante o setup:upgrade o módulo adiciona o atributo de produto:

• código: blocks_id,
• etiqueta: CMS Blocks,
• tipo: text,
• input: multiselect,
• source model: blocos CMS ativos,
• backend: backend padrão Magento para multiselect,
• scope: Store View,
• grupo: Product Features,
• visível na edição do produto,
• disponível na grelha de produtos e na filtragem da grelha.

O campo CMS Blocks permite atribuir blocos CMS ativos ao produto. Cada bloco selecionado será renderizado como uma secção separada, se na configuração do módulo existir uma secção com:

• Attribute Code: blocks_id,
• Display Type: cms_blocks.

O título da secção no frontend vem do título do bloco CMS, e o conteúdo do conteúdo do bloco. Blocos inativos ou indisponíveis para o Store View não são renderizados.

Gestão de blocos CMS

Os blocos utilizados por blocks_id são criados normalmente no Magento:

Content > Elements > Blocks

Recomendações:

• utilize títulos de bloco claros, porque podem ser visíveis como títulos de secção,
• atribua os blocos aos Store View corretos,
• defina o bloco como ativo,
• guarde nos blocos conteúdos descritivos que devem ser partilhados por vários produtos, por exemplo, entrega, devoluções, instruções, tecnologias.

Edição em massa de produtos

O atributo blocks_id está preparado para funcionar com edição em massa de produtos.

1. Aceda a Catalog > Products.
2. Selecione os produtos na grelha.
3. Escolha a ação Update Attributes.
4. Defina o valor do campo CMS Blocks.
5. Guarde as alterações.

Utilização: atribuição rápida da mesma secção CMS, por exemplo, Entrega, Devoluções ou Instruções de manutenção, a vários produtos ao mesmo tempo.

Atributos para escala

Para o tipo scale utilize atributos select com 2 ou 3 opções ativas.

Exemplo:

• atributo fit,
• opções: Largo, Regular, Ajustado.

O produto deve ter uma das opções selecionada. O módulo mostrará todas as opções da escala e destacará a atribuída ao produto.

Se o atributo tiver menos de 2 ou mais de 3 opções, o renderer scale ignorará esse atributo.

Atributos multiselect

Para listas de características, aplicações, tecnologias ou certificados, utilize atributos multiselect.

Tipos de apresentação possíveis:

• text_list,
• badge_list,
• swatch_list,
• swatch_grid,
• multiselect_icon,
• icon_list.

O produto pode ter vários valores selecionados. O módulo renderiza apenas os valores atribuídos ao produto.

Swatches Magento

Se o atributo multiselect utilizar swatches Magento, pode usar o tipo swatch_list ou swatch_grid.

Utilização:

• ícones de tecnologias,
• cores,
• pictogramas de aplicações,
• marcações de materiais.

Se a opção tiver swatch de imagem, o módulo mostrará a imagem. Se tiver swatch de cor ou de texto, o módulo utilizará a variante adequada.

Ícones Amasty

Para o tipo multiselect_icon o módulo tenta obter o ícone da opção a partir de Amasty ShopbyBrand / ShopbyBase.

Origem do ícone:

Shop by Brand > Option Edit > Other > Small Image

O texto alternativo vem de Small Image Alt, e se este faltar, da etiqueta da opção.

Se o Amasty não estiver instalado ou se a opção não tiver ícone, o módulo mostrará apenas a etiqueta.

Atributos de texto e HTML

Para informações curtas, utilize text_inline, key_value ou badge.

Para descrições mais longas, utilize text_block, accordion_text ou html_block.

Nota: html_block e accordion_text renderizam HTML, pelo que devem ser usados exclusivamente para conteúdos administrativos fiáveis.

Atributos numéricos

Para valores numéricos, pode utilizar:

• number_with_unit - quando o número exige uma unidade,
• range_bar - quando o valor deve ser mostrado como progresso num intervalo,
• rating_dots - quando o valor descreve um nível ou avaliação.

Exemplo de Renderer Options JSON para número com unidade:

{'unit':'%','precision':0}

Atributos boolean

Para atributos sim/não, utilize:

• yes_no, quando o cliente deve ver tanto Yes como No,
• checkmark, quando a característica só deve ser visível quando o produto a possui.

Atributos de imagem

Para atributos do tipo imagem, pode utilizar:

• image,
• image_with_label,
• image_grid.

O módulo constrói o endereço da imagem com base no diretório de media de produto do Magento e utiliza a etiqueta do atributo como texto alternativo.

Configuração de exemplo

Secção com várias escalas:

Secção de aplicações com ícones:

Secções CMS:

Diagnóstico

Se a secção não aparecer no frontend, verifique:

• se o Enabled do módulo tem o valor Yes,
• se a secção em causa tem Enabled = Yes,
• se o produto tem o atributo preenchido,
• se foi selecionado o Attribute Code ou Attribute Codes correto,
• se o Display Type corresponde ao tipo de atributo,
• se Hide Empty não está a ocultar uma secção vazia,
• se o atributo está disponível para o Store View em questão,
• se o bloco CMS está ativo e atribuído ao Store View correto,
• se a cache do Magento foi atualizada.