trends api docs

trends.md

Placeholder api

As a salecycle standard we use ${BasketCount} to define the location for trends in the osr. However, the script never looks specifically for BasketCount, it just needs ${} to be present. All of these placeholders are valid:

• ${BasketCount}
• ${}
• ${foobar}

HTML class naming api

There are two class names that need to be present in #wrapper-sc for trends to render correctly:

(1) .trendsHide-sc

This element acts as a template whose content should never be displayed, it is just a content template.

(2) .trendsShow-sc

This element acts as a rendering target for your template data generated via .trendsHide-sc. Importantly, any content you have in .trendsShow-sc will be overridden by your content generated via the template defined in .trendsHide-sc.

Dynamic HTML example

Because trends is usually used with dynamic messages, there shouldn't really be anything in .hideTrends-sc or .showTrends-sc. Trends are displayed in the html mostly through the script, but it's impossible to know how to configure the html correctly unless the person who authors the html is in close collaboration with the person that authors the script.

<!-- what should be in portal -->
<div id="wrapper-sc">
  <div class="hideTrends-sc">${BasketCount}</div>
  <div class="showTrends-sc"></div>
</div>

<!-- what will be rendered on the page -->
<div id="wrapper-sc">
  <div class="hideTrends-sc">${BasketCount}</div>
  <!-- "people are viewing" is never written in the osr html, it should be configured inside the script -->
  <div class="showTrends-sc">5 people are viewing this item.</div>
</div>

Correct melds to use

You always want to make a reference to trueTrends with a closure.

var trueTrends;

// store trends with closure
// will give other melds down the osr lifecycle access to the data
meld.around(__sco.osr, 'showTrendsContent', function(methodcall) {
  trueTrends = methodCall.args[0][0].BasketCount;
  methodCall.proceed();
});

Melds that occur later in the osr lifecycle will make use of trueTrends but there are several ways you can do this.

(1) meld.after(__sco.osr, '_render')

meld.after(__sco.osr, '_render', function() {
  var trendsDisplayContainer = _scs('.trendsShow-sc:first');
  var copy = ' looking at this product';
  if (trueTrends === 1)
    trendsDisplayContainer.innerHTML = '1 person is' + copy; 
  else if (trueTrends > 1)
    trendsDisplayContainer.innerHTML = trueTrends + ' people are' + copy;
  else if (trueTrends < 1)
    trendsDisplayContainer.innerHTML = '';
});

(2) meld.around(__sco.osr, 'showTrendsContent')

meld.around(__sco.osr, 'showTrendsContent', function(methodCall) {
  trueTrends = methodCall.args[0][0].BasketCount;
  var container = _scs('.trendsShow-sc:first');
  var copy = ' looking at this product';
  // importantly, you have to modify the html
  // after you proceed with the original method call
  methodCall.proceed();
  if (trueTrends === 1)
    container.innerHTML = '1 person is' + copy; 
  else if (trueTrends > 1)
    container.innerHTML = trueTrends + ' people are' + copy;
  else if (trueTrends < 1)
    container.innerHTML = '';
});

${BasketCount} is confusing, unnecessary, and doesn't even do anything if melds are used properly

Because the script is using melds to capture the api response that provides us with BasketCount and setting the html directly, there is no reason to use the confusing ${BasketCount} in the html at all. This is still perfectly valid html that conforms to the script's api:

<div id="wrapper-sc">
  <!-- no ${BasketCount} as it is really unnecessary if you are storing trends in a closure -->
  <div class="trendsHide-sc"></div>
  <div class="trendsShow-sc"></div>
</div>

However, even if .trendsHide-sc is empty, it must be present in the html. The script expects that element to be present.

For cases, I think the cleanest api to use is one with empty .trendsHide-sc and .trendsShow-sc elements. Let the script do all the work and give design folks the most straightforward api to work with.