This guide provides instructions for installing, configuring, and customizing the HubBox module for your Magento 2 store. This module integrates HubBox pickup point selection directly into your Magento checkout process, offering your customers convenient delivery alternatives.
Version Check: Please inform the HubBox team of your exact Magento 2 version (e.g., 2.4.5-p1) to ensure you receive the correct and compatible module version.
composer.developers.hub-box.com
).1.2.3
).Config ID
.Follow these steps to install the HubBox module using Composer. It is highly recommended to perform these steps on a staging/development environment first and back up your site and database before proceeding.
bin/magento maintenance:enable
Add the HubBox Composer repository to your project's root composer.json
file if it's not already present.
composer.json
file.repositories
section (or add one if it doesn't exist).{
"type": "composer",
"url": "[https://composer.developers.hub-box.com](https://composer.developers.hub-box.com)"
}
repositories
section might look similar to this afterwards:"repositories": [
{
"type": "composer",
"url": "[https://repo.magento.com/](https://repo.magento.com/)"
},
{
"type": "composer",
"url": "[https://composer.developers.hub-box.com](https://composer.developers.hub-box.com)"
}
// Potentially other repositories...
]
composer.json
file.USERNAME
and PASSWORD
with the credentials provided by HubBox:composer config http-basic.composer.developers.hub-box.com USERNAME PASSWORD
composer require
command, replacing x.y.z
with the specific version number provided by HubBox:COMPOSER_MEMORY_LIMIT=-1 composer require hub-box/click-and-collect:x.y.z
(Setting COMPOSER_MEMORY_LIMIT=-1
helps prevent memory issues on some systems)../composer.json has been updated
Running composer update hub-box/click-and-collect
Loading composer repositories with package information
Authentication required (composer.developers.hub-box.com):
Username: YOUR_HUBBOX_COMPOSER_USERNAME
Password: YOUR_HUBBOX_COMPOSER_PASSWORD
bin/magento module:enable HubBox_ClickAndCollect
bin/magento setup:upgrade
bin/magento setup:di:compile
en_US fr_FR
with the specific locales used on your store:bin/magento setup:static-content:deploy en_US fr_FR -f
bin/magento cache:clean
bin/magento cache:flush
bin/magento maintenance:disable
The HubBox module should now be installed and enabled.
Configure the module settings via the Magento Admin Panel.
Log in to your Magento Admin Panel.
Navigate to Stores > Configuration.
In the left panel, expand HubBox and select Settings.
Configure the options according to the details below. Obtain API credentials and the Config ID from your HubBox Integrations contact.
Configuration Field | Scope | Description | Source | Default |
---|---|---|---|---|
Enabled | Website | Set to Yes to enable the HubBox module functionality on the frontend checkout for the selected scope. |
N/A | No |
Inject Carrier Extra Data | Website | Set to Yes if using carriers (like UPS API, DPD) that require HubBox to inject special codes into the address fields for manifesting. (Usually Yes ). |
N/A | Yes |
Environment | Website | Select Sandbox for testing/development environments or Production for your live site. This determines which HubBox API endpoints the module communicates with. |
N/A | Sandbox |
Username | Website | HubBox API Username for authentication. | Provided by HubBox | |
Password | Website | HubBox API Password (or Key) for authentication. | Provided by HubBox | |
Client ID | Website | HubBox API Client ID for authentication. | Provided by HubBox | |
Client Secret | Website | HubBox API Client Secret for authentication. | Provided by HubBox | |
Design | Store View | Selects how the HubBox map widget is displayed: Modal (pops up) or Embed (appears directly inline on the page). |
N/A | Modal |
Config ID | Store View | Your unique HubBox configuration ID. Determines network availability, base widget styling (colors, fonts, map settings), and potentially other features. | Provided by HubBox |
Set the Scope (top-left dropdown) correctly (e.g., specific Website or Store View) before configuring.
Click Save Config.
You may need to flush Magento caches again (bin/magento cache:flush
) after saving configuration.
The HubBox module uses standard Magento mechanisms to add the necessary elements to your checkout.
checkout_index_index.xml
), Blocks, Templates (.phtml), and potentially UI Components/KnockoutJS/JavaScript to inject the HubBox frontend components (delivery choice toggles/buttons, map widget trigger, confirmation display) into the appropriate steps of the checkout flow.view/frontend/layout/checkout_index_index.xml
file, first remove the default HubBox CSS:<?xml version="1.0"?>
<page xmlns:xsi="[http://www.w3.org/2001/XMLSchema-instance](http://www.w3.org/2001/XMLSchema-instance)" layout="1column" xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
<head>
<remove src="HubBox_ClickAndCollect::css/theme/orange.css"/>
<css src="Vendor_YourTheme::css/custom-hubbox-styles.css"/>
</head>
</page>
(Adjust Vendor_YourTheme::css/custom-hubbox-styles.css
to the correct path for your custom CSS file).app/design/frontend/Vendor/YourTheme/web/css/custom-hubbox-styles.css
).::part()
pseudo-element. Target the component tag (e.g., hubbox-local-pickup-toggles
) and the specific part name:/* Example: Style the toggle radio button within the pickup component */
hubbox-local-pickup-toggles::part(radio) {
color: var(--primary-color);
border: 1px solid var(--primary-color);
}
/* Example: Style the title within the home delivery choice component */
hubbox-home-delivery-toggles::part(title) {
font-weight: bold;
font-size: 1.1em;
}
:root
overrides) for easier theming.bin/magento setup:static-content:deploy...
) and clear caches.configId
set in the Magento Admin configuration, which points to a style configuration managed within the HubBox platform.For functionality beyond the standard configuration, Magento's plugin (interceptor) system and dependency injection (di.xml
) are typically used. This requires Magento development expertise.
ConfigProvider
(Simpler): Create an after
plugin on the HubBox\ClickAndCollect\Model\Ui\ConfigProvider::getConfig()
method. In your afterGetConfig
method, inspect the current quote ($subject->getQuote()
), check its items against your eligibility rules (e.g., product attributes like is_pickup_eligible
, category IDs, dimensions), and modify the isClickAndCollectable
value within the $result
array before returning it.<?php
namespace Vendor\Module\Plugin\HubBox\Ui;
use HubBox\ClickAndCollect\Model\Ui\ConfigProvider;
use Magento\Checkout\Model\Session as CheckoutSession;
class ConfigProviderPlugin
{
protected $checkoutSession;
public function __construct(CheckoutSession $checkoutSession) {
$this->checkoutSession = $checkoutSession;
}
public function afterGetConfig(ConfigProvider $subject, array $result): array
{
// Default to module's setting
$isEligible = $result['isClickAndCollectable'] ?? true;
try {
$quote = $this->checkoutSession->getQuote();
if ($quote && $quote->getId()) {
$items = $quote->getAllVisibleItems();
foreach ($items as $item) {
// --- YOUR LOGIC HERE ---
// Example: Check a custom product attribute 'allow_pickup'
$product = $item->getProduct();
if ($product->getData('allow_pickup') === '0') { // Assuming 0 means not allowed
$isEligible = false;
break; // Found one ineligible item, no need to check further
}
// Add other checks (category, dimensions, etc.)
}
}
} catch (\Exception $e) {
// Log error, maybe default to not eligible on error?
$isEligible = false;
}
$result['isClickAndCollectable'] = $isEligible;
return $result;
}
}
(Remember to declare the plugin in your module's etc/di.xml
).WidgetConfigInterface
(More Involved): Define a preference
in your module's etc/di.xml
to replace the default implementation of HubBox\ClickAndCollect\Api\WidgetConfigInterface
with your own custom class. Your class must implement the interface and contain the complex eligibility logic, likely by injecting necessary dependencies (like CheckoutSession
) to access quote data.<config xmlns:xsi="[http://www.w3.org/2001/XMLSchema-instance](http://www.w3.org/2001/XMLSchema-instance)" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
<preference for="HubBox\ClickAndCollect\Api\WidgetConfigInterface" type="Vendor\Module\Model\CustomWidgetConfig"/>
</config>
after
Plugin on the collectRates
method of the relevant shipping carrier models (e.g., Magento\Quote\Model\Quote\Address\RateRequest
).Magento\OfflineShipping\Model\Carrier\Flatrate
, Magento\Shipping\Model\Carrier\AbstractCarrierOnline
, specific third-party module carriers).afterCollectRates(\Magento\Shipping\Model\Rate\Result $result)
method:Quote
or Quote\Address
object that you can check, or you might inspect the address fields).$result
object ($result->getAllRates()
).$result
.<?php
namespace Vendor\Module\Plugin\Quote\Address\RateResult;
use Magento\Quote\Model\Quote\Address\RateResult\Method;
use Magento\Checkout\Model\Session as CheckoutSession;
// Potentially use HubBox module helper to check selection status
class MethodPlugin
{
protected $checkoutSession;
// Inject HubBox helper if available
public function __construct(CheckoutSession $checkoutSession /*, HubBoxHelper */) {
$this->checkoutSession = $checkoutSession;
}
// Example targeting a specific rate method - adapt as needed
public function afterCollectRates(
\Magento\Shipping\Model\Rate\Result $subject, // Or specific carrier model
\Magento\Shipping\Model\Rate\Result $result
) {
$quote = $this->checkoutSession->getQuote();
// --- Logic to determine if HubBox pickup is selected for the quote ---
$isHubBoxSelected = false; // Replace with actual check
// e.g., check quote address, or a session flag set by HubBox module
$rates = $result->getAllRates();
$result->reset(); // Clear existing rates
foreach ($rates as $rate) {
$isHomeRate = ($rate->getMethodCode() === 'home_delivery_standard'); // Example check
$isPickupRate = ($rate->getMethodCode() === 'hubbox_pickup'); // Example check
if ($isHubBoxSelected && $isPickupRate) {
$result->append($rate); // Keep pickup rate
} elseif (!$isHubBoxSelected && $isHomeRate) {
$result->append($rate); // Keep home rate
}
// Add logic for other rates...
}
return $result;
}
}
(This is highly conceptual; actual implementation depends heavily on rate codes and how the HubBox module indicates selection status. Declare plugin in di.xml
).
app/design/frontend/Vendor/YourTheme/i18n/en_GB.csv
) in your custom theme or a dedicated translation module.ConfigProvider.php
/ WidgetConfigInterface
. The module likely requests text based on the current store view's locale using the Config ID
. To override default text for a specific language:ConfigProvider.php
(using a plugin as described for eligibility) to inject a translations
object (similar to the Tag documentation examples).Testing on a staging/development environment that mirrors your production setup is essential.
Sandbox
. Ensure API credentials and Config ID are correct for the sandbox.bin/magento module:status HubBox_ClickAndCollect
) and setup scripts ran without error. Check Magento logs (var/log
).hbcc_order
custom table in the database for new entries corresponding to test orders. Verify the stored HubBox data (location ID, name, network) is correct. Check Magento order details in the admin.To access HubBox's UAT guide, visit the Testing Documentation.
setup:upgrade
, setup:di:compile
, setup:static-content:deploy
, cache:flush
).Production
and ensure all API credentials and the configId
are correct for the live environment.bin/magento cache:flush
).hbcc_order
Table)The HubBox module adds a custom database table named hbcc_order
.
collectPointId
, collectPointName
, collectPointNetwork
, and collectPointType
, linked to the corresponding Magento order_id
.
(Caption: Example view of the hbcc_order table structure)
(Caption: HubBox information potentially displayed in Magento Order View)
var/log/system.log
and var/log/exception.log
). Check these logs if you suspect backend issues.etc/events.xml
or code dispatching events) to identify and observe these for advanced custom integrations.For issues during installation, configuration, customization, or troubleshooting the HubBox Magento 2 module, please contact the HubBox Client Support or Integrations team at clientsupport@hub-box.com. Provide your Magento version, HubBox module version, relevant configuration details, and steps to reproduce the problem.