📖 Welcome to our comprehensive guide on utilizing FE Lib V3 for front-end customization in Boost AI Search & Discovery. This resource is tailored for developers looking to enhance their eCommerce platforms with advanced customization capabilities.

Customize React components

💡 There are two files that we use for customization, find them in Themes > [Target Theme] > Edit code.

boost-sd-custom.js for customizing React components in JavaScript.
boost-sd-custom.css for customizing your component's layout & style in CSS.

List of components that can be customized

FilterTree category	`FilterTree` `FilterTreeVertical` `RefineByVertical` `FilterTreeHorizontal` `RefineByHorizontal` `FilterOption` `FilterOptionRangeSlider`
Collection Header category	`CollectionHeader` `Breadcrumb` `HeaderDescription` `HeaderImage` `ProductCount` `HeaderTitle` `HeaderMain1` `HeaderMain2` `HeaderMain3` `HeaderMain4`
Toolbar category	`Toolbar` `ProductCount` `Sorting` `ShowLimitList` `ViewAs`
ProductList category	`ProductList` `ProductListPagination` `ProductListPlaceholder` `PaginationButton` `PaginationInfiniteScroll` `PaginationLoadMore` `PaginationPageLink` `PaginationNumber` `PaginationRange` `ProductCount` `ProductItemWidget` `ProductTitle` `ProductPrice` `ProductVendor` `CTAButton` `CartItem` `IntegrationProductRating` `InventoryStatus` `ProductLabel` `ProductLink` `ProductImage` `ProductSwatch` `ProductSwatchOption` `ProductInfo` `IntegrationProductLabel` `IntegrationProductQuickView` `IntegrationProductRating` `IntegrationProductReviewFera` `IntegrationProductWishlist` `ProductImage` `Image` `IntegrationProductWishlist`
Recommendation category	`RecommendationWidget` `Slider` `RecommendationBundle` `ProductLink` `ProductImage`
QuickView category	`QuickView` `Slider` `ProductImage` `Quantity` `ProductLabel` `ProductSwatch` `ProductSwatchOption`
Cart category	`Cart` `CartItem` `Quantity`
Instant Search category	`SearchProductItem` `SearchBar` `SearchInput` `SearchContentResult`
Slider category	`Slider` `SliderSlide` `SliderThumbs` `SliderDots` `SliderPrevButton`
Utils category	`FormatCurrency`
Additional elements	`SearchResultPanels` `SearchResultToolbar`

Define a Component's plugin (Recommended)

To customize a component, use the useComponentPlugin function. This allows you to modify aspects like style, behavior, and rendering. An example to modify a ProductLabel component would be:

Go to Themes > [Target theme] > Edit code > in this file: boost-sd-custom.js, we have:

window.__BoostCustomization__ = (window.__BoostCustomization__ ?? []).concat([
    (componentRegistry) => {
        componentRegistry.useComponentPlugin('ProductLabel', {
            name: 'Modify Product Label',
            enabled: true,
            apply: () => ({
                className: 'extra-class',
                props: (props) => {
                    props.label += ' Boost'; // Modify props
                    return props;
                },
                style: {
                    color: 'red', // Modify styles
                },
                render(elementModel, currentRenderElement) {
                    return currentRenderElement;
                },
                beforeRender(element) {},
                afterRender(element) {},
                // Commonly used for customization
            }),
        });
    }
]);

⚠️ To customize the appearance of an element using CSS, please insert your custom CSS code into the boost-sd-custom.css file. For consistency and maintainability, we recommend refraining from altering the component's styles via JavaScript when feasible.

Use getHelpers to access Exported Internal Component methods (Not Recommended)

To retrieve internal methods exported within a component, getHelpers can be utilized, although this approach is generally not recommended for basic use cases. Here's an example of how to apply this in the context of a ProductLabel component:

Go to Themes > [Target theme] > Edit code > in this file: boost-sd-custom.js, we have:

window.__BoostCustomization__ = (window.__BoostCustomization__ ?? []).concat([
    (componentRegistry) => {
        componentRegistry.useComponentPlugin('ProductLabel', {
            name: 'Use Method Product Label',
            enabled: true,
            apply: () => ({
                afterRender(element) {
                    const helpers = element.getHelpers();
                },
            }),
        });
    }
]);

This snippet demonstrates the application of getHelpers post-render in a component plugin, enabling the use of internal methods for more advanced customization.

Retrieve a Parent Element of a Component (Advanced Use Recommended)

For advanced customization, you can use the getParentElmByPath function to access the parent element of a specific component. While this method offers deeper customization, it's generally recommended for more experienced developers. Here's how to apply it within a ProductLabel component:

Go to Themes > [Target theme] > Edit code > in this file: boost-sd-custom.js, we have:

window.__BoostCustomization__ = (window.__BoostCustomization__ ?? []).concat([
    (componentRegistry) => {
        componentRegistry.useComponentPlugin('ProductLabel', {
            name: 'Modify Product Label',
            enabled: true,
            apply: () => ({
                afterRender(element) {
                    // Get ProductItem element - the parent of ProductLabel element
                    const parent = componentRegistry.getParentElmByPath(element, 'ProductItem.ProductLink.ProductImage');
                },
            }),
        });
    }
]);

Retrieve the Nearest Parent Element of a Component (Advanced Use Recommended)

To enhance customization capabilities, developers can use the getParentElmNearest function to access the closest parent element of a given component. This method is especially useful for complex customizations and is recommended for experienced users. Here's an example of how to implement this within the ProductLabel component:

Go to Themes > [Target theme] > Edit code > in this file: boost-sd-custom.js, we have:

window.__BoostCustomization__ = (window.__BoostCustomization__ ?? []).concat([
    (componentRegistry) => {
        componentRegistry.useComponentPlugin('ProductLabel', {
            name: 'Modify Product Label',
            enabled: true,
            apply: () => ({
                afterRender(element) {
                    // Get the nearest parent ProductItem element
                    const parent = componentRegistry.getNearestParentElm(element, 'ProductItem');
                },
            }),
        });
    }
]);

Enable Debug Mode for Component Analysis

To facilitate troubleshooting and enhance the development process, the setComponentDebug function can be employed to activate the debug mode for a specific component. This feature is invaluable for developers seeking to diagnose and resolve issues more efficiently. Here's how to enable debug mode for the ProductLabel component:

Go to Themes > [Target theme] > Edit code > in this file: boost-sd-custom.js, we have:

componentRegistry.setComponentDebug('ProductLabel', true);

This command activates debug mode for the 'ProductLabel' component, providing detailed insights and information useful for debugging.

Implement Custom Logic in Module Plugins

Customize the behavior of various modules in your application by defining a module plugin. The useModulePlugin function in componentRegistry allows you to add custom logic to module operations. Here's an example of customizing the FilterAPI module:

Go to Themes > [Target theme] > Edit code > in this file: boost-sd-custom.js, we have:

window.__BoostCustomization__ = (window.__BoostCustomization__ ?? []).concat([
    (componentRegistry) => {
        componentRegistry.useModulePlugin('FilterAPI', {
            name: 'FilterAPI plugin',
            apply(builder) {
                builder.on('beforeMethodCall', 'get', (payload) => {
                    // Example: modify request params
                    payload.args[1].limit = 30;
                });
                builder.on('methodPending', 'get', (payload) => {
                    return payload;
                });
                builder.on('methodFulfilled', 'get', (payload) => {
                    // Example: add extra response
                    payload.extraRes = 'Boost';
                    return payload;
                });
                builder.on('methodReject', 'get', (payload) => {
                    return payload;
                });
            }
        });
    }
]);

💡 // // Example: modify request params

payload.args[1].limit = 30; : example for customization that you can add

This script demonstrates how to modify the 'get' method behavior in the FilterAPI module. You can apply similar customizations to other modules:

1. FilterAPI

get use for filter-related API calls.

2. SearchAPI

get for Instant Search Widget API calls.
searchInCollection for Search Page or in-collection searches on collection pages API calls.

3. RecommendationAPI

get for recommendation-related API calls.

4. CartAPI

addToCart for API to add a single product to the cart.
addMultiProductToCart for API to adding multiple products.
getCartItems for API to retrieve cart items.
clearCart for API to clear the cart.
changeCartItem for API to modify cart items.

5. CollectionAPI

get to call Collection Header API to fetch the collection's info.

For dev - Advanced Definition of Theme Setup (App Lib V2)

For dev - How to troubleshoot Analytics in Boost Recommendation

For Dev - Product List Customization (App Lib V2)

For dev - App Lib V2 Customization

For dev - App Lib V2 Overview

For Dev - App Customization (App Lib V3)