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:


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

  1. (Recommended) Put your store into maintenance mode:
    bin/magento maintenance:enable
    
  2. 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.

  1. Open your composer.json file.
  2. Locate the repositories section (or add one if it doesn't exist).
  3. Add the HubBox repository:
    {
        "type": "composer",
        "url": "[https://composer.developers.hub-box.com](https://composer.developers.hub-box.com)"
    }
    
  4. 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...
    ]
    
  5. Save the composer.json file.
  6. (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

  1. Navigate to your Magento project's root directory in your terminal/SSH client.
  2. 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).
  3. 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
    
  4. Wait for Composer to download the module and its dependencies.

Step 4: Enable Module & Run Setup

  1. Enable the module within Magento:
    bin/magento module:enable HubBox_ClickAndCollect
    
  2. Run the Magento setup upgrade process to install the module's schema and data:
    bin/magento setup:upgrade
    

Step 5: Compile & Deploy Static Content

  1. (If in Production Mode) Compile Magento's code:
    bin/magento setup:di:compile
    
  2. 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

  1. Clean and flush the Magento cache:
    bin/magento cache:clean
    bin/magento cache:flush
    

Step 7: Disable Maintenance Mode

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

  1. Log in to your Magento Admin Panel.

  2. Navigate to Stores > Configuration.

  3. In the left panel, expand HubBox and select Settings.

  4. 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
  5. Set the Scope (top-left dropdown) correctly (e.g., specific Website or Store View) before configuring.

  6. Click Save Config.

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

Styling

  1. Default Styles: The module includes default CSS to provide basic styling.
  2. 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)

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

Shipping Rate Filtering

Language & Translations

BOPIS / Own Store Integration

Testing

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

  1. Environment Configuration: In Stores > Configuration > HubBox > Settings, set Environment to Sandbox. Ensure API credentials and Config ID are correct for the sandbox.
  2. 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

  1. Ensure thorough testing on your staging environment is complete.
  2. Deploy the tested codebase (including the enabled HubBox module) to your production environment.
  3. Run necessary Magento deployment commands on production (setup:upgrade, setup:di:compile, setup:static-content:deploy, cache:flush).
  4. 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.
  5. Save the configuration and flush Magento caches (bin/magento cache:flush).
  6. Perform final smoke tests on the live site.

Data Storage (hbcc_order Table)

The HubBox module adds a custom database table named hbcc_order.

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

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.