HubBox Module for Magento 2

Introduction

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.

Compatibility: HubBox maintains versions of the module compatible with various Magento 2 releases.

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.

Prerequisites:

A functioning Magento 2 instance.
SSH/CLI access to your Magento server environment.
Composer installed and configured for your Magento project.
Magento Admin Panel access with appropriate permissions.
Credentials & Version: You must obtain the following from your HubBox Integrations Manager:
- Composer Authentication Credentials (Username and Password for composer.developers.hub-box.com).
- The specific HubBox module version number to install (e.g., 1.2.3).
- HubBox API Credentials (Username, Password/API Key, Client ID, Client Secret) for configuration after installation.
- Your unique HubBox Config ID.

Installation

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.

Step 1: Preparation

(Recommended) Put your store into maintenance mode:
```
bin/magento maintenance:enable
```
Ensure you have the HubBox Composer credentials and the correct module version number from HubBox.

Step 2: Configure Composer Repository

Add the HubBox Composer repository to your project's root composer.json file if it's not already present.

Open your composer.json file.
Locate the repositories section (or add one if it doesn't exist).

Add the HubBox repository:

{
    "type": "composer",
    "url": "[https://composer.developers.hub-box.com](https://composer.developers.hub-box.com)"
}

The 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...
]

Save the composer.json file.
(Optional but Recommended) Configure Composer authentication for the HubBox repository using your provided credentials. This avoids interactive prompts later. Run the following command, replacing USERNAME and PASSWORD with the credentials provided by HubBox:
```
composer config http-basic.composer.developers.hub-box.com USERNAME PASSWORD
```

Step 3: Require the HubBox Module

Navigate to your Magento project's root directory in your terminal/SSH client.
Run the 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).

If you didn't configure authentication in Step 2, Composer will prompt you for the HubBox repository username and password. Enter the credentials provided by HubBox.

./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

Wait for Composer to download the module and its dependencies.

Step 4: Enable Module & Run Setup

Enable the module within Magento:

bin/magento module:enable HubBox_ClickAndCollect

Run the Magento setup upgrade process to install the module's schema and data:
```
bin/magento setup:upgrade
```

Step 5: Compile & Deploy Static Content

(If in Production Mode) Compile Magento's code:
```
bin/magento setup:di:compile
```
Deploy static view files. Replace en_US fr_FR with the specific locales used on your store:
```
bin/magento setup:static-content:deploy en_US fr_FR -f
```

Step 6: Clear Cache

Clean and flush the Magento cache:

bin/magento cache:clean
bin/magento cache:flush

Step 7: Disable Maintenance Mode

Bring your store back online:
```
bin/magento maintenance:disable
```

The HubBox module should now be installed and enabled.

Configuration

Configure the module settings via the Magento Admin Panel.

Step 8: Configure in Admin

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.

Frontend Integration & Customization

The HubBox module uses standard Magento mechanisms to add the necessary elements to your checkout.

How it Works: The module utilizes Magento's Layout XML (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.
Web Components: The visible UI elements are often rendered using HubBox's framework-agnostic Web Components.

Styling

Default Styles: The module includes default CSS to provide basic styling.
Customization (Recommended Method):
- Create your own custom Magento theme or a small custom module.
- In your theme/module's 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).
- Create your custom CSS file (e.g., app/design/frontend/Vendor/YourTheme/web/css/custom-hubbox-styles.css).
- In your custom CSS, style the HubBox Web Components using the 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;
}
```
- Refer to the general HubBox Components Documentation for details on available parts and CSS variables (:root overrides) for easier theming.
- After adding/changing CSS, deploy static content (bin/magento setup:static-content:deploy...) and clear caches.

Styling Caveats (within Widget)

The HubBox Widget (the map and location list UI, whether in a modal or embedded) typically runs inside an iframe.
This means CSS added via Magento Layout XML primarily styles the launch experience elements (toggles/buttons rendered directly on the page) and the container around the iframe/modal.
The internal appearance of the map widget (map pins, colors, list styles within the iframe) is mainly controlled by the configId set in the Magento Admin configuration, which points to a style configuration managed within the HubBox platform.
For more details on configurations within the Widget, see the Widget Configuration documentation.

Advanced Customization & Features

For functionality beyond the standard configuration, Magento's plugin (interceptor) system and dependency injection (di.xml) are typically used. This requires Magento development expertise.

Product Eligibility Filtering

Purpose: Prevent the HubBox option from showing if the cart contains ineligible items. See Product Eligibility documentation.

Magento Implementation: Requires custom code. Two common approaches:

Plugin on 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).

DI Preference for 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>
```

Shipping Rate Filtering

Purpose: Show/hide Magento shipping methods based on whether Home Delivery or Pickup is selected. See Shipping Rate Filtering documentation.

Magento Implementation (Recommended): Create an after Plugin on the collectRates method of the relevant shipping carrier models (e.g., Magento\Quote\Model\Quote\Address\RateRequest).

Target: You might need plugins for multiple carrier models depending on which rates you need to filter (e.g., Magento\OfflineShipping\Model\Carrier\Flatrate, Magento\Shipping\Model\Carrier\AbstractCarrierOnline, specific third-party module carriers).
Logic: In your afterCollectRates(\Magento\Shipping\Model\Rate\Result $result) method:
1. Determine if the current quote's shipping address represents a HubBox pickup selection. (The HubBox module might add a flag or specific data to the Quote or Quote\Address object that you can check, or you might inspect the address fields).
2. Iterate through the rates in the $result object ($result->getAllRates()).
3. If HubBox is selected, remove rates intended only for home delivery (e.g., based on method code or a custom attribute you add to Shipping Methods via XML extension).
4. If Home Delivery is selected, remove rates intended only for HubBox pickup.
5. Return the modified $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).

Language & Translations

Module Strings: Translate text strings added by the HubBox module itself (e.g., admin configuration labels, potentially some frontend labels added via PHTML) using Magento's standard translation mechanism. Add translations to CSV files (e.g., app/design/frontend/Vendor/YourTheme/i18n/en_GB.csv) in your custom theme or a dedicated translation module.
Web Component Text: Text inside the interactive HubBox UI elements (toggles, map widget, confirmation) is controlled by configuration passed from the backend via the 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:
1. You may need to customize the data returned by ConfigProvider.php (using a plugin as described for eligibility) to inject a translations object (similar to the Tag documentation examples).
2. Consult HubBox documentation or support for the specific mechanism provided by the Magento module version you are using for overriding web component text.

BOPIS / Own Store Integration

Displaying your own physical stores requires additional setup, including synchronizing your Magento store location data (Stores > Inventory > Sources/Stocks, or custom implementation) with HubBox. This typically requires specific configuration within HubBox and potentially custom development or professional services. Please contact your HubBox representative to discuss BOPIS requirements and visit the BOPIS documentation

Testing

Testing on a staging/development environment that mirrors your production setup is essential.

Environment Configuration: In Stores > Configuration > HubBox > Settings, set Environment to Sandbox. Ensure API credentials and Config ID are correct for the sandbox.
Verification Checklist:
- Installation: Confirm module is enabled (bin/magento module:status HubBox_ClickAndCollect) and setup scripts ran without error. Check Magento logs (var/log).
- Admin Config: Verify settings save correctly and are applied based on scope.
- Checkout UI: Does the HubBox UI appear correctly on the shipping step (desktop & mobile)? Does styling match?
- Functionality: Can you search/select locations? Does the map work? Does the Magento shipping address form populate correctly after selection?
- Filtering: Test product eligibility and shipping rate filtering logic thoroughly with various cart combinations.
- Place Test Orders: Complete orders using HubBox pickup.
- Order Data: Check the 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.
- Console Errors: Monitor browser console for JavaScript errors.
- Compatibility: Test with various customer groups, other checkout modules, and payment methods.
- Cross-Browser: Test in major browsers.

To access HubBox's UAT guide, visit the Testing Documentation.

Going Live

Ensure thorough testing on your staging environment is complete.
Deploy the tested codebase (including the enabled HubBox module) to your production environment.
Run necessary Magento deployment commands on production (setup:upgrade, setup:di:compile, setup:static-content:deploy, cache:flush).
In the production Magento Admin Panel (Stores > Configuration > HubBox > Settings), change the Environment to Production and ensure all API credentials and the configId are correct for the live environment.
Save the configuration and flush Magento caches (bin/magento cache:flush).
Perform final smoke tests on the live site.

Data Storage (`hbcc_order` Table)

The HubBox module adds a custom database table named hbcc_order.

Purpose: This table stores specific information related to the HubBox pickup choice for each relevant Magento order. It typically includes non-personally identifiable HubBox data such as the chosen collectPointId, collectPointName, collectPointNetwork, and collectPointType, linked to the corresponding Magento order_id.
Usage: This data can be useful for reporting, backend processes identifying pickup orders, or potentially passing information to fulfillment systems.

magento-order-table (Caption: Example view of the hbcc_order table structure)

magento-order-example (Caption: HubBox information potentially displayed in Magento Order View)

Errors & Events

Frontend Errors: JavaScript errors related to the HubBox Web Components or module interactions will appear in the browser's Developer Console.
Backend Errors: PHP errors or exceptions generated by the HubBox module will be logged in Magento's standard log files (typically var/log/system.log and var/log/exception.log). Check these logs if you suspect backend issues.
Magento Events: Experienced Magento developers can utilize Magento's event/observer system. The HubBox module may dispatch custom events at certain points (e.g., after a location is selected). Developers can inspect the module's code (etc/events.xml or code dispatching events) to identify and observe these for advanced custom integrations.

Support

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.