Client-Side Integration

If you are first starting your setup of Pages, read this guide first. This guide will go in-depth on frontend integration.

Requirements & Prerequisites

This method requires the least amount of work to get going.

Divs & Data Attributes

The most important part of the Pages product is to place and input the <div> code snippet.

You can read more about the div tag in this guide here. The div tag placement and setup are quite similar to how you would set up a product recommendation.

Code snippet example - Category:

<div id="helloretail-category-page-{key}" data-filters='
  { "hierarchies": ["value"] }
'></div>

Code snippet example - Brand:

<div id="helloretail-category-page-{key}" data-filters='
  { "brand": "value" }
'></div>

The {key} will be auto-generated and unique for each page created. This means that you can create multiple pages to serve different purposes with various categories.

For examples of this, check this section here. 

The data for hierarchies will be in json format and the data for all other attributes will be in text format, also known as a string.

The "VALUE" in the below code snippet must be changed. See examples in this section here.

It is very important to set up and implement the HTML code snippet correctly with the div tag in order for Hello Retail's system to recognize the tag and show up with the category page.

Reach out to your own developer so they can build the functionality of dynamically adding this div tag with the corresponding data value.

You can read more about the setup of Pages here.

Summary of Requirements:

1. Place and input the <div> code snippet.
2. Input the value to match exactly as on your webshop.
3. Reach out to your own developer so they can build the functionality of dynamically adding this div tag with the corresponding data value.

Process

You will need to add a div to the HTML of the page where you want the category content to appear. The div needs to contain a “data-filter” attribute. This filter is used to determine what products should be shown on the page.

The filter value will typically have to be fetched in the shop platform and dynamically added to the div. You should thereby normally not have a manual div per category or brand page.

A generated div could look like this after the dynamic value has been inserted:

<div id="helloretail-category-page-621ca9f152b27467bdb8d06a" data-filters='{"hierarchies": ["Clothing"]}'></div> 

When the Hello Retail JavaScript runs on the page, it will look for divs matching any active category pages. In the case above, if a category page with the key 621ca9f152b27467bdb8d06a is active, it will find the div.

Once the div has been found it sends an API request to Hello Retail to fetch content for that category page. Included in the request, it will send the provided filters. That allows the API to filter out products that should not be shown.

How this div is generated, and especially how the dynamic filter is generated is very dependent on the shop platform.

As an example this is how it could be done in WooCommerce. The category pages are generated by the /wp-content/plugins/woocommerce/templates/archive-product.php file.

The current category can be found by looking at the breadcrumb. To build a div like the above, the developer would have to add something like this below the title that WooCommerce is generating for the page:

<?php
    $key = '621ca9f152b27467bdb8d06a';
    $breadcrumbs = (new WC_Breadcrumb())->generate();
    $filter = ['hierarchies' => []];
    foreach($breadcrumbs as $b) {
        $filter['hierarchies'][] = $b[0];
    }
?>
<div id="helloretail-category-page-<?=$key?>" data-filters='<?=htmlspecialchars(json_encode($filter), ENT_QUOTES, 'UTF-8')?>'></div>

This will generate a div that automatically puts in the correct filter depending on what category page is being viewed. On the url /product-category/clothing/accessories/ it would output

<div id="helloretail-category-page-621ca9f152b27467bdb8d06a" data-filters='{&quot;hierarchies&quot;:[&quot;Clothing&quot;,&quot;Accessories&quot;]}'></div>

While on the url /product-category/clothing/ it would output

<div id="helloretail-category-page-621ca9f152b27467bdb8d06a" data-filters='{&quot;hierarchies&quot;:[&quot;Clothing&quot;]}'></div>

Once the content is working the existing category page content, generated by the shop platform can be removed.

Examples & Use Cases

The examples below are to showcase different use cases depending on what you see fit with your strategy and needs. This could also apply to cases where you wish to push for something specific because you are planning a sale or anticipating a sales event for an occasion.

Examples

The squared brackets indicate a list with potentially multiple nested lists inside it that contain 1 single category. This means that if you want to show products from Men > Shoes > Boots, it will show products from this single category.

Example - Breadcrumbs:

This also resembles the same kind of structure you can see from breadcrumbs and how it goes into different levels.

For everything contained inside of the [" " ] indicates the indention of sublevels for the categories. These are contained in a list.

'{ "hierarchies": ["woman"] }'

For everything contained inside of the " " indicates a string most commonly used for brands.

'{ "brand": "nike" }'

The example below illustrates the different categories. As you can see, it is also possible to have the same product but located in different categories. In this example, Asics shoes is both in Shoes > Men > Outdoor shoes and Shoes > Women > Sneakers.

<div id="helloretail-category-page-{key}" data-filters='
{ "hierarchies": ["Shoes", "Men", "Outdoor Shoes"] }
'></div>

<div id="helloretail-category-page-{key}" data-filters='
{ "hierarchies": ["Shoes, "Women", "Sneakers"] }
'></div>

Example - Illustration of Categories and Products: 

Use Cases

json

['Electronics']

<div id="helloretail-category-page-{key}"
data-filters='{"hierarchies":["Electronics"]}'>
</div>

json

['Electronics', 'TVs and
Accessories', 'TVs']

<div id="helloretail-category-page-{key}"
data-filters='{"hierarchies":["Electronics", "TVs and Accessories", "TVs"]}'>
</div>

string

"Nike"

<div id="helloretail-category-page-{key}"
data-filters='{"brand": "Nike"}'>
</div>

Fallback Content

If you want to have a fallback in the unlikely event that Hello Retails services are down, an approach can be to fallback to the shop platforms category pages:

1. Make sure the category page content generated by the platform is inside a div. Make this div hidden by adding the style "display:none"

2. Start a timer for, for instance, two seconds.

3. Check if the Hello Retail div has been filled with content when the timer runs out. If not, show the fallback content, and hide the Hello Retail div, as a precaution if the Hello Retail content is loaded later.

In the example from above, this would look something like this:

<?php
    $key = '621ca9f152b27467bdb8d06a'; 
    $breadcrumbs = (new WC_Breadcrumb())->generate();
    $filter = ['hierarchies' => []];
    foreach($breadcrumbs as $b) {
        $filter['hierarchies'][] = $b[0];
    }
?>
<div id="helloretail-category-page-<?=$key?>" data-filters='<?=htmlspecialchars(json_encode($filter), ENT_QUOTES, 'UTF-8')?>'></div>
<div id="platform-default-category-page" style="display:none"> ... </div>

<script>
    // Show default category if Hello Retail loads 0 products after 2 seconds of wait.
    setTimeout(function() {
        var helloretailContent = document.querySelector("#helloretail-category-page-<?=$key?> .hr-products-container");
        var woocommerceContent = document.getElementById("platform-default-category-page");
        if (helloretailContent?.children.length === 0) {
            helloretailContent.closest("#helloretail-category-page-<?=$key?>").style.display="none";
            woocommerceContent.style.display="block";
        }
    }, 2000);
</script>

You can always check Hello Retail's system status from here and subscribe to updates if needed.