PHPackages omikron/magento2-factfinder - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. omikron/magento2-factfinder ActiveMagento2-module omikron/magento2-factfinder =========================== FACTFinder Webcomponents SDK v5.2.1(10mo ago)1160.9k—2.5%17[9 issues](https://github.com/FACT-Finder-Web-Components/magento2-module/issues)[3 PRs](https://github.com/FACT-Finder-Web-Components/magento2-module/pulls)proprietaryPHPPHP ~8.1.0||~8.2.0||~8.3.0CI failing Since Oct 31Pushed 3mo ago4 watchersCompare [ Source](https://github.com/FACT-Finder-Web-Components/magento2-module)[ Packagist](https://packagist.org/packages/omikron/magento2-factfinder)[ RSS](/packages/omikron-magento2-factfinder/feed)WikiDiscussions release/5.x Synced 1mo ago READMEChangelog (10)Dependencies (14)Versions (106)Used By (0) FACT-Finder® Web Components for Magento 2 ========================================= [](#fact-finder-web-components-for-magento-2) [![Packagist Version](https://camo.githubusercontent.com/21662658267f1beea37cba6f8a0e95865c99b2f410b6259248f21257dd596285/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f6d696b726f6e2f6d6167656e746f322d6661637466696e646572)](https://packagist.org/packages/omikron/magento2-factfinder)[![Build status](https://github.com/FACT-Finder-Web-Components/magento2-module/workflows/build/badge.svg)](https://github.com/FACT-Finder-Web-Components/magento2-module/actions)[![GitHub contributors](https://camo.githubusercontent.com/d81abc8c1098c491885b6f2bbe33c309df782c85600e4ce8fb4fab3f293c3be8/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6e7472696275746f72732f464143542d46696e6465722d5765622d436f6d706f6e656e74732f6d6167656e746f322d6d6f64756c65)](https://github.com/FACT-Finder-Web-Components/magento2-module/graphs/contributors) This is a new version of SDK which support new WebComponents v5 NG. This document helps you integrate the FACT-Finder Web Components SDK into your Magento 2 Shop. In addition, it gives a concise overview of its primary functions. The first chapter *Installation* walks you through the suggested installation processes. The second chapter “Backend Configuration” explains the customisation options in the Magento 2 backend. The final chapter *Web Component Integration* describes how the web components interface with the shop system and how to customise them. Our Magento 2 module offers a basic working integration for default Magento2 Luma theme. Most projects may require modifications in order to fit their needs. For more advanced features please check our official [WebComponnents documentation](https://web-components.fact-finder.de/documentation/5.x/install-dist). Table of contents ----------------- [](#table-of-contents) - [Requirements](#requirements) - [Installation](#installation) - [Activating the Module](#activating-the-module) - [Backend Configuration](#backend-configuration) - [Main Settings](#main-settings) - [FACT-Finder version](#fact-finder-version) - [Server Side Rendering](#server-side-rendering) - [Advanced Settings](#advanced-settings) - [Currency and Country Settings](#currency-and-country-settings) - [Optional Custom Elements](#optional-custom-elements) - [Custom Elements Options](#custom-elements-options) - [Export Settings](#export-settings) - [CMS Export Settings](#cms-export-settings) - [Data Transfer Settings](#data-transfer-settings) - [Updating Field Roles](#updating-field-roles) - [Automatic Import](#automatic-import) - [Data Export](#data-export) - [Feed Types](#feed-types) - [Integration Methods](#integration-methods) - [FTP Export](#ftp-export) - [HTTP Export](#http-export) - [Console Command](#console-command) - [Web Component Integration](#web-component-integration) - [Searchbox Integration and Functions](#searchbox-integration-and-functions) - [Process of Data Transfer between Shop and FACT-Finder](#process-of-data-transfer-between-shop-and-fact-finder) - [Using Proxy](#using-proxy) - [Using FACT-Finder on category pages](#using-fact-finder-on-category-pages) - [Tracking](#tracking) - [Modification examples](#modification-examples) - [Changing existing column names](#changing-existing-column-names) - [Adding new column](#adding-new-column) - [GenericField usage](#genericfield-usage) - [Adding custom product data provider](#adding-custom-product-data-provider) - [Configure field to be exported from variant](#configure-field-to-be-exported-from-variant) - [Troubleshooting](#troubleshooting) - [Removing `/pub` from exported URLs](#removing-pub-from-exported-urls) - [Contribute](#contribute) - [License](#license) Requirements ------------ [](#requirements) This module supports: - Magento 2 version 2.4.4 and higher - PHP version 8.1 and higher Installation ------------ [](#installation) To install module, open your terminal and run the command: ``` composer require omikron/magento2-factfinder ``` Optionally, you can specify a version constraint, e.g. `omikron/magento2-factfinder:^5.0`. Refer to Composer manual for more information. If, for some reason, `composer` is not available globally, proceed to install it following the instructions available on the [project website](https://getcomposer.org/doc/00-intro.md). Activating the Module --------------------- [](#activating-the-module) From the root of your Magento 2 installation, enter these commands in sequence: ``` php bin/magento module:enable Omikron_Factfinder php bin/magento setup:upgrade ``` As a final step, check the module activation by running: ``` php bin/magento module:status ``` The module should now appear in the upper list *List of enabled modules*. Also, check in the Magento 2 backend "Stores → Configuration → Catalog → FACT-Finder" if the module output is activated. [![Module configuration](docs/assets/admin-section.png "Module configuration")](docs/assets/admin-section.png) Backend Configuration --------------------- [](#backend-configuration) Once the FACT-Finder module is activated, you can find the configurations page under "Stores → Configuration → Catalog → FACT-Finder". Here you can customise the connection to the FACT-Finder service. You can also activate and deactivate single web components, as well as access many additional settings. ### Main Settings [](#main-settings) At the top of the configurations page are the main settings. The information with which the shop connects to and authorises itself to the FACT-Finder Service are entered here. In the first line, activate your FACT-Finder integration. Before any changes become active, save them by clicking "Save Config". In some cases, you need to manually empty the cache (System → Cache Management → Flush Magento Cache ). Click the button "Test Connection" to check the connection to the FACT-Finder service. **Note:** the **channel name, server URL and API key** need to be entered correctly to establish a connection. Here you can also enable the rendering of category pages using FACT-Finder. More details can be found [here](#using-fact-finder-on-category-pages). At the end of the *Main Settings* section is an option *Show 'Add to Cart' Button in Search Results*. Activate this option to add a button to the products displayed on the search result page, which directly adds that product to the shopping cart. This feature works only for simple products. For configurable products user will be redirected to product page to choose specific product variant. Warning: The product added to the cart is identified by the variable "MasterProductNumber". To allow this function to work correctly, the field "MasterProductNumber" must be imported to the FACT-Finder backend (on fact-finder.de). By enabling option *Activate Logging*, all exceptions thrown during communication with FACT-Finder server will be saved in log file `var/log/factfinder.log`. **Note:** that is a server side communication option: Web Components behaviour won't be affected. [![Main Settings](docs/assets/general-settings.png "Main Settings")](docs/assets/general-settings.png) #### FACT-Finder version [](#fact-finder-version) From version 5, the module supports only `NG` FACT-Finder version. If you use lower version, please use SDK [version 4.x](https://github.com/FACT-Finder-Web-Components/magento2-module/tree/release/4.x) #### Server Side Rendering [](#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. The module uses [Handlebars PHP](https://github.com/salesforce/handlebars-php) library for template processing **Note:** More information about SSR concept you can find in the article [Server Side Rendering](https://web-components.fact-finder.de/documentation/5.x/server-side-rendering) from Web Components documentation. ### Advanced Settings [](#advanced-settings) [![Optional Custom Elements](docs/assets/advanced-settings.png "Optional Custom Elements")](docs/assets/advanced-settings.png) Advanced Settings contains additional parameters used for the WebComponents configurations. Each setting is set to a default value and has a short explanatory text attached. #### Currency and Country Settings [](#currency-and-country-settings) You don't need to set currency nor country only for module purposes. It will use currently used currency and pass this information to `factfinder init`component as respectively `currency-code` and `currency-country-code` parameters. You can find these settings under Magento General settings - [How to configure currency?](https://docs.magento.com/m2/ce/user_guide/stores/currency-configuration.html) - [How to configure country?](https://docs.magento.com/m2/ce/user_guide/stores/country-options.html) ### Optional Custom Elements [](#optional-custom-elements) [![Optional Custom Elements](docs/assets/optional-custom-elements.png "Optional Custom Elements")](docs/assets/optional-custom-elements.png)Some of the custom elements we offer works only when specific additional FACT-Finder modules has been purchased. Here you can disabled them, if you do not use utilize this part of FACT-Finder functionality **Note:** Feedback campaign support only labels: **above search result**. More labels needs some simple code customisation. **Note:** Paging has been added cause with infinite scrolling enabled in ff-record list, this custom element is redundant **Note:** Page id in Landing page campaign base on Magento CMS page Identifier name ### Custom Elements Options [](#custom-elements-options) [![Custom Elements Options](docs/assets/custom-elements-options.png "Custom Elements Options")](docs/assets/custom-elements-options.png)In this section you can find specific custom elements attributes, the values of which, you can configure. The values stored here are passed to specific places in the templates of the corresponding elements. ### Export Settings [](#export-settings) [![Product Data Export](docs/assets/export-settings.png "Product Data Export")](docs/assets/export-settings.png) In this section users can decide if the attributes should be exported as single fields or grouped into a multi-attribute field. Setting Multi-Attribute to No will result attribute being part of cumulative column FilterAttribute. Setting value to Yes will result attribute will be exported into separated column. Attribute export is working for the attributes of type: - boolean - price - select - multiselect - all scalars #### Numerical attributes [](#numerical-attributes) Setting a multi-attribute field as numerical, will cause this field to be exported to a separate multi-attribute column named `NumericalAttributes`. This would easier filter configuration in FACT-Finder. **Note:** Attributes which are part of configuration are always exported to `FilterAttributes`. ### CMS Export Settings [](#cms-export-settings) You can export Your CMS pages to FACT-Finder to present them in suggest results. [![CMS Export Settings](docs/assets/cms-settings.png "CMS Export Settings - using single channel")](docs/assets/cms-settings.png) - **Pages Blacklist** - allow user to filter out pages, which should not be exported, for example "404 Not Found page" should not be visible at suggested records If you want to start using CMS export in your project, please contact a person from FACT-Finder who is assigned to your project or ask our Service Desk. **Note:** CMS Export is available only via console command ### Data Transfer Settings [](#data-transfer-settings) This option configures the connection with the FACT-Finder system via FTP/SFTP. Shop data can be generated and transferred to FACT-Finder using FTP/SFTP. FACT-Finder needs to be up to date on the product data, to ensure that components like the search work as intended. For FTP servers you will likely specify the user and password For SFTP servers you can use both authenication methods: key or password **Note** Magento uploader does not allow files without extension. If your key file doesn't have any, please add one (for example .rsa) **Note** Don't forget to specify the key passhprase if it's protected Enter an server to which the CSV file is uploaded automatically. If you are not sure if Magento will be able to connect to your server, please use "Test Upload connection" button. The CSV file uses double quotes `"` for field enclosure and a semi-colon `;` as field delimiter. Before starting the export by clicking *Generate Export File(s) now*, you need to commit all changes by clicking "Save Config". The exception to that rule is `Test Connection` function which always takes the actual values from the corresponding fields. [![Data Transfer Settings](docs/assets/data-transfer-settings.png "Data Transfer Settings")](docs/assets/data-transfer-settings.png) #### Updating Field Roles [](#updating-field-roles) Field roles are assigned while creating new channel in FACT-Finder application, however they can be changed anytime. In this situations, You need to update field roles which are being kept in Magento database for tracking purposes. To updates field roles, use the button `Update Field Roles` #### Automatic Import [](#automatic-import) Once the feed file is uploaded (using [FTP Export](#ftp-export)), in order FACT-Finder to start serving new data, import needs to be triggered. Module allows You to enable automatic import which makes FACT-Finder import will be triggered, right after the feed file is uploaded onto FTP server. You can also select which of data types should be imported automatically - Search - Suggest - Recommendation This is a multiselect field, so You can select all of them Data Export ----------- [](#data-export) In following section You'll get information how, to integrate Your feed with FACT-Finder. Feed is built the same way, regardless of chosen method, so You can choose from one of possible methods. ### Feed Types [](#feed-types) Module ise capable of exporting feeds in one of the following types - Product - CMS - Category Product is the main feed that will be used by FACT-Finder to produce search result for your shop. CMS could be used as an separate search result source (if you have search functionality in your blog) or to enriche suggestions (if you want to suggest blog articles related to user search query). Category is used to enrich suggestions by adding categories URLs category to specific suggest items ### Integration Methods [](#integration-methods) #### FTP export [](#ftp-export) This method exports feed from shop system and uploads it to FTP server. In order to use this method of export, You need to have FTP server configured (described in section [Data Transfer Settings](#data-transfer-settings)). Then You can click the button (visible below) to generate and then, upload file via FTP. [![Product Data Export](docs/assets/generate-feed.png "Generate Export File(s) now")](docs/assets/generate-feed.png) Using of that button is dedicated mostly for ad-hoc export. In production environment You'll rather use Cron job which will do the same work without forcing You to click the export button each time You want to send new data to FACT-Finder. To configure Cron, please activate the option *Generate Export Files(s) automatically* and the export will be generated every day at 01:00 server time. You can define your own cron expression in the module configuration (section visible below). Please remember that this setting is only for that specific task ran under Magento supervisor. It won't work until You have not system Cron configured. To do that, You'll need to add Magento Cron entrypoint to Your system crontab file. Read this [tutorial](https://devdocs.magento.com/guides/v2.3/config-guide/cli/config-cli-subcommands-cron.html) for more information [![Cron Configuration](docs/assets/cron-configuration_en.jpg "Cron Configuration")](docs/assets/cron-configuration_en.jpg) #### HTTP Export [](#http-export) Alternative way to integrate Your feed is to use builtin FACT-Finder functionality to periodically download feed from specific URL which the feed is accessible at. This URL should be secured by Basic Auth (username and password configured at section [Data Transfer Settings](#data-transfer-settings)) in order only authenticated users get access to. By making this URL no secured, You are allowing literally everyone to download Your feed! Exports are available under following location: `https://YOUR_SHOP_URL/factfinder/export/product/store/YOUR_STORE_ID` If there's no `store id` provided, feed will be generated with the default store (by default with id = 1) You should provide this URL in Your FACT-Finder UI [![FACT-Finder Import settings](docs/assets/import-settings.png "Import settings")](docs/assets/import-settings.png) ### Console Command [](#console-command) If You are a developer and want to test feed is generated correctly or You do not want to executing magento cron You can use console command which is implementation of Command of Symfony Console Component, builtin in Magento2. Command name: `factfinder:export [TYPE]`. You can add execution of this command to Your crontab file. - Arguments: - type (mandatory) - set the `FeedFactory` class with a type of data to be exported. If for a given type, no data provider exists, an exception will be thrown. Possible default values are `product` and `cms`. - Options (all optional) - store - define a store, which the product data will be taken from - skip-ftp-upload - skips the ftp upload - skip-push-import - skips triggering import Web Component Integration ------------------------- [](#web-component-integration) You can activate and deactivate any web components from the configurations page in the Magento 2 backend. The HTML code for the web components can be found in this folder: ``` src/view/frontend/templates/ff ``` The module styles can be found in this folder ``` src/view/frontend/web/css/source/ff ``` Since Magento 2 is using Less, all source styles are written in this stylesheet language ``` src/view/frontend/web/css/source/_module.less ``` You can integrate the templates anywhere within your shop system. The recommended way is to use Magento2 layouts for that. As an example, the `ff-suggest` element was integrated into the `ff-searchbox` template for this SDK: ``` Omikron_Factfinder::ff/searchbox.phtml ``` You can also instantiate block in templates using the Magento Layout API, but it's not a recommended way ```