Product Features - instalación, configuración y gestión de atributos

Este documento describe la configuración del módulo kowal/module-product-features, el significado de todos los campos administrativos y el trabajo con atributos en el lado del producto.

Instalación

El módulo está destinado a instalarse mediante 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

Tras el despliegue en producción, deben ejecutarse los comandos estándar correspondientes al proyecto, por ejemplo la compilación DI y el deploy de assets estáticos, de acuerdo con el modo de funcionamiento de Magento.

Ubicación de la configuración

La configuración del módulo se encuentra en el panel de administración de Magento:

Stores > Configuration > Catalog > Product Features

Los ajustes de apariencia se encuentran en un grupo independiente:

Stores > Configuration > Catalog > Product Features Appearance

Los campos de configuración están disponibles en los niveles Default, Website y Store View. Gracias a ello, distintas vistas de tienda pueden tener secciones de características diferentes o una apariencia distinta.

Product Features

Enabled

Activa o desactiva el módulo para el ámbito de configuración correspondiente.

Valores:

• Yes - las secciones de características del producto se renderizan en la ficha de producto,
• No - el módulo no devuelve secciones y el bloque no aparece en el frontend.

Uso: desactivación rápida del módulo para toda la tienda, un Website seleccionado o un Store View sin eliminar la configuración de las secciones.

Feature Sections

Lista de secciones renderizadas en la ficha de producto. Cada fila define una sección frontend o un grupo de secciones si se utiliza el tipo cms_blocks.

Enabled

Activa o desactiva una sección individual.

Valores:

• Yes - la sección participa en el renderizado,
• No - la sección se omite.

Uso: ocultar temporalmente una sección sin borrar su configuración.

Section Title

Título de la sección visible en la ficha de producto.

Ejemplos:

• Características del producto,
• Uso deportivo,
• Especificación,
• Tecnologías,
• Entrega.

Uso: el nombre debe ser comprensible para el cliente; no tiene que corresponder al nombre técnico del atributo.

Nota: para el tipo cms_blocks, el título de la sección hija se obtiene del título del bloque CMS.

Attribute Code

Atributo individual del producto utilizado por la sección. El campo tiene forma de dropdown con una lista de atributos de producto.

Uso: utilice este campo cuando la sección se base en un único atributo, por ejemplo sport_usage, blocks_id, material, technology_icon.

Attribute Codes

Lista de varios atributos de producto utilizados por una sola sección. El campo tiene forma de multiselect.

Uso: utilice este campo cuando una sección deba agrupar varias características, por ejemplo varias escalas en la sección Características del producto o varios parámetros en la sección Especificación.

Ejemplo: la sección Características del producto puede contener los atributos fit, resistance, stretch y breathability, todos renderizados como escalas.

Display Type

Define la forma de presentación del valor del atributo.

El valor vacío Auto significa selección automática del renderer:

• blocks_id se renderiza como cms_blocks,
• swatch multiselect como swatch_list,
• select con 2 o 3 opciones como scale,
• select con un mayor número de opciones 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,
• los demás tipos como text_inline.

Tipos disponibles:

En el panel de administración, parte de las opciones está marcada como available in future release. Esto se refiere a tipos que ya son visibles en la lista de configuración, pero que todavía no tienen su presentación frontend final propia:

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

Sort Order

Orden de las secciones en la ficha de producto. Un número menor significa una visualización más temprana.

Uso: coloque las secciones más importantes al principio, por ejemplo 10 para características principales, 20 para usos, 30 para especificación.

Default State

Estado inicial de la sección en la ficha de producto.

Valores:

• Expanded - la sección está desplegada por defecto,
• Collapsed - la sección está plegada por defecto.

Uso: el contenido más importante puede mostrarse de inmediato y la información auxiliar más extensa puede dejarse plegada.

Hide Empty

Decide si la sección debe ocultarse cuando no hay datos para mostrar.

Valores:

• Yes - la sección se oculta si el producto no tiene valor de atributo o el renderer no devuelve ningún elemento,
• No - la sección puede permanecer visible incluso sin elementos.

Uso: normalmente se recomienda Yes para no mostrar secciones vacías al cliente.

Appearance Profile

Selección del perfil de apariencia definido en el campo Appearance Profiles.

El campo tiene forma de dropdown. El administrador ya no introduce el código manualmente, sino que selecciona un perfil listo de la lista, normalmente en formato code - label.

Uso: permite dar a una sección concreta una apariencia distinta de la global, por ejemplo el perfil compact, highlight o plain.

Si el campo está vacío y se selecciona la opción Use global appearance, la sección utiliza la apariencia global.

Orden de trabajo recomendado:

1. defina el perfil en Appearance Profiles,
2. guarde la configuración,
3. vuelva a Feature Sections,
4. seleccione el perfil en la columna Appearance Profile para la sección correspondiente.

CSS Class

Clase CSS adicional añadida a la sección.

Uso: ajuste individual de la apariencia en el tema frontend, por ejemplo product-features-section--technical.

Renderer Options JSON

Ajustes opcionales pasados al renderer en formato JSON.

El uso depende del tipo de presentación. Ejemplos:

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

Para number_with_unit:

• unit - unidad, por ejemplo cm, %, g/m2,
• precision - número de decimales.

Para range_bar:

• min - valor mínimo del rango,
• max - valor máximo del rango,
• low_label - etiqueta del inicio del rango,
• high_label - etiqueta del final del rango.

Para rating_dots:

• steps - número de puntos o niveles.

El tipo radial_chart no requiere opciones adicionales. El renderer lee el valor del atributo o la etiqueta de la opción en formato x/y, por ejemplo 1/6, 4/6, 7/10.

Ejemplo para la barra de rango:

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

Ejemplo para los puntos:

{'steps':5}

Nota: el campo debe contener un JSON válido. El renderer ignora los valores incorrectos.

Appearance Profiles

Lista de perfiles de apariencia opcionales que pueden asignarse a las secciones mediante el campo Appearance Profile.

Code

Código técnico del perfil.

Ejemplos:

• compact,
• highlight,
• plain.

Uso: el código identifica internamente el perfil y se utiliza como valor de opción en el dropdown Appearance Profile de la sección.

Label

Nombre descriptivo del perfil visible para el administrador.

Uso: facilita reconocer el perfil en la configuración, por ejemplo Compacto, Destacado, Neutro. En combinación con el código crea una etiqueta clara en la lista de selección de perfiles de Feature Sections.

Background

Color de fondo de la sección para el perfil.

Uso: destacar secciones seleccionadas o adaptar la apariencia al tema.

Text

Color del texto principal en la sección.

Heading

Color del título de la sección.

Accent

Color de acento, por ejemplo para elementos activos, puntos de escala o destacados.

Accent Background

Color de fondo de los elementos de acento.

Border

Color de líneas, separadores, eje de escala y bordes.

Icon

Color del icono de desplegar y plegar la sección.

Radius, e.g. 18px

Redondeo de las esquinas de la sección.

Ejemplos: 0, 8px, 18px.

Padding, e.g. 28px

Espaciado interior de la sección.

Ejemplos: 16px, 24px, 28px.

Label Font Size, e.g. 21px

Tamaño del texto de las etiquetas de características en la sección.

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

Product Features Appearance

Este grupo contiene la apariencia global de las secciones. Los ajustes se transforman en variables CSS y se aplican al wrapper del módulo.

Section Background Color

Color de fondo de la sección.

Por defecto: #f4f4f4.

Section Text Color

Color principal del texto en la sección.

Por defecto: #000000.

Section Heading Color

Color del encabezado de la sección.

Por defecto: #000000.

Muted Text Color

Color de los textos auxiliares y menos importantes.

Por defecto: #555555.

Accent Color

Color de los elementos activos y destacados.

Por defecto: #000000.

Accent Background Color

Color de fondo de los elementos activos, por ejemplo las selecciones.

Por defecto: #ffffff.

Border Color

Color de bordes, separadores y eje de escala.

Por defecto: #9b9b9b.

Icon Color

Color del icono + / - en el encabezado de la sección.

Por defecto: #000000.

Selected Text Color

Color del texto del valor seleccionado.

Por defecto: #000000.

Selected Font Weight

Grosor de la fuente del valor seleccionado.

Por defecto: 700.

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

Section Border Radius

Redondeo del contenedor de la sección.

Por defecto: 18px.

Section Padding

Espaciado interior de la sección.

Por defecto: 28px.

Section Gap

Espacio entre secciones.

Por defecto: 16px.

Heading Font Size

Tamaño de fuente del encabezado de la sección.

Por defecto: 20px.

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

Label Font Size

Tamaño de fuente de las etiquetas de características y de valores.

Por defecto: 21px.

Body Font Size

Tamaño de fuente del contenido principal de la sección.

Por defecto: 16px.

Gestión de atributos en el lado del producto

El módulo no crea un sistema independiente de datos de producto. Utiliza los atributos de producto de Magento, por lo que la gestión del contenido se realiza principalmente en la edición del producto.

Edición de un solo producto

1. Vaya a Catalog > Products.
2. Abra el producto para editarlo.
3. Complete los atributos que utilizan las secciones del módulo.
4. Si el producto debe utilizar bloques CMS, vaya al grupo Product Features y configure el campo CMS Blocks.
5. Guarde el producto.
6. Limpie la caché si el proyecto lo requiere.

La sección aparecerá en el frontend solo si:

• el módulo está habilitado,
• la sección está habilitada en la configuración,
• el atributo existe,
• el producto tiene valor en el atributo,
• el renderer puede manejar el valor seleccionado,
• la sección no ha sido ocultada por Hide Empty.

Atributo blocks_id / CMS Blocks

Durante setup:upgrade, el módulo añade el atributo de producto:

• código: blocks_id,
• etiqueta: CMS Blocks,
• tipo: text,
• input: multiselect,
• source model: bloques CMS activos,
• backend: backend estándar de Magento para multiselect,
• scope: Store View,
• grupo: Product Features,
• visible en la edición del producto,
• disponible en la grid de productos y en el filtrado de la grid.

El campo CMS Blocks permite asignar bloques CMS activos al producto. Cada bloque seleccionado se renderizará como una sección independiente si en la configuración del módulo existe una sección con:

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

El título de la sección en el frontend proviene del título del bloque CMS y el contenido del contenido del bloque. Los bloques inactivos o no disponibles para el Store View no se renderizan.

Gestión de bloques CMS

Los bloques utilizados por blocks_id se crean de forma estándar en Magento:

Content > Elements > Blocks

Recomendaciones:

• utilice títulos de bloque claros, ya que pueden ser visibles como títulos de sección,
• asigne los bloques a los Store View correctos,
• establezca el bloque como activo,
• almacene en los bloques contenido descriptivo que deba compartirse entre muchos productos, por ejemplo entrega, devoluciones, instrucciones, tecnologías.

Edición masiva de productos

El atributo blocks_id está preparado para trabajar con la edición masiva de productos.

1. Vaya a Catalog > Products.
2. Seleccione productos en la grid.
3. Elija la acción Update Attributes.
4. Establezca el valor del campo CMS Blocks.
5. Guarde los cambios.

Uso: asignación rápida de una misma sección CMS, por ejemplo Entrega, Devoluciones o Instrucciones de cuidado, a varios productos al mismo tiempo.

Atributos para la escala

Para el tipo scale, utilice atributos select con 2 o 3 opciones activas.

Ejemplo:

• atributo fit,
• opciones: Holgado, Regular, Ajustado.

El producto debe tener una de las opciones seleccionada. El módulo mostrará todas las opciones de la escala y destacará la asignada al producto.

Si el atributo tiene menos de 2 o más de 3 opciones, el renderer scale omitirá este atributo.

Atributos multiselect

Para listas de características, usos, tecnologías o certificados, utilice atributos multiselect.

Tipos de presentación posibles:

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

El producto puede tener varios valores seleccionados. El módulo renderiza solo los valores asignados al producto.

Swatches de Magento

Si el atributo multiselect utiliza swatches de Magento, puede emplearse el tipo swatch_list o swatch_grid.

Uso:

• iconos de tecnologías,
• colores,
• pictogramas de uso,
• marcados de materiales.

Si la opción tiene un swatch de imagen, el módulo mostrará la imagen. Si tiene un swatch de color o de texto, el módulo utilizará la variante correspondiente.

Iconos de Amasty

Para el tipo multiselect_icon, el módulo intenta obtener el icono de la opción desde Amasty ShopbyBrand / ShopbyBase.

Fuente del icono:

Shop by Brand > Option Edit > Other > Small Image

El texto alternativo proviene de Small Image Alt y, si no existe, de la etiqueta de la opción.

Si Amasty no está instalado o la opción no tiene icono, el módulo mostrará solo la etiqueta.

Atributos de texto y HTML

Para información breve utilice text_inline, key_value o badge.

Para descripciones más largas utilice text_block, accordion_text o html_block.

Nota: html_block y accordion_text renderizan HTML, por lo que deben utilizarse únicamente para contenido administrativo de confianza.

Atributos numéricos

Para valores numéricos pueden utilizarse:

• number_with_unit - cuando el número requiere una unidad,
• range_bar - cuando el valor debe mostrarse como progreso dentro de un rango,
• rating_dots - cuando el valor describe un nivel o una valoración.

Ejemplo de Renderer Options JSON para número con unidad:

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

Atributos boolean

Para atributos sí/no utilice:

• yes_no, cuando el cliente deba ver tanto Yes como No,
• checkmark, cuando la característica deba ser visible solo cuando el producto la tenga.

Atributos de imagen

Para atributos de tipo imagen pueden utilizarse:

• image,
• image_with_label,
• image_grid.

El módulo construye la dirección de la imagen a partir del catálogo de medios del producto de Magento y utiliza la etiqueta del atributo como texto alternativo.

Configuración de ejemplo

Sección de varias escalas:

Sección de usos con iconos:

Secciones CMS:

Diagnóstico

Si una sección no aparece en el frontend, compruebe:

• si Enabled del módulo tiene el valor Yes,
• si la sección correspondiente tiene Enabled = Yes,
• si el producto tiene el atributo completado,
• si se ha seleccionado el Attribute Code o Attribute Codes correctos,
• si Display Type se ajusta al tipo de atributo,
• si Hide Empty no está ocultando una sección vacía,
• si el atributo está disponible para el Store View correspondiente,
• si el bloque CMS está activo y asignado al Store View correcto,
• si la caché de Magento se ha actualizado.