Overwriting Widgets

Overwriting an existing widget with our recommendations is useful in the following contexts:

• You want to rewrite a subset of the recommendations in a widget area that you have already designed.
• You want to run an A/B test against your own internal recommendations.
• You want to maintain a fallback set of recommendations to show if the user is unable to fetch our recommendations (due to browser issues on the user’s side, network connectivity issues, or server timeouts on our side).

1. Illustration: rewriting some items with recommendations from one widget

Assume you already have the following recommendation area on your page:

HTML

<div id="li-recommendation-unit">
  <div class='recommended_item'>
    <a class='headline' href='//url-1'>Title 1</a>
  </div>

  <div class='recommended_item'>
    <a class='headline' href='//url-2'>Title 1</a>
  </div>

  <div class='recommended_item'>
    <a class='headline' href='//url-3'>Title 3</a>
  </div>

  <div class='recommended_item'>
    <a class='headline' href='//url-4'>Title 4</a>
  </div>
</div>

Suppose you want to overwrite the 2nd and 4th recommended_item with LiftIgniter recommendations. You can do that as follows:

Step 1 Tag the items you want to replace (e.g. by adding li-widget-item to the class):

HTML

<div id="li-recommendation-unit">
  <div class='recommended_item'>
    <a class='headline' href='//url-1'>Title 1</a>
  </div>

  <div class='recommended_item li-widget-item'>
    <a class='headline' href='//url-2'>Title 1</a>
  </div>

  <div class='recommended_item'>
    <a class='headline' href='//url-3'>Title 3</a>
  </div>

  <div class='recommended_item li-widget-item'>
    <a class='headline' href='//url-4'>Title 4</a>
  </div>
</div>

Step 2 Add a mustache template matching the tagged units to your page:

HTML

<script type="application/mustache" id="recommended-item-template">
  <div class='recommended_item'>
    <a class='headline' href='{{url}}'>{{title}}</a>
  </div>
</script>

Step 3 Render recommendations with appropriate callback

JavaScript

// Renders the recommendations and overwrites area marked with 'li-widget-item'.
var overwrite_callback = function(resp) {
    var els = document.querySelectorAll(
      '#li-recommendation-unit > div.li-widget-item');
    var template = document.querySelector(
      '#recommended-item-template').innerHTML;
    for (var i = 0;
         i < els.length && i < resp.items.length;
         ++i) {
         els[i].innerHTML = $p('render', template, resp.items[i]);
         // Basically Mustache.render(template, resp.items[i]);
    }
   $p('track', {
       elements: document.querySelectorAll('#li-recommendation-unit > div.li-widget-item'
), // track LI recommendations
       name: 'default-widget',
       source: 'LI',
       opts: {}		 // Optional parameters to track with each event.
                         // If the corresponding 'register' call had optional
                         // fields, exactly those fields MUST be present here.
		                }
		       );

}
// Register call to fetch recommendations.
// Apply the overwrite callback.
$p('register', {
                  max: 2,
                  widget: 'default-widget',
                  callback: overwrite_callback // You may wish to wrap this inside jQuery or another listener to make sure that the widget you intend to overwrite has actually loaded
               }
);
// Executes the registered call.
$p('fetch');

❗️

Load order issues

Keep in mind that if your recommendations that you intend to overwrite have not loaded when the callback is executed, LiftIgniter's recommendations will not be able to replace them. You can remedy the problem by wrapping the execution inside a jQuery. For more, see our documentation on load order.

📘

Rewrite items with recommendations from multiple widget calls

You can populate an area of your site with recommendations mixed and matched from different widget calls.