Autocomplete (JS) - boxalino/rtux-integration-magento2 GitHub Wiki

Before you continue, make sure the required integration steps have been completed.

The proposed integration of the autocomplete requires to have an up-to-date Boxalino data-index (especially price if it is part of your design); Unlike the other features, the autocomplete integration is fully front-end driven.

The content of the response depends 100% on your design and layout blocks desired.

Before you start, the layout blocks & narrative layout must be defined in Boxalino Intelligence admin.

The Layout Blocks JSON & Narratives JSON from this page can be used as base.

If there is no narrative assigned to the choice/widget requested, the response will be empty.

The provided JSON samples for the Narrative layout and the Layout blocks must be imported in Boxalino Intelligence Admin

Integration description

The proposed strategy is as follows:

1. Rewrite the _onPropertyChange function from the Magento2 $.mage.quickSearch component with the use of a mixin
2. Keep the autocomplete elements rendering design in a template. This will allow the designers to edit the design without altering the JavaScript/autocomplete logic.
3. Use the Boxalino Layout Blocks & Narrative to define what template ID to be used for each element type (textual suggestion, product, blog, filters, etc)

Prerequisites

Set the return fields for autocomplete (if missing)

Autocomplete acts as a "search" sub-request so it does not have a widget of it`s own in Boxalino Intelligence Admin. By default, only the product ID will be part of the response. In order to change that, you can add an optimization strategy to the search widget.

1. Open the "search" widget in Boxalino Intelligence Admin
2. Add the use-case: "Add return fields (simple)"
3. Write the fields used in your autocomplete template.
4. Save & test, save
5. Publish (if production ready)

Optionally, you can just import the provided JSON for optimization strategy in the search widget.

Steps

In order to enable Boxalino JS autocomplete requests, the following steps must be followed:

1. Update plugin configurations.

In order to make API requests just with the use of the API-key, request from Boxalino support team the JavaScript API Key- with PUBLIC_NARRATIVE role. The configurations path in your Magento2 back-end is: Stores >> Configuration >> Boxalino API >> REST API >> JS API Key

2. Initialize the rtuxApiHelper JS component.

This is achieved by adding the Boxalino_RealTimeUserExperience::js.phtml to the layout.

3. Design planning

• consider what properties from the Boxalino data-index are required for your integration; these have to be added as "return fields" in the Boxalino Intelligence "search" widget; (ex: title, discountedPrice, products_url_key, products_image)
• decide the layout; as a general practice, it has the following elements in order: a list of textual suggestions, a "Products" title to divide sections, a list of products; after this base implementation, feel free to extend the layout to also include blogs, filters (categories) and other elements.

4. Create the templates.

As a recommendation, keep the JS template in a phtml/html file which can easily be edited/extended without touching the JavaScript logic. For the purpose of the integration, 3 templates are provided marked by ID which is assign to each content type in the Boxalino Layout Block.

5. Create the JS mixin.

Follow the mixin documentation available in the JS file.

6. Add the Layout Blocks & Narrative.

In order to receive a response, the narrative has to be present in Boxalino Intelligence. Feel free to use the sample structures available in wiki.

7. Activate the integration;

• update requirejs-config.js
• add the JS template on the layout
• compile the theme (if required)

---

Layout Blocks JSON

[ { "id": 970, "uniqueKey": "autocomplete_suggestion_list", "parametersJsonScheme": "{\n \"title\": \"Autocomplete Text List\",\n \"type\": \"object\",\n \"properties\": {\n \"accessor\": {\n \"type\": \"string\",\n \"description\": \"ac-queries accessor (typically leave empty)\"\n }\n }\n}", "format": null, "widgets": [], "parameters": [ { "name": "bx-acQueries", "values": [ "accessor" ] }, { "name": "template", "values": [ "#rtux-suggestion-template" ] }, { "name": "content", "values": [ "suggestion" ] }, { "name": "content-resource", "values": [ "c-r=t" ] } ], "subRenderings": [], "route": "visual-elements", "reqParams": null, "$fromServer": true, "parentResource": null, "restangularCollection": false, "isSelected": true }, { "id": 974, "uniqueKey": "autocomplete_suggestion", "parametersJsonScheme": "{\n \"title\": \"Autocomplete Suggestion\",\n \"type\": \"object\",\n \"properties\": {\n \"accessor\": {\n \"type\": \"string\",\n \"description\": \"autocomplete accessor (typically leave empty)\"\n }\n }\n}", "format": null, "widgets": [], "parameters": [ { "name": "bx-acQuery", "values": [ "accessor" ] }, { "name": "class", "values": [ "suggestion-item sub_product_suggestions sub_id_" ] }, { "name": "content-resource", "values": [ "c-r=t" ] } ], "subRenderings": [], "route": "visual-elements", "reqParams": null, "$fromServer": true, "parentResource": null, "restangularCollection": false, "isSelected": true }, { "id": 998, "uniqueKey": "autocomplete_hit_list", "parametersJsonScheme": "{\n \"title\": \"Hits List\",\n \"type\": \"object\",\n \"properties\": {\n \"title\": {\n \"type\": \"object\",\n \"title\": \"Label\",\n \"properties\": {\n \"de\": {\n \"type\": \"string\",\n \"description\": \"label in German\"\n },\n \"fr\": {\n \"type\": \"string\",\n \"description\": \"label in French\"\n },\n \"it\": {\n \"type\": \"string\",\n \"description\": \"label in Italian\"\n },\n \"en\": {\n \"type\": \"string\",\n \"description\": \"label in English\"\n }\n }\n },\n \"content\": {\n \"type\": \"string\",\n \"description\": \"hits content (blog, product, etc)\"\n },\n \"template\": {\n \"type\": \"string\",\n \"description\": \"hits template (JS id as configured)\"\n },\n \"accessor\": {\n \"type\": \"string\",\n \"description\": \"hits accessor (typically leave empty)\"\n }\n }\n}", "format": null, "widgets": [], "parameters": [ { "name": "bx-hits", "values": [ "accessor" ] }, { "name": "content-resource", "values": [ "c-r=t" ] } ], "subRenderings": [], "route": "visual-elements", "reqParams": null, "$fromServer": true, "parentResource": null, "restangularCollection": false, "isSelected": true }, { "id": 999, "uniqueKey": "autocomplete_hit", "parametersJsonScheme": "{\n \"title\": \"Autocomplete Product\",\n \"type\": \"object\",\n \"properties\": {\n \"accessor\": {\n \"type\": \"string\",\n \"description\": \"hits accessor (typically leave empty)\"\n }\n }\n}", "format": null, "widgets": [], "parameters": [ { "name": "bx-hit", "values": [ "accessor" ] }, { "name": "content-resource", "values": [ "c-r=t" ] }, { "name": "class", "values": [ "suggestion-item global_product_suggestions" ] } ], "subRenderings": [], "route": "visual-elements", "reqParams": null, "$fromServer": true, "parentResource": null, "restangularCollection": false, "isSelected": true } ]

---

Narrative Layout JSON

[ { "id": 886, "status": null, "uniqueKey": "autocomplete-js", "aliases": null, "widgets": [ "autocomplete" ], "allWidgets": null, "parametersJsonScheme": null, "seoContent": { "title": [ { "language": "de", "value": "" }, { "language": "fr", "value": "" }, { "language": "it", "value": "" }, { "language": "en", "value": "" } ], "metaTags": [], "h1": [ { "language": "de", "value": "" }, { "language": "fr", "value": "" }, { "language": "it", "value": "" }, { "language": "en", "value": "" } ], "others": [ { "name": "breadcrumbs", "value": [ { "language": "de", "value": "" }, { "language": "fr", "value": "" }, { "language": "it", "value": "" }, { "language": "en", "value": "" } ] } ] }, "contexts": [], "layoutModels": null, "acts": [ { "parameters": [ null ], "chapter": { "format": "CPOActChapter", "contexts": [], "subActs": [], "journeyStepUniqueKeys": null, "callToActions": null, "renderings": [ { "parameters": [ null ], "rendering": { "contexts": [], "layoutModels": [], "visualElements": [ { "visualElementModelUniqueKey": "autocomplete_suggestion_list", "label": "Suggestion list", "parameters": [ { "name": "accessor", "values": [ "" ] } ], "visualElement": null, "subRenderings": [ { "parameters": [ null ], "rendering": { "contexts": [], "layoutModels": [], "visualElements": [ { "visualElementModelUniqueKey": "autocomplete_suggestion", "label": "Suggestion", "parameters": [ { "name": "accessor", "values": [ "" ] } ], "visualElement": null, "subRenderings": [ { "parameters": [ null ], "rendering": { "contexts": [], "layoutModels": [], "visualElements": [], "parameters": null } } ] } ], "parameters": null } } ] }, { "visualElementModelUniqueKey": "autocomplete_hit_list", "label": "Product list", "parameters": [ { "name": "title", "values": [ "{\"de\":\"Produkte\",\"fr\":\"Produits\",\"it\":\"Prodotti\",\"en\":\"Products\"}" ] }, { "name": "content", "values": [ "product" ] }, { "name": "accessor", "values": [ "" ] }, { "name": "template", "values": [ "#rtux-product-template" ] } ], "visualElement": null, "subRenderings": [ { "parameters": [ null ], "rendering": { "contexts": [], "layoutModels": [], "visualElements": [ { "visualElementModelUniqueKey": "autocomplete_hit", "label": "Dynamic Product", "parameters": [ { "name": "accessor", "values": [ "" ] } ], "visualElement": null, "subRenderings": [ { "parameters": [ null ], "rendering": { "contexts": [], "layoutModels": [], "visualElements": [], "parameters": null } } ] } ], "parameters": null } } ] } ], "parameters": null } } ], "parameters": null } } ], "parameters": [], "route": "narratives", "reqParams": null, "$fromServer": true, "parentResource": null, "restangularCollection": false, "isSelected": true } ]

Optimization strategy (add return fields)

[ { "id": 0, "useCaseModelSource": "library", "useCaseModelId": 144, "useCaseModelVersion": 1, "useCaseModelSubVersion": 1, "name": "Add Return Fields (simple)", "order": "0", "orGroup": null, "fromIndex": -1, "toIndex": -1, "maxWeight": null, "variant": "", "scope": "local", "overwriteLevel": 1, "overwriteLabel": [ null ], "globalTargetTags": [ null ], "active": true, "parameters": [ { "name": "fields", "value": { "format": "StringParameterValues", "values": "title,discountedPrice,products_url_key,products_image,products_group_id" }, "scope": "global" } ], "segmentationIds": null, "segmentationUniqueKeys": [], "CPOInitiativeId": null, "notes": null, "options": { "status": null, "includeWidgets": null, "excludeWidgets": null, "allWidgets": null, "conditionalSegments": null, "conditionalProductSelections": null, "ordering": null, "parameters": [ { "name": "system", "values": [ "false" ] } ], "allLinkedAccounts": null, "accounts": null }, "icons": { "strategy": { "value": "cpo_sales.png", "tooltip": "SALES OPTIMIZATION" }, "level": { "value": "L1", "tooltip": "LEVEL 1 - ONLINE CONVERSIONS" }, "initiative": { "value": "fa-folder", "tooltip": "RELEVANT SOFT-CRITERIA" }, "character": { "value": "fa-sort-amount-asc", "tooltip": "RANKER: Promote products based on a numeric attribute value (e.g: boost the products based on sales count)" }, "mode": { "label": "UP", "value": "up-color", "tooltip": "USE-CASE PARAMETRIZATION: Defined values and attributes of Use Cases configuring the desired business rules" } }, "sections": [ { "id": "main", "label": "Values", "active": true } ], "status": true, "isSelected": true } ]