API Integration (HTML Response)

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

---

Requirements & Prerequisites

The following solution is great if you want to use the default designs that Hello Retail can provide, but you want to render them serverside.

Read more about the Pages API in our developer documentation.

---

Process

The idea with this method is that the initial load of the content for the category page is done as an API call from the webshop's backend code, and then the returned HTML, CSS & JS is rendered serverside. This will allow the page to have content immediately when it loads in the browser. The subsequent requests, when paginating or filtering can be done as ajax requests from the Javascript in the frontend.

The process consists of 3 steps.

1. Send an API call to Hello Retail to get the content. The response will contain HTML, CSS, and JavaScript.

2. Make the returned HTML and CSS part of the page. The HTML has to be injected into a div. A reference to this div is needed in the next step.

3. Inject the JavaScript into the page. Before the JavaScript is executed, it needs to wait for the Hello Retail script to be ready. This is most easily done by waiting for the context_ready event from the Hello Retail script.

The category page generated by Hello Retail typically includes filters. When a filter is set, it is added to the URL. If you want to allow the customer to reload the page and still have the filters they previously applied set, then you need to have these filters be retrieved on the backend and passed in the API call.

---

Example

The following is an example of how the backend integration can be implemented in WooCommerce. The default category page is implemented in the /wp-content/plugins/woocommerce/templates/archive-product.php file.

You will see some similarities with the code for generating the div for the front end integration.

The below requires the design template for the page in hello Retail is configured to save its filters in the query string parameter hr-page

<?php
    $key = '621ca9f152b27467bdb8d06a';
    $breadcrumbs = (new WC_Breadcrumb())->generate();
    $baseFilter = ['hierarchies' => []];
    foreach($breadcrumbs as $b) {
        $baseFilter['hierarchies'][] = $b[0];
    }
    $baseFilter = json_encode($baseFilter);
    $trackingUserId = $_COOKIE['hello_retail_id'];
    $filters = [];
    $sorting = [];
    $start = 0;
    $count = 24;
    if (isset($_GET['hr-page'])) {
        $decoded = json_decode($_GET['hr-page'], true);
        if (isset($decoded['filters'])) {
            $filters = $decoded['filters'];
        }
        if (isset($decoded['sorting'])) {
            $sorting = $decoded['sorting'];
        }
        if (isset($decoded["page"])) {
            if (isset($decoded["pagesize"])) {
                $count = $decoded["pagesize"];
            } else {
                $count = 24;
            }
            $start = ($decoded["page"] - 1) * $count;
        }
    }
    $req = [
        "url" => $_SERVER["REQUEST_URI"],
        "layout" => true,
        "products" => [
            "start" => $start,
            "count" => $count,
            "filters" => $filters,
            "sorting" => $sorting
        ],
        "params" => [
            "filters" => $baseFilter
        ],
        "firstLoad" => true,
        "trackingUserId" => $trackingUserId
    ];
    $opts = [
        "http" => [
            'method' => 'POST',
            'header' => 'Content-type: application/json',
            'content' => json_encode($req)
        ]
    ];
    $context = stream_context_create($opts);
    $content = file_get_contents('https://core.helloretail.com/serve/pages/' . $key, false, $context); 

    if ($content) {
        $content = json_decode($content, true);
        $req["products"]["count"] = $content["products"]["count"];
        $req["products"]["total"] = $content["products"]["total"];
        ?>
            <div id='hr-category-page'>
                <?=$content['products']['html']?>
            </div>
            <style><?=$content['products']['style']?></style>
            <script>
                hrq = window.hrq || [];
                hrq.push(function(){
                    (function(_, container, data, page){
                        <?=$content['products']['javascript']?>
                    })(
                        ADDWISH_PARTNER_NS,
                        document.getElementById('hr-category-page'),
                        <?=json_encode($req)?>,  {  key:'<?=$key?>'  }
                    )
                });
            </script>
        <?php
            } else {
        // output the default platform category page } 
?>

The various parts of this would often be split into a part that is handled in a controller and a part that is handled in the view.