๐ 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 |
|
Collection Header category |
|
Toolbar category |
|
ProductList category |
|
Recommendation category |
|
QuickView category
|
|
Cart category |
|
Instant Search category |
|
Slider category |
|
Utils category |
|
Additional elements |
|
โ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.
If you have any questions or need further assistance, please do not hesitate to reach out to our dedicated support team at [email protected].