Magento Extension Installation Guide

This document describes a step-by-step install/update/uninstall guide for the Bloomreach Connector for Magento extension. For configuration and usage, refer to the User Guide.

Installation Instructions

Requirement: This extension has been tested with Magento 2.3.0, 2.3.7, & 2.4.0.

• The minimum PHP requirement is: PHP 7.4
• Magento 2.4.0 must be installed and running before installing this extension

Ensure your Magento instance is up to date with the latest software versions for your installation. To see what software versions & extensions are recommended for each version of Magento, click on this link.

Installation can be done in one of two ways:

Method 1: Manually Upload the Extension

1. Check to see if your Magento instance has an app/code directory structure. If not, then create the code subfolder manually.
2. Create 2 more directories with this path: “Bloomreach/Connector.” The final path should look like: app/code/Bloomreach/Connector
3. Extract the downloaded zip folder and move the content of the extracted folder to this path: app/code/Bloomreach/Connector
4. These same steps also apply for ftp upload.

Method 2: Install using Composer

1. If accessing the Extension from the Magento Marketplace, you can run the Composer require command, and press Enter:

composer require bloomreach/bloomreach-connector-magento

2. If the Composer command returns any errors, then you may need to check your php version and Magento version. To see supported versions, refer to the composer.json file included in this extension.

Initialize the Extension:

After completing either method 1 or 2, change directory to . If your Magento instance is in Production mode, then you will need to set your store to maintenance mode.

php bin/magento main:ena

To enable the Bloomreach Connector extension:

php bin/magento module:enable Bloomreach_Connector

Now, run the setup upgrade and compilation command from your Magento root directory:

php bin/magento setup:upgrade && php bin/magento setup:di:compile

If your Magento instance is in Production mode, then you may need to run static content deployment as well. If you have more than one locale enabled in your store, you may also need to run this process for other locales. You can add multiple locales by using this naming convention (for example, en_US de_DE nl_NL)

php bin/magento setup:static-content:deploy en_US

If maintenance mode was enabled earlier, then you can now disable it:

php bin/magento main:dis

Then, clear cache to see the changes.

php bin/magento cache:flush

Now the installation is complete! You can follow the User Guide to configure and use this extension.

Updating the SDK/Extension

The SDK (a set of JS files) is a fundamental part of this extension. The SDK includes a pre-defined template for making API calls to Bloomreach, as well as a template UI that gets injected to your Magento store. If you would like to customize the features of the SDK, or add functionally not included in the base SDK, then follow one of these methods:

Method 1: Upgrade the Extension to the latest version

If you want to upgrade to have the latest SDK version with fixes and new features, you can do any of the following to update your extension:

1. To upgrade the extension, you can download the latest version of the extension from the marketplace and follow above installation methods if you had installed with Manual installation.
2. If you installed through Composer, then you can run the following command to upgrade to the latest version:

composer update bloomreach/bloomreach-connector-magento

After installation, run the following commands. If your Magento instance is in Production mode, then you will need to set your store to maintenance mode.

php bin/magento main:ena

Now, run the setup upgrade and compilation command from your Magento root directory:

php bin/magento setup:upgrade && php bin/magento setup:di:compile

If your Magento instance is in Production mode, then you may need to run static content deployment as well. If you have more than one locale enabled in your store, you may also need to run this process for other locales. You can add multiple locales by using this naming convention (for example, en_US de_DE nl_NL)

php bin/magento setup:static-content:deploy en_US

If maintenance mode was enabled earlier, then you can now disable it:

php bin/magento main:dis

Then, clear cache to see the changes.

php bin/magento cache:flush

Method 2: Update/Customize SDK JS

Developers are allowed to add functionality to the base SDK, but not directly in the original file.

All modules are available under this window variable: window.BloomreachModules

You can add or customize SDK JS by creating a new JS file and using the JS class method override. Here is an example of how you could override the SDK JS if you wanted to customize some elements related to autosuggest:

📘

All SDK modules are implemented using Javascript classes, so you can easily add/modify methods or variables as needed.

1. First, create a separate JS file
2. Then, override the path of autosuggest.js in requirejs-config-js to reference your new file.
3. In the new file, include autosuggest.js sdk path inside a require/define section.
4. Then, you can write JS logic to override a method. Here’s an example: if you need to override the load method, your new customized load method will now be called.

window.BloomreachModules.autosuggest.load = function(){
//function body + customization here
}

5. Or if you want to create a new method then you can follow this pattern:

window.BloomreachModules.autosuggest.customMethod = function(){
//function body here
}

6. You can also change the existing template, which is available under the template variable.

window.BloomreachModules.autosuggest.template = “Copy the original template from the Autosuggest SDK and add your customization here”

7. Now, because of the override from Step 2, when the autosuggest is called from the front end, your new JS will be loaded.
8. After you complete your edits, you need to run the following commands to deploy:

If your Magento instance is in Production mode, then you will need to set your store to maintenance mode.

php bin/magento main:ena

Now, run the setup upgrade and compilation command from your Magento root directory:

php bin/magento setup:upgrade && php bin/magento setup:di:compile

If your Magento instance is in Production mode, then you may need to run static content deployment as well. If you have more than one locale enabled in your store, you may also need to run this process for other locales. You can add multiple locales by using this naming convention (for example, en_US de_DE nl_NL)

php bin/magento setup:static-content:deploy en_US

If maintenance mode was enabled earlier, then you can now disable it:

php bin/magento main:dis

Then, clear cache to see the changes.

php bin/magento cache:flush

If you run console.log, you can see all available modules under the window variable. Then you can use JS prototyping to customize the Javascript.

Uninstall

Depending on the installation method you chose above, you can uninstall the Bloomreach Connector extension in two ways:

• Manual Uninstall: If the extensions files are located within app/code/Bloomreach, then the extensions were installed manually and you need to uninstall the extensions files manually.
• Composer: If the extension files are located within vendor/bloomreach/, then the extension was installed using the Composer and you need to use the Composer to uninstall.

Manual Uninstall

To uninstall manually, you can login to SSH and run the following commands.

1. To disable the extension:

php bin/magento module:disable Bloomreach_Connector

2. Remove files from app/code/Bloomreach:

rm -rf app/code/Bloomreach

3. Run the following commands:

If your Magento instance is in Production mode, then you will need to set your store to maintenance mode.

php bin/magento main:ena

Now, run the setup upgrade and compilation command from your Magento root directory:

php bin/magento setup:upgrade && php bin/magento setup:di:compile

If your Magento instance is in Production mode, then you may need to run static content deployment as well. If you have more than one locale enabled in your store, you may also need to run this process for other locales. You can add multiple locales by using this naming convention (for example, en_US de_DE nl_NL)

php bin/magento setup:static-content:deploy en_US

If maintenance mode was enabled earlier, then you can now disable it:

php bin/magento main:dis

Then, clear cache to see the changes.

php bin/magento cache:flush

Uninstall via Composer

To uninstall using Composer, you can login to SSH and run the following commands.

1. Enable Maintenance mode first

php bin/magento main:ena

2. Disable Extension

php bin/magento module:disable Bloomreach_Connector

3. To remove files related to the extensions, run the following command

php bin/magento module:uninstall -r Bloomreach_Connector

4. To remove modules from Composer and clean up the database and code, run the following commands after modules have been successfully uninstalled:

composer remove bloomreach/bloomreach-connector-magento

5. Run the following commands:

If your Magento instance is in Production mode, then you will need to set your store to maintenance mode.

php bin/magento main:ena

Now, run the setup upgrade and compilation command from your Magento root directory:

php bin/magento setup:upgrade && php bin/magento setup:di:compile

If your Magento instance is in Production mode, then you may need to run static content deployment as well. If you have more than one locale enabled in your store, you may also need to run this process for other locales. You can add multiple locales by using this naming convention (for example, en_US de_DE nl_NL)

php bin/magento setup:static-content:deploy en_US

If maintenance mode was enabled earlier, then you can now disable it:

php bin/magento main:dis

Then, clear cache to see the changes.

php bin/magento cache:flush