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

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, customizationCompatibility)		Creates an instance of RecommendationWidgetController.

Properties

Property	Modifiers	Type	Description
appService	`protected`	AppService
customizationCompatibility	`protected`	CustomizationCompatibility
domHelpers	`protected`	DomHelper
MOBILE_BREAKPOINT	`protected` `readonly`	number
props?		Signal<RecommendationWidgetControllerProps>	(Optional) Reactive signal containing the widget's initialization properties. This signal is populated when the widget connects via the `connect()` method and provides reactive access to the widget ID and other initialization props. Useful for accessing widget configuration in extended methods.
recommendationService	`protected`	RecommendationService
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)

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.
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.
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.
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.
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.
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.
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.
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.
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.