TURBO for Developers

Home > widget-integration > RecommendationWidgetController

RecommendationWidgetController class

Controller for managing recommendation widget lifecycle, rendering, and carousel functionality.

This controller orchestrates the complete lifecycle of recommendation widgets, from data fetching to rendering and carousel initialization. It provides numerous extension points for Technical Support teams to customize widget behavior for specific shops without modifying core code.

Signature:

export declare class RecommendationWidgetController extends Controller<RecommendationWidgetControllerProps>

Extends: Controller<RecommendationWidgetControllerProps>

Remarks

Key responsibilities include: - Lazy loading widgets when they enter the viewport for performance - Fetching recommendation data from the API - Managing widget templates and rendering - Configuring and initializing Slick carousel for carousel layouts - Handling empty recommendation states

Performance considerations: - Uses IntersectionObserver for viewport detection to avoid unnecessary renders - Lazy loads jQuery and Slick carousel only when carousel layout is needed - Unobserves elements after rendering to prevent memory leaks

Example 1

Extend to customize recommendation fetching with additional filters:

window.boostWidgetIntegration.extend('RecommendationWidgetController', (Base) => {
  return class CustomRecommendationController extends Base {
    protected async fetchRecommendationData(widgetId) {
      const model = await super.fetchRecommendationData(widgetId);
      if (model && this.customer?.tags?.includes('vip')) {
        // Filter products for VIP customers
        model.properties.products = model.properties.products.filter(
          p => p.tags?.includes('vip-eligible')
        );
      }
      return model;
    }
  };
});

Example 2

Extend to customize carousel configuration for specific shops:

window.boostWidgetIntegration.extend('RecommendationWidgetController', (Base) => {
  return class extends Base {
    protected getCarouselConfig(model) {
      const config = super.getCarouselConfig(model);
      // Customize for shop theme
      return {
        ...config,
        autoplay: true,
        autoplaySpeed: 5000,
        dots: false
      };
    }
  };
});

Constructors

Constructor	Modifiers	Description
(constructor)(domHelpers, recommendationService, appService, recommendationBundleHelper, customizationCompatibility, dtoHelper, cartController, quickviewController, quickAddToCartController, productController, slickHelper, tooltipHelper)		Creates an instance of RecommendationWidgetController.

Properties

Property	Modifiers	Type	Description
appService	`protected`	AppService
cartController	`protected`	CartController
clickHandler	`protected` `readonly`	(e: MouseEvent) => void
customizationCompatibility	`protected`	CustomizationCompatibility
domHelpers	`protected`	DomHelper
dtoHelper	`protected`	DTOHelper
MOBILE_BREAKPOINT	`protected` `readonly`	number
openingBundleDropdownIdx	`protected`	Signal<number>
productController	`protected`	ProductController
quickAddToCartController	`protected`	QuickAddToCartController
quickviewController	`protected`	QuickViewController
recommendationBundleHelper	`protected`	RecommendationBundleHelper
recommendationService	`protected`	RecommendationService
resizeHandler	`protected` `readonly`	() => void
scrollHandler	`protected` `readonly`	() => void
slickHelper	`protected`	SlickHelper
state		Signal<RecommendationWidgetControllerState>	Reactive state management for the recommendation widget. Tracks loading status and the current recommendation model. The state is observable and can be monitored for changes during the widget lifecycle.
template?	`protected`	string	(Optional)
tooltipHelper	`protected`	TooltipHelper

Methods

Method	Modifiers	Description
afterWidgetRender()	`protected`	Called after widget rendering is complete. This lifecycle hook is executed after the widget has been fully rendered in the DOM. It triggers app integration for cart buttons, executes legacy customization hooks for backward compatibility, and other interactive elements. Override this method to add post-render logic like analytics tracking, custom event handlers, third-party integrations, or accessibility enhancements.
applyRecommendationBundleEvent(model, container)	`protected`	Attaches all event handlers for the 'bundle' layout (Dropdown, Checkbox, AddToCart, Image Link). Logic moved and refactored from index.js/processRecommendationBundleEvent.
applyRecommendationCarouselEvent(model, container)		Initializes and configures the Slick carousel with event handlers and accessibility features. This method handles the complete carousel setup including: - Initializing Slick carousel with configuration - Setting up RTL (right-to-left) layout if needed - Configuring keyboard navigation with proper tabindex management - Attaching carousel navigation button handlers - Managing focus states for accessibility
attachCarouselButtonHandlers(container, slider)	`protected`	Attaches click event handlers to carousel navigation buttons (Previous/Next). Binds click events to circular navigation buttons based on their aria-label attributes. Override this method to customize button behavior, add additional navigation controls, or implement custom navigation logic.
attachProductInteractionHandlers(widgetElement)	`protected`	Attaches click event handlers for product interactions (add to cart, quick view, select options). This method sets up event delegation for product item clicks within the recommendation widget. Uses the same pattern as filter module for consistency.
attachProductLinkHandlers(container, model)	`protected`	Attaches click event handlers to product links and images for navigation and tracking. Handles both .boost-sd__product-link and .boost-sd__product-image elements. Based on the original implementation logic for consistency.
buildBundleCartPayload(products)	`protected`
buildDropboxStyle(rootPosition)		Builds CSS style string for dropdown positioning. Creates inline styles for absolute positioning of dropdown elements relative to their trigger buttons. Override this method to customize dropdown positioning logic, add viewport edge detection, or implement custom positioning strategies.
buildLegacyContext(widgetElement)	`protected`	Builds a legacy context object for compatibility with product-item helpers. This method creates a minimal Context object required by legacy helper functions. The helper functions will extract additional settings from DOM attributes and global configuration as needed.
calcDropdownPosition()		Calculates and updates the position of open dropdowns based on their trigger elements. Dynamically repositions open dropdown elements when the page is scrolled or resized to maintain proper alignment with their trigger buttons. Override this method to implement custom positioning logic, add animations, or modify responsive behavior.
calcTotalPrice(products)		Calculates the total price of checked products in a bundle. Sums the prices of all selected products in the recommendation bundle. Override this method to apply bundle discounts, tax calculations, or custom pricing logic for specific shops or customer segments.
connect(props, parent)		Initializes the recommendation widget and sets up viewport observation for lazy loading. This is the main entry point for widget initialization. It loads the widget template, sets up an IntersectionObserver to detect when the widget enters the viewport, and triggers rendering only when visible for optimal performance.
destroy()		Cleans up event listeners and resources when the controller is no longer needed. This method should be called when the widget is removed or the component is destroyed to prevent memory leaks.
extractProductIdFromHref(href)	`protected`	Extracts product handle from product URL href.
fetchRecommendationData(widgetId)	`protected`	Fetches recommendation data from the recommendation service. Override this method to add shop-specific data enrichment, modify API calls, add caching strategies, or implement custom fallback logic when recommendations are unavailable.
formatPrice(price)		Formats a price value according to shop settings and theme configuration. Applies shop-specific currency formatting including decimal handling, superscript cents, and currency symbols. Override this method to implement custom price formatting logic, add discounts, or modify display for specific customer segments.
getBundleRawPrice(selectedOption)	`protected`
getCarouselConfig(model)	`protected`	Gets the Slick carousel configuration for desktop view. Configures carousel behavior including slides to show/scroll, navigation arrows, dots, and responsive breakpoints. The configuration respects RTL (right-to-left) layout direction from the document. Override this method to customize carousel behavior for specific shops or add features like autoplay.
getDropdownNodeKey(widgetId)		Generates the CSS selector for dropdown elements. Creates a CSS selector that targets dropdown container elements for variant selection. Override this method to customize dropdown element targeting or modify the selector structure.
getDropdownOpenNodeKey(widgetId)		Generates the CSS selector for open dropdown elements. This method creates a CSS selector that targets dropdown elements in their opened state. Override this method to customize dropdown targeting or add additional CSS classes.
getMobileBreakpoint()	`protected`	Gets the mobile breakpoint value in pixels. The breakpoint determines when the carousel switches from desktop to mobile configuration. Default is 768px. Override this method to customize the mobile breakpoint for shops with specific responsive design requirements.
getMobileCarouselConfig()	`protected`	Gets the Slick carousel configuration for mobile view. Defines mobile-specific carousel behavior when viewport width is below the mobile breakpoint. Override this method to customize mobile carousel experience for specific shops or device requirements.
handleClickOutsideBundleDropdown(e)		Handles click events outside bundle dropdowns to close them. Implements click-outside behavior for dropdown menus to provide intuitive UX. When a click occurs outside the dropdown or its trigger, the dropdown closes. Override this method to customize close behavior or add additional event handling.
handleCloseQuickAddToCart(target)	`protected`	Handles closing the quick add to cart popup. Hides the popup and returns focus to the select option button.
handleEmptyRecommendation(parent, unobserve)	`protected`	Handles the case when recommendation data is empty or has no products. By default, removes the widget element from the DOM and stops observing. Override this method to customize empty state behavior, such as showing a fallback message, displaying alternative content, or tracking empty states.
handleGoToProductDetail(target)	`protected`	Handles navigation to product detail page. Builds product URL with variant and navigates to the product page.
handleWidgetInViewport(widgetId, parent, unobserve)	`protected`	Handles the complete widget lifecycle when it enters the viewport. This method orchestrates the entire widget rendering process: fetching data, handling loading states, managing empty states, rendering the widget, and cleaning up the observer. Override this method to customize the entire widget lifecycle or add custom analytics, logging, or error handling.
loadTemplate()	`protected`	Loads the widget template from the recommendation service. Override this method to customize template loading logic, such as loading shop-specific templates, adding template preprocessing, or implementing template caching strategies.
renderBundleWidget(container)		Renders the bundle widget by processing product variants and initializing interactions. This method handles the complete bundle widget rendering process: 1. Processes products and selects available variants 2. Calculates initial total price and selection state 3. Renders template with processed data 4. Initializes bundle-specific event handlers
renderCarouselWidget(container)		Renders the carousel widget by loading dependencies and initializing the carousel. This method handles the complete carousel rendering process: 1. Lazy loads jQuery library with noConflict mode 2. Lazy loads Slick carousel library 3. Renders widget template with product data 4. Initializes carousel with event handlers
renderWidget(model, parent)	`protected`	Renders the widget based on the model's layout configuration. Currently handles carousel layout rendering. Override this method to add support for custom layouts, modify rendering logic, or add pre/post-render transformations.
trackProductLinkClick(link, model)	`protected`	Tracks product link clicks and handles navigation to product detail page. Stores the selected variant ID in session storage for consistency with old implementation.
updateTotalPriceUI(totalPrice, container)		Updates the total price display in the bundle widget UI. Refreshes the visual display of the total bundle price and updates accessibility attributes. Override this method to customize price display formatting, add additional UI elements, or implement custom accessibility features.

← Back to Library Reference