Method of manual rendering of widgets

Description

retailrocket.markup.render() is a method that allows manual control over the rendering of markup blocks on a web page.

In this guide, we will explore how automatic rendering works, why retailrocket.markup.render() is necessary and how to use it.

How does automatic rendering of markup blocks work?

When a page loads, the Retail Rocket main tracking code performs the following steps:

1. Searching for markup blocks:
   Starting from the moment the tracking code is loaded, it scans the page every 100 milliseconds for elements with the data-retailrocket-markup-block attribute. This search continues until the page is fully loaded.
2. Loading layout and recommendations:
   • For each detected block, the code:Retrieves the block's layout based on its ID.
   • Determines the recommendation algorithm specified in the block.
   • Requests recommendations and populates the block with content.
3. Stopping the search:
   After the DOMContentLoaded event (when the HTML is fully loaded and the DOM is built), the tracking code stops searching for new blocks.

🚧

Important

If a markup block appears on the page after DOMContentLoaded, automatic rendering will not process it. This is where retailrocket.markup.render() becomes essential.

Why is retailrocket.markup.render() necessary?

Automatic rendering only handles blocks present on the page before the DOMContentLoaded event. However, modern websites often add blocks dynamically or avoid full page reloads. retailrocket.markup.render() addresses this by allowing manual initialization and display of markup blocks. Key reasons for its use include:

• Dynamic addition of blocks after page load:
  If a block appears after DOMContentLoaded (e.g., in a pop-up form loaded via Ajax), the tracking code will not detect it. Callingretailrocket.markup.render()forces the rendering of such blocks.
• Single page applications (SPAs):
  In SPAs, pages do not reload during navigation, and DOMContentLoaded only triggers once on initial load. For each transition to a new "page," retailrocket.markup.render() must be called to display the blocks.
  updating existing blocks If a block's content needs to be updated (e.g., when the cart state changes), calling retailrocket.markup.render() again allows re-rendering the block with new recommendations.
• Adding blocks based on user actions Blocks may appear not immediately but upon specific actions, such as scrolling, clicking a button, or opening a pop-up. After adding such a block, retailrocket.markup.render() should be called.
• Websites without page reloads If a site does not refresh the page during transitions (e.g., during scrolling or tab switching), automatic rendering will not trigger. In such cases, retailrocket.markup.render() must be called manually after adding blocks.

📘

Note

The method does not return a value (it returnes undefined), which is normal. To confirm that the block has been rendered, visually inspect the page and check if the block has the initialized="true" attribute.

How to use retailrocket.markup.render()?

To use the method correctly, follow these steps:

1. Remove the initialized="true" attribute:
   If the block's container has the initialized="true" attribute, remove it. This attribute indicates that the block has already been rendered, and its presence may prevent re-rendering.
2. Reset the duplicates filter (if necessary):
   If you are updating a block and want to display new recommendations, even if they overlap with previous ones, execute:
   delete retailrocket.modules.duplicates;
3. Call the method:
   retailrocket.markup.render();