Introducing JSv2 Theme

Harshdeep Gujjar

Modified on: Mon, 30 Sep, 2024 at 3:20 PM

This guide is specific to Klevu module versions 2.x and 3.x. It is not required for version 4.x.

Klevu is pleased to announce the latest version of our JavaScript Theme, powered by Klevu JS Library, is now available as part of our official Magento extension.

If you’re performing a new installation of the Klevu extension onto a Magento instance, chances are it’s already enabled by default. Navigate to Magento Admin > Stores > Configuration > Klevu Search > Developer Settings where you will find the following setting:

If the selection here is “JSv2” then you are already using our latest theme. If it is “JSv1” then you are still using the legacy theme. If you’re already up and running with Klevu with everything looking how you expect, you should not change this value. However, if you are starting a new project and would like more control over your Klevu theme, you may wish to give the latest theme a try.

Any customisations made in JSv1 or JSv2 are not transferrable, so you would need to redevelop any changes for the respective theme. Therefore please use this setting with caution.

All you need to do is:

Change this value to either JSv1 or JSv2 as required for the current store.
Select Klevu JS Theme for Search (and Category pages if applicable).
Flush your cache.

The Klevu extension will take care of the rest and serve quick search, search results page, and category pages with the theme you selected.

FAQs

I upgraded the Magento module but my site is still using the legacy theme

While the new theme is both stable and an improvement on the legacy version, existing installations will not switch to the new theme automatically to prevent any unexpected side effects. If you have previously installed the module at version 2.4.x or lower (even if you have subsequently removed it), you will remain on the legacy theme until you explicitly change the setting in your Magento admin panel.
This applies even if you have not yet connected your store with the Klevu service.

How do I switch between theme versions?

Log into your Magento admin panel and navigate to Stores > Settings > Configuration > Klevu > Search Configuration > Developer Settings
Change the field Theme Version to the desired value
Save the configuration
Clear your Magento cache

I have changed the theme version in Magento but it has not updated in my KMC settings

Changing the theme version in Magento after a store has been registered with Klevu will not update the setting in KMC. In order to access some JSv2 specific configuration in Merchant Center, please contact our support team to update this on your account.
Note, new store registrations will use the value set in Magento at time of sign-up. This also applies to additional stores in a multisite where the theme version value has been changed prior to integrating Klevu.

Can I use JSv1 for store A and JSv2 for store B?

Yes. Our Magento store configuration setting for theme version is store scope, so you can change this for each of your stores independently.
This would be a good way to trial the new JS Library before rolling out to established sites, or if you have sites using different Magento themes.

Can I use the new theme for search and the legacy theme for Smart Category Merchandising (or vice versa)?

Not natively.The Theme Version setting in the Klevu integration will affect both Search (quick search and results) and Smart Category Merchandising; there is no built-in support for using different themes for these features.
If you want to do this, you will need to implement the functionality yourself through a custom extension, however it is not recommended as it may cause conflicts.

How do I customise the templates in JSv2 Theme?

The steps to customise templates in Magento is the same as for all other platforms, and you can find instructions within our Klevu JS Theme documentation.
While some changes can be performed with template and layout changes in your theme itself, some functionality (for example, changing initialisation settings) will not available without plugging into the module’s code. To help you get started, we also provided one skeleton module which can be used as your starting point for overriding Klevu settings, templates or API Calls. Please download the extension hereand modify as required.

You should never make changes to the Klevu extension files directly as this will break the upgrade path when updates are released.

My store is on the legacy theme and contains customisations; what will happen to these if I move to Theme V2?

Any customisations made in JSv1 or JSv2 are not transferrable, so you would need to redevelop any changes for the respective theme. You can find a examples of common modifications in the skeleton module here.

I have already integrated Theme V2 manually on my store; do I need to remove these customisations before enabling through the extension?

Yes. The Klevu extension will add all required files and settings in predefined locations in your theme, but it will not detect any JSv2 code added through other means. Including this code twice will cause your site to behave in unexpected ways.

How do I override an API call?

Please refer to the above instructions for overriding a template, which is a very similar process, and also find an example of an API call override within the skeleton module mentioned above.

The search box on my site is not showing suggestions when entering search terms

Potential reasons include the following. If you have ruled out all suggestions below, please check in with our community here.

Incorrect Search Box Selector

If you are using a custom theme, you should confirm that the input selector matches your quick search HTML element. The default pattern will match text type inputs with the name “q” (the standard Magento query parameter); ie input type="text" name="q" ... /> so if you have changed the type or name of the search box then you will need to tell the JSv2 initialisation script the new pattern.
This value is defined under Stores > Settings > Configuration > Klevu > Search Configuration > Developer Settings > Quicksearch Input Selector and must be a valid JavaScript query selector string.

Too Few Characters Entered

By default the quicksearch should show suggestions on focus, even if the input is empty. This is controlled by the minChars initialisation option (set to 0 by default). You should confirm that this value has not been increased through customisations.

Incorrect Cloud Search V2 URL

Confirm that the Cloud Search V2 URL value under Stores > Settings > Configuration > Klevu > Search Configuration > General Settings corresponds with the existing Cloud Search URL in the same section. Note: you will need to switch to the relevant store scope to see these settings

The Cloud Search V2 URL should be the same as the Cloud Search URL, only with “v2” at the end of the subdomain. For example
Cloud Search URL: eucs123.ksearchnet.com
Cloud Search V2 URL: eucs123v2.ksearchnet.com

If the Cloud Search V2 URL value does follow this pattern (or is empty), you can delete the value from the field and click Save Config to force the application to regenerate it. Then, clear the cache and the correct value will be populated to the JavaScript initialization configuration on the frontend.

If you using an old version of Magento (< 2.3) and have already integrated a store with Klevu, the Cloud Search V2 URL will not automatically update when saving the configuration settings. In this case, you will need to access the Store Info section in your KMC account and copy the APIv2 Cloud Search URL value into the relevant field in Magento, save the configuration, and clear your cache.

The Search Results Page is not showing results; loading image does not disappear

Potential reasons include the following. If you have ruled out all suggestions below, please check in with our community here.

Incorrect Cloud Search V2 URL
Confirm that the Cloud Search V2 URL value under Stores > Settings > Configuration > Klevu > Search Configuration > General Settings corresponds with the existing Cloud Search URL in the same section. Note: you will need to switch to the relevant store scope to see these settings

The Cloud Search V2 URL should be the same as the Cloud Search URL, only with “v2” at the end of the subdomain. For example
Cloud Search URL: eucs123.ksearchnet.com
Cloud Search V2 URL: eucs123v2.ksearchnet.com

If the Cloud Search V2 URL value does follow this pattern (or is empty), you can delete the value from the field and click Save Config to force the application to regenerate it. Then, clear the cache and the correct value will be populated to the JavaScript initialization configuration on the frontend.