OpenCart Integration

Integrate SearchX into your OpenCart store by modifying three template files.

Overview

The OpenCart integration replaces your default search with SearchX by adding the SDK to your Twig templates. You'll need to modify three files:

1. Footer template — Loads the SDK and initializes it.
2. Search template — Mounts the search bar component.
3. Search results template — Mounts the full search results page.

Step 1: Configure Footer & Initialization

Add the SDK scripts and initialization to your footer template.

File: catalog/view/template/common/footer.twig

<!-- SearchX SDK Dependencies (React 18) -->
<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
<!-- SearchX SDK Core -->
<script src="https://helloworld-pc.github.io/searchx-components/searchx-sdk.umd.js"></script>
<script>
  (function () {
    var storedLang = localStorage.getItem('searchx_lang') || 'en';
    window.SEARCHX_LANG = storedLang;

    function initSearchX() {
      if (!window.SearchXSDK) {
        console.warn('SearchX SDK not loaded yet.');
        return;
      }
      window.SearchXSDK.init({
        app_id: 'YOUR_APP_ID',
        api_key: 'YOUR_API_KEY',
        components: {
          SearchBar: { root: 'search-bar' },
          SearchPage: { root: 'search-page' },
        },
        customCSSUrl: '/catalog/view/stylesheet/custom/client-theme.css',
        customLocaleUrl: '/catalog/view/stylesheet/custom/locales/' + storedLang + '.json',
        defaultLanguage: storedLang,
        settings: {
          wishlistEnabled: true,
          showIcon: true,
          compactPagination: true,
          primaryFacetAttribute: 'categories',
          platform: 'opencart',
        },
      });

      window.dispatchEvent(new Event('searchx:ready'));
      window.searchxReady = Promise.resolve();
    }

    if (window.SearchXSDK) {
      initSearchX();
    } else {
      window.addEventListener('load', initSearchX);
    }
  })();
</script>

Step 2: Search Bar Integration

Replace your existing search input with the SearchX container.

File: catalog/view/template/common/search.twig

<div id="search-bar" class="searchx-bar-container"></div>
<script>
  (function () {
    function mountSearchBar() {
      if (window.SearchXSDK && window.SearchXSDK.mount) {
        if (document.getElementById('search-bar')) {
          SearchXSDK.mount('Searchbar', { root: 'search-bar' });
        }
      }
    }
    if (window.searchxReady) {
      mountSearchBar();
    } else {
      window.addEventListener('searchx:ready', mountSearchBar);
    }
  })();
</script>

Step 3: Search Results Page

Update your search results template to use SearchX.

File: catalog/view/template/product/search.twig

Add the SearchX container inside your content area. Use Twig's header and footer includes as usual, and place the SearchX container where the default product listing loop was:

<div id="content" class="container">
  <!-- Your existing breadcrumbs here -->

  <!-- SearchX Results Container -->
  <div id="search-page" class="searchx-page-container"></div>
</div>
<script>
  (function () {
    function mountSearchPage() {
      var rootId = 'search-page';
      if (!document.getElementById(rootId)) return;
      if (window.SearchXSDK && window.SearchXSDK.mount) {
        try {
          SearchXSDK.mount('SearchPage', { root: rootId });
        } catch (err) {
          console.error('SearchX: Failed to mount SearchPage', err);
        }
      }
    }
    document.addEventListener('DOMContentLoaded', function () {
      if (window.searchxReady) {
        mountSearchPage();
      } else {
        window.addEventListener('searchx:ready', mountSearchPage);
      }
    });
  })();
</script>

Platform Setting

When using OpenCart, set the platform setting to "opencart". This enables OpenCart-specific "Add to Cart" behavior that uses OpenCart's native API routes:

settings: {
  platform: "opencart",
}

For more details on platform-specific behavior, see Event Handling.

Next Steps

• Customize the widget appearance with Widget Styling.
• Set up custom translations with Localization.