Product Sets feature integration
Edit on GitHubThis document describes how to install the Product Sets feature.
Prerequisites
To prepare your project to work with Product Sets:
- Require the Product Set modules in your
composer.json
:
composer require spryker/product-set spryker/product-set-collector spryker/product-set-gui
- If you want to enable the Product Sets search powered by Elasticsearch, install the
spryker/search-elasticsearch
module:
composer require spryker/search-elasticsearch
- Install the new database tables:
vendor/bin/console propel:diff
Propel should generate a migration file with the changes.
- Apply the database changes:
vendor/bin/console propel:migrate
- Generate ORM models:
vendor/bin/console propel:model:build
Make sure that:
-
New classes have been added to
\Orm\Zed\ProductSet\Persistence
. -
They extend the base classes from the Spryker core. For example:
-
\Orm\Zed\ProductSet\Persistence\SpyProductSet
extends\Spryker\Zed\ProductSet\Persistence\Propel\AbstractSpyProductSet
-
\Orm\Zed\ProductSet\Persistence\SpyProductSetData
extends\Spryker\Zed\ProductSet\Persistence\Propel\AbstractSpyProductSetData
-
\Orm\Zed\ProductSet\Persistence\SpyProductAbstractSet
extends\Spryker\Zed\ProductSet\Persistence\Propel\AbstractSpyProductAbstractSet
-
\Orm\Zed\ProductSet\Persistence\SpyProductSetQuery
extends\Spryker\Zed\ProductSet\Persistence\Propel\AbstractSpyProductSetQuery
-
\Orm\Zed\ProductSet\Persistence\SpyProductSetDataQuery
extends\Spryker\Zed\ProductSet\Persistence\Propel\AbstractSpyProductSetDataQuery
-
\Orm\Zed\ProductSet\Persistence\SpyProductAbstractSetQuery
extends\Spryker\Zed\ProductSet\Persistence\Propel\AbstractSpyProductAbstractSetQuery
-
- Get the new transfer objects:
vendor/bin/console transfer:generate
- Rebuild Zed navigation:
vendor/bin/console navigation:build-cache
- To activate the Product Set collectors, add
ProductSetCollectorStoragePlugin
to the storage collector plugin stack andProductSetCollectorSearchPlugin
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(),
];
}
}
You can reorder product sets in the Back Office. See Reorder product sets for more details.
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
NAME | VERSION |
---|---|
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/glossary | 3.16.0 |
spryker/glossary-storage | 1.5.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 |
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
Make sure that the following modules have been installed:
MODULE | EXPECTED DIRECTORY |
---|---|
ProductImage | vendor/spryker/spryker/product-image |
ProductSetGui | vendor/spryker/product-set-gui |
ProductSetPageSearch | vendor/spryker/product-set-page-search |
ProductSetStorage | vendor/spryker/product-set-storage |
Glossary | vendor/spryker/glossary |
GlossaryStorage | vendor/spryker/glossary-storage |
ProductSetListPage | vendor/spryker-shop/product-set-list-page |
ProductSetWidget | vendor/spryker-shop/product-set-widget |
ShopUi | vendor/spryker-shop/shop-ui |
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
- Apply database changes and generate entity and transfer changes:
console propel:install
console transfer:generate
Make sure that the following changes have been applied by checking your database:
DATABASE ENTITY | TYPE | EVENT |
---|---|---|
spy_product_image.alt_text_small | field | created |
spy_product_image.alt_text_large | field | created |
Make sure the following changes have been applied in transfer objects:
TRANSFER | TYPE | EVENT | PATH |
---|---|---|---|
ProductImage.altTextSmall | property | created | src/Generated/Shared/Transfer/ProductImageTransfer |
ProductImage.altTextLarge | property | created | src/Generated/Shared/Transfer/ProductImageTransfer |
ProductImage.translations | property | created | src/Generated/Shared/Transfer/ProductImageTransfer |
ProductImageTranslation | class | created | src/Generated/Shared/Transfer/ProductImageTranslationTransfer |
StorageProductImage.altTextSmall | property | created | src/Generated/Shared/Transfer/StorageProductImageTransfer |
StorageProductImage.altTextLarge | property | created | src/Generated/Shared/Transfer/StorageProductImageTransfer |
4) Import text alternatives data
- 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.
- 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
- Import data:
console data:import --config=data/import/local/full_EU.yml product-set
Thank you!
For submitting the form