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

Version Support: HubBox supports Magento 2 versions in line with Adobe's Software Lifecycle Policy.

The HubBox Extension is only suitable if clients are not using custom applications like Hyva or Amasty in the checkout, as these can conflict. In such cases, Tag or SDK should be used.

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).
- HubBox API Credentials (Username, Password/API Key, Client ID, Client Secret) for configuration after installation.
- Your unique HubBox configId.

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"
}

The repositories section might look similar to this afterwards:

"repositories": [
    {
        "type": "composer",
        "url": "https://repo.magento.com/"
    },
    {
        "type": "composer",
        "url": "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. (Setting COMPOSER_MEMORY_LIMIT=-1 helps prevent memory issues on some systems).
```
COMPOSER_MEMORY_LIMIT=-1 composer require hub-box/click-and-collect:x.y.z
```

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.

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

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

Frontend Integration & Customization

The HubBox module uses standard Magento mechanisms to add the necessary elements to your checkout. 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.

The visible UI elements are rendered using HubBox's 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 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

In certain cases, you may wish to prevent the HubBox option from showing if the cart contains ineligible items. See Product Eligibility documentation.

Below are two common approaches to handle product eligibility.

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

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

To implement a shipping rate filter, you will need to create an after Plugin on the collectRates method of the relevant shipping carrier models (e.g., Magento\Quote\Model\Quote\Address\RateRequest).

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

In your afterCollectRates(\Magento\Shipping\Model\Rate\Result $result) method:

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).
Iterate through the rates in the $result object ($result->getAllRates()).
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).
If Home Delivery is selected, remove rates intended only for HubBox pickup.
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.

Testing

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

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. 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. This data can be useful for reporting, backend processes identifying pickup orders, or potentially passing information to fulfillment systems.

magento-order-table Example view of the hbcc_order table structure

magento-order-example HubBox information potentially displayed in Magento Order View

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.