Product Sets feature integration

This document describes how to install the Product Sets feature.

Prerequisites

To prepare your project to work with Product Sets:

1. Require the Product Set modules in your composer.json:

composer require spryker/product-set spryker/product-set-collector spryker/product-set-gui

2. If you want to enable the Product Sets search powered by Elasticsearch, install the spryker/search-elasticsearch module:

composer require spryker/search-elasticsearch

3. Install the new database tables:

vendor/bin/console propel:diff

Propel should generate a migration file with the changes.

4. Apply the database changes:

vendor/bin/console propel:migrate

5. Generate ORM models:

vendor/bin/console propel:model:build

6. Get the new transfer objects:

vendor/bin/console transfer:generate

7. Rebuild Zed navigation:

vendor/bin/console navigation:build-cache

8. To activate the Product Set collectors, add ProductSetCollectorStoragePlugin to the storage collector plugin stack and ProductSetCollectorSearchPlugin to the search collector plugin stack:

<?php

namespace Pyz\Zed\Collector;

use Spryker\Shared\ProductSet\ProductSetConfig;
use Spryker\Zed\Kernel\Container;
use Spryker\Zed\ProductSetCollector\Communication\Plugin\ProductSetCollectorSearchPlugin;
use Spryker\Zed\ProductSetCollector\Communication\Plugin\ProductSetCollectorStoragePlugin;
// ...

class CollectorDependencyProvider extends SprykerCollectorDependencyProvider
{
	/**
	 * @param \Spryker\Zed\Kernel\Container $container
	 *
	 * @return \Spryker\Zed\Kernel\Container
	 */
	public function provideBusinessLayerDependencies(Container $container)
	{
		// ...

		$container->set(static::SEARCH_PLUGINS, function (Container $container) {
			return [
				// ...
				ProductSetConfig::RESOURCE_TYPE_PRODUCT_SET => new ProductSetCollectorSearchPlugin(),
			];
		});

		$container->set(static::STORAGE_PLUGINS, function (Container $container) {
			return [
				// ...
				ProductSetConfig::RESOURCE_TYPE_PRODUCT_SET => new ProductSetCollectorStoragePlugin(),
			];
		});

		// ...
	}
}

Data setup

Implement an installer in your project to put products together in sets representing how you want them to be displayed in your shop frontend. Find implementation examples in the Demoshop.

Listing products sets on the Storefront

The KV storage and Elasticsearch should by now contain some product sets you can display on the Storefront. By default, the exported documents in Search do not support the configurable search features as products: full-text search, faceted navigation, sorting, and pagination. However, since their data structure is the same, it’s possible to implement the same features with a custom implementation.

For a simple listing, the ProductSet module provides a Client API to list product sets from Elasticsearch. By calling the ProductSetClient::getProductSetList() method, a limited set of documents can be listed on the Storefront. The results are sorted in descending order based on the product sets’ weight attributes.

The executed search query works the same way as described in Search Query. If you need to extend the query, for example, by filtering current store and locale, add the desired query expander plugins, like in the example below. To format a raw response from Elasticsearch, provide a result formatter plugin that is also provided by the ProductSet module.

<?php

namespace Pyz\Client\ProductSet;

use Spryker\Client\ProductSet\Plugin\Elasticsearch\ResultFormatter\ProductSetListResultFormatterPlugin;
use Spryker\Client\ProductSet\ProductSetDependencyProvider as SprykerProductSetDependencyProvider;
use Spryker\Client\SearchElasticsearch\Plugin\QueryExpander\LocalizedQueryExpanderPlugin;

class ProductSetDependencyProvider extends SprykerProductSetDependencyProvider
{

	/**
	 * @return array
	 */
	protected function getProductSetListResultFormatterPlugins()
	{
		return [
			new ProductSetListResultFormatterPlugin(),
		];
	}

	/**
	 * @return array
	 */
	protected function getProductSetListQueryExpanderPlugins()
	{
		return [
			new LocalizedQueryExpanderPlugin(),
		];
	}

}

Enable the text alternatives functionality

The Text Alternatives functionality lets you add alternative text to product images for better accessibility and SEO.

1) Upgrade modules

Upgrade the following modules to the specified versions or higher

composer require spryker/glossary:^3.16.0 spryker/glossary-storage:^1.5.0 spryker/product-image:^3.20.0 spryker/product-set-gui:^2.13.0 spryker/product-set-page-search:^1.13.0 spryker/product-set-storage:^1.13.0 spryker-shop/product-set-list-page:^1.2.0 spryker-shop/product-set-widget:^1.10.0 spryker-shop/shop-ui:^1.96.0 --update-with-dependencies

2) Enable the feature in the ProductImage module configuration

src/Pyz/Shared/ProductImage/ProductImageConfig.php

<?php
declare(strict_types = 1);

namespace Pyz\Shared\ProductImage;

use Spryker\Shared\ProductImage\ProductImageConfig as SprykerProductImageConfig;

class ProductImageConfig extends SprykerProductImageConfig
{
    /**
     * @return bool
     */
    public function isProductImageAlternativeTextEnabled(): bool
    {
        return true;
    }
}

3) Set up database schema and transfer objects

1. Apply database changes and generate entity and transfer changes:

console propel:install
console transfer:generate

4) Import text alternatives data

1. Add text alternatives data for product set images by adding new fields to the data import file, using the following example:

data/import/common/AT/combined_product.csv

>alt_text.image_small.1.1.de_DE,alt_text.image_small.1.1.en_US,alt_text.image_large.1.1.de_DE,alt_text.image_large.1.1.en_US
"Details ansehen: Samsung Gear S2","View details of Samsung Gear S2","Back view of Samsung Gear S2 Black","Rückansicht von Samsung Gear S2 Black"

New fields are alt_text_small and alt_text_large with the image number and the locale name as a suffix.

2. Apply the changes to the data import business logic:

Here is an example of how to extend the data import business logic for product images to handle the new fields: https://github.com/spryker-shop/b2c-demo-shop/pull/781/files

3. Import data:

console data:import --config=data/import/local/full_EU.yml product-set