search

FACT-Finder-Web-Components / shopware6-plugin

FACT-Finder® Web Components for Shopware 6
Other
3 stars 5 forks source link
fact-finder shopware-platform-plugin web-components

readme

FACT-Finder® Web Components for Shopware 6

Build status

This document helps you to integrate the FACT-Finder® Web Components SDK into your Shopware Shop. In addition, it gives a concise overview of its primary functions. The first chapter Installation walks you through the suggested installation process. The second chapter Settings explains the customisation options in the Shopware backend. The final chapter Exporting Feed describes how to use provided console command to export the feed.

Our Shopware plugin offers a basic working integration for default Shopware Storefront theme. Most projects may require modifications in order to fit their needs. For more advanced features please check our official WebComponnents documentation.

System Requirements

Note: If you use Shopware 6.5 please use SDK version 5.x: https://github.com/FACT-Finder-Web-Components/shopware6-plugin/tree/release/5.x

Note: For Shopware 6.6 please use Shopware marketplace version: https://store.shopware.com/en/factf26713613196f/factfinder-ai-powered-search-product-discovery.html

FACT-Finder® Supported Sections

Version Compatibility
NG ✔️
7.x ❌️

Installation

To install the plugin, open your terminal and run the command:

composer require omikron/shopware6-factfinder

After successfully installation, it will be visible in the extensions list. Depending on the Shopware 6 versions the view could be different.

Module Enabled

Note: Plugin can only be installed only via composer, unpacking plugin source code directly into Shopware 6 project directory will not work as the plugin contains external dependencies which also needs to be installed.

Activating the Module

To activate the module, please use the switcher located on the left side of the row with extension info. Module Enabled After it is installed, its configuration is available under the three dots icon. Module Enabled All sections will be covered in the following paragraphs.

Main Settings

Main Settings

This section contains a plugin configuration, which is required in order for the module to work. All fields are self-explained. Configuration set here is used by both Web Components and during the server side communication with FACT-Finder® instance. Credentials you will be given should be placed here. Please remember that you have to clear the store cache in order the new applied configuration to start working.

You can check if the above data is correctly set by clicking on the Test Connection button. Please save your settings before clicking on button.

Update Field Roles

This functionality offers a way to download field roles configured in FACT-Finder®. Please use this if you don't use feed offered by the plugin or for some reason you have changed the column names. You can find more information about what Field Roles are in (Web Components documentation)[https://web-components.fact-finder.de/documentation/4.x/field-roles] Note: Updating process is ran for all sales channels, no need to run it separately for each of them

Server Side Rendering

That option enables Server Side Rendering (SSR) for ff-record-list element on category and search result pages. That means when user navigate to a page of mentioned type, the HTML output will contain the pre-rendered custom elements. This is useful especially in terms of SEO because ff-record-list renders product data which could have much impact on page rating in browser. Without SSR enabled, web crawlers could not have a chance to scan the element rendered content because it will not yet be rendered on the time of scanning.

Note: More information about SSR concept you can find in the article Server Side Rendering from Web Components documentation.

Advanced Settings

Advanced Settings

This section contains a plugin configuration, which is optional and provides additional features.

Export Settings

Export Settings

Note: When the Export cache is enabled:

Price Columns Format

If Export prices in all currencies setting is set to true, price columns will be exported in followed pattern Price_[currency ISO code] i.e. Price_De

Upload Settings

Upload Setting Following settings are used for uploading already exported feed to a given FTP/SFTP server.

Note: The default port setting is 21. If your server is listening on different port, please change it accordingly.

You can check if the above data is correctly set by clicking on the Test FTP/SFTP Connection button. Please save your settings before clicking on button.

*Note** Fields "Private Key Content" and "Passphrase" are optional. Use them only if your SFTP server require this method of authentication.

Import Settings

Upload Setting

Category Pages

Note: This feature is experimental, and it is highly possible that it will be significantly modified in a near future.

Plugin offers a way to use FACT-Finder® Web Components on category pages using page builder Shopping Experiences. There is two CMS blocks offered:

Page Builder CMS Blocks Page Builder CMS Preview

Offered Cms Blocks and Elements are designed to work on pages of type LandingPage. There is a type CategoryPage but the builtin validation will not allow saving that prepared page, unless it contains at least one default Product Listing Block. The block FACTFinder Web Components Listing is unfortunately not taken into account.

All elements are available under the category Commerce

Element Settings

Each of the element of given block contains dedicated configuration which allows to configure them without necessity of adding hardcoded values in the templates. Page Builder CMS Element Configuration

If you do not want to render a specific element, just change the subscribe option to false. This will make element will not subscribe to the FACT-Finder® response, hence they will not render any HTML.

ASN Element

Page Builder CMS Element ASN

Record List Element

Page Builder CMS Element Record List

Campaigns Element

Page Builder CMS Element Campaigns

Note: You can find more information about campaigns related elements and their configuration in Web Components documentation

Blocks and Elements Templates

Each of the block and element has it own templates which could be found, according to the Shopware 6 convention:

Assigning Layout to Category

Once the page layout is done, you need to assign layout to selected categories. Page Builder Page Assigning

We strongly recommend not creating many layouts as currently there's still only few possibilities offered anyway. Future development will bring more blocks and elements will be provided here.

Exporting Feeds

FACT-Finder allows to export different types of feeds, like a products, cms and brands (or manufacturers)

Also you can define your own data types to export in services.xml file in factfinder.data_export.entity_type_map parameter

Feed can be exported in two ways: using admin panel (www.yourhost.com/admin#/ui/feed/export/index) or using CLI

CLI

Feed export is available in the Shopware CLI application. You can run it by executing:

php [SHOPWARE_ROOT]/bin/console factfinder:data:export

and follow the instructions in console.

If You want to run command whitout interaction mode, type command with -n option:

php [SHOPWARE_ROOT]/bin/console factfinder:data:export -n

The command can be run with an optional argument indicating the sales channel ID that you are targeting. The ID is an string value.

php [SHOPWARE_ROOT]/bin/console factfinder:data:export -n SALES_CHANNEL_ID

If a specific language needs to be specified, theres is a second argument which allows that.

php [SHOPWARE_ROOT]/bin/console factfinder:data:export -n SALES_CHANNEL_ID LANGUGAGE_ID

There are two additional options (except -n):

by default export outputs data in the STDOUT. It could be easily redirected using Linux way of redirecting output.

php [SHOPWARE_ROOT]/bin/console factfinder:data:export -n > export.csv

Selecting Categories for CMS Export

With CMS Export we introduced custom field for CategoryEntity by which we filter the Categories going to be exported. You can find it on Category edit page. Include in CMS Export Custom Field

Exporting from Admin Panel

There is a possibility to run whole integration: generating feed, uploading it to FTP server and trigger FACT-Finder® import. A dedicated form can be found under Extensions section Admin Panel Export

Admin Panel Export Form Select fields allows you to select sales channel and languague parameter for which an integration shall be run. Select export type gives you possibility to create different content of data available in your Shopware instance. Export can be done for:

Create Export Send a message to a bus which then might be consumed automatically by an admin worker (if enabled) or by CLI worker. More information about messaging you can find in official Shopware documentation

Admin Panel Refresh export cache If you use the export cache feature (read more) you could also refresh your export cache by clicking on Refresh cache Export button. This feature will be useful if:

Web Components Integration

Note: Please note that plugin right now is supporting only classic storefronts, rendered using Twig templating system.

Web Components Documentation

Full FACT-Finder® Web Components documentation you can find here

Including Scripts

The module is shipped with script including FACT-Finder® Web Components. Including Scripts step is implemented in the module. No additional action is required.

All these files are included in Resources/views/storefront/layout/meta.html.twig. That file extends the default theme meta.html.twig . Note: Including these scripts is obligatory for Web Components to work. Make sure you include it or if your storefront does not use that file, include all scripts in mentioned order on your own.

Communication

Main configuration element ff-communication is added in file src/Resources/views/storefront/base.html.twig . Same as with meta.twig.html, it extends the base.html.twig file defined in default Storefront. This element is populated automatically with the data, configured in module configuration.

Note: If your theme doesn't extend the default Storefront, make sure you implement ff-communication element as it is mandatory and FACT-Finder® Web Components will not work without it.

Templates

Plugin templates could be found in Resources/views/storefront/. Just as with the previous sections, all templates are extending default Storefront wherever it is possible. You can use these templates if you are extending it using sw_extends which offers a support for a multi inheritance.

Tracking

Plugin offers a following way of tracking customer actions

Full List of Implemented Web Components

Plugin implements a list of given Web Components:

Modifications Examples

Adding New Column to Feed

The standard feed contains all data FACT-Finder® requires to work. However, you may want to export additional information which is relevant for your project and not part of a default Shopware installation. This section shows you how to extend the feed with additional column.

Start with creating field provider - a class implementing Omikron\FactFinder\Shopware6\Export\FieldInterface which will be used to export your data.


use Shopware\Core\Framework\DataAbstractionLayer\Entity;

interface FieldInterface
{
    public function getName(): string;

    public function getValue(Entity $entity): string;

    public function getCompatibleEntityTypes(): array;
}

The method getName contains name of Column under which field should be exported The method getValue contains your field logic and receives the article detail currently being exported. The method getCompatibleEntityTypes contains an array of Shopware Entity classes of which the given field can be applied to


use Omikron\FactFinder\Shopware6\Export\Data\Entity\ProductEntity;
use Shopware\Core\Framework\DataAbstractionLayer\Entity;

class CustomColumn implements FieldInterface
{
     public function getName(): string
     {
        return 'MyColumnName'; // Will be used as column header in the CSV feed
     }

    public function getValue(Entity $entity): string
    {
        // Implement logic to fetch and transform data for a given article detail  
    }

    public function getCompatibleEntityTypes(): array
    {
        return [ProductEntity::class];
    }
}

Once your additional column is defined, register it as a service using Symfony DI (you can find more information here) and set them to be auto-configured. By doing this, your fields will be tagged as factfinder.export.field and can be picked up automatically. Of course, autoconfiguration is just a convenience we offer, you can still assign the tag to your service manually.

Export Fields Stored in Variants

By default, only these fields are exported from variants:

However, exporting data from variants may require additional joins during the data fetch. To define custom association (join) set them in under a parameter of that name

//src/Resources/config/services.xml:39
<parameter key="factfinder.export.associations" type="collection">
    <parameter key="variant_cover">children.cover</parameter>
</parameter>

All parameters in that collection will be used in a following expression

$criteria->addAssociation($association);

where $association would be a children.cover in that example.

Note: Please note that adding more and more associations will have an impact on overall export performance.

Creating Custom Entity Export

Plugin offers a flexible export mechanism which could be specified to work with different types of entities. In current state of plugin it allows to export three types of entities:

You can extend base with new kinds of entities. In order to do so you need to provide at least three classes

Generic Entity Factory

If your Entity does not require custom logic in order to be yield (for instance ProductEntityFactory also yields VariantEntities if product is configurable with properties) You don't need to create new Factory for it. It will be handled by Omikron\FactFinder\Shopware6\Export\Data\Factory\GenericEntityFactory.

Note: By entity we consider a class that extends Shopware\Core\Framework\DataAbstractionLayer\Entity class.

If some fields needs more complex logic you can create additional Fields. This is a class that implements Omikron\FactFinder\Shopware6\Export\Field\FieldInterface. In method getCompatibleEntityTypes you can specify which entities this field could be applied to. All fields applicable for given entity will be passed in a form of iterator to the instance of Omikron\FactFinder\Shopware6\Export\Data\ExportEntityInterface. Here is the example (ProductEntity)

//src/Export/Data/Entity/ProductEntity.php:18
public function __construct(Product $product, iterable $productFields)
{
    $this->product       = $product;
    $this->productFields = $productFields;
}

after that you cann call Omikron\FactFinder\Shopware6\Export\FeedFactory to create a Feed wi

$feed = $this->feedFactory->create($context, YourCustomEntity::class);
$feed->generate();

Note: $context is object of class Shopware\Core\System\SalesChannel\SalesChannelContext

Extending Specific Web Component Template

All the Web Components rendering HTML, contains it inside the Twig block. If you need to change it just extend the parent file and override the block which contains the template. For example if you need to define own template for the ff-record element which is responsible for rendering record tiles on search result page

{% sw_extends '@Parent/storefront/components/factfinder/record-list.html.twig' %}

{% block component_factfinder_record %}
    {# here comes the template #}
{% endblock %}

As we see we use sw_extends to extend the parent file and then define the re-define component_factfinder_record block. It is contained in the plugin Resources/views/storefront/components/factfinder/record-list.html.twig file. With this code you override only this block and rest of the parent file HTML will be inherited.

Note: Template in that section stands for the HTML rendered by Web Components, not the .html.twig file

Split ASN on Category Page

The demo version of the split ASN approach is available here. It is possible to reproduce this functionality with the PageBuilder:

  1. Add two FF-ASN CMS Elements

Split ASN layout

  1. Configure the main ASN

Split ASN - Main

  1. Configure the second ASN

Split ASN - Second

Note: In that setup, Filter Cloud must be disabled as for now it has no support for custom topics

Duplicated filter variants

The example above divides the ASN groups into two exclusive collections. If you just want to duplicate some filter from the first ASN and put it in the second, just change the configuration of first ASN to be: Split ASN - Main (duplicate filters)

In that case we do not use splice method but slice which does not mutate the original data.

Note: Dom Updated listener can be empty. ASN groups from the second ASN are also present in first, so there is no need to merge them together. Note: Since all ASN groups are available in first ASN, the Filter Cloud can be used.

Set custom Field Roles

If you don't plan to use feed offered by the module, or you want some of the essential column to have different name than the default you must remember to adjust the field roles used by the FACT-Finder® and the Web Components.

Default field roles are defined as array of Symfony Configuration Parameters in services.xml file`

<parameter key="factfinder.field_roles" type="collection">  
 <parameter key="brand">Manufacturer</parameter>  
 <parameter key="deeplink">Deeplink</parameter>  
 <parameter key="description">Description</parameter>  
 <parameter key="ean">EAN</parameter>  
 <parameter key="displayProductNumber">ProductNumber</parameter>  
 <parameter key="imageUrl">ImageUrl</parameter>  
 <parameter key="masterArticleNumber">Master</parameter>  
 <parameter key="price">Price</parameter>  
 <parameter key="productName">Name</parameter>  
 <parameter key="trackingProductNumber">ProductNumber</parameter>  
</parameter>

In order to override these parameters defined by a module, you have to redefine them in your application services.xml. Parameters defined there take precedence over the defaults, defined in the module

Adding custom Export Cache Subscriber


use Omikron\FactFinder\Shopware6\Events\FeedPreprocessorEntryBeforeCreate;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class FeedPreprocessorEntryBeforeCreateSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [FeedPreprocessorEntryBeforeCreate::class => 'onCreateEntries'];
    }

    public function onCreateEntries(FeedPreprocessorEntryBeforeCreate $event)
    {
        $entry = $event->getEntry();
        $entry['additionalCache'] = [
            'some_data' => 'cache1',
            'some_data2' => 'cache2',
        ];
        $event->setEntry($entry);
    }
}

Enrich data received from FACT-Finder in ProxyController


use Omikron\FactFinder\Shopware6\Events\EnrichProxyDataEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class EnrichProxyDataEventSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [EnrichProxyDataEvent::class => 'enrichData'];
    }

    public function enrichData(EnrichProxyDataEvent $event)
    {
        $data = $event->getData();
        $data['example_data'] = [
            'some_data' => 'data_1',
            'some_data2' => 'data_2',
        ];
        $event->setData($data);
    }
}

Contribute

We welcome contribution! For more information, click here

License

FACT-Finder® Web Components License. For more information see the LICENSE file.