Gaper Theme

1. Overview

Gaper is a modern, feature-rich theme for OpenCart 4.1.x.x. It provides a complete redesign of the storefront with extensive customization options accessible through an intuitive admin panel.

Key Features

2. Admin Panel Layout

The theme settings panel uses a vertical tab layout on the left side for easy navigation. All settings are organized into 13 tabs:

On mobile devices (< 768px), the tabs automatically switch to a horizontal scrollable layout.

Accessing Theme Settings

3. General Tab

Shadow Intensity

Controls the box-shadow depth for cards, dropdowns, modals, header, product cards, carousels, and all other elevated elements across the theme.

This setting overrides the following CSS variables globally:

4. Colors & Fonts Tab

Color Presets

Choose from 8 pre-designed color schemes. Clicking a preset automatically fills all color fields. The currently active preset is highlighted with a blue border.

Custom Color Presets

Save up to 3 custom color presets by clicking "Save as Custom Preset" below the Color Scheme section. Custom presets capture all 21 color fields (11 core colors + 10 extended colors for topbar, header, footer, and newsletter).

Custom presets appear in a separate row below the built-in presets with the same card design and color preview circles.

Core Colors

Typography

5. Header Tab

Top Bar

Header

Dropdowns

Currency, Language, and My Account dropdowns use hover-based activation on desktop (>= 768px) with a smooth fade-in transition. On mobile, they use the default Bootstrap click behavior.

Header Internal Tabs

Smart Search (Header)

Mega Menu (Header)

6. Category Tab

Listing Options

Subcategory Display

Category Sidebar Accordion

7. Product Tab

Quantity Control

Custom +/- buttons replace the native browser number input spinner. The design is consistent across all browsers and adapts to both light and dark themes.

8. Checkout Tab

One Page Checkout (OPC)

Checkout Fields

How OPC Works

The One Page Checkout displays all fields on a single page. When the customer fills in their address and selects a Region/State, the form automatically saves via AJAX — no "Continue" button is needed. Shipping methods, payment methods, and the order summary update in real time.

The Terms & Conditions agreement is handled by a checkbox in the order summary sidebar (not in the address form), preventing validation errors during auto-save.

9. Modules Tab

The Modules tab manages two groups of modules: (A) default OpenCart module overrides, and (B) the six Gaper-exclusive modules.

A. Default Module Overrides

Global settings applied whenever these OpenCart modules are placed in any layout position.

Settings (per module)

B. Gaper-Exclusive Modules

Six custom modules ship with the theme. They are managed only from the Gaper Modules tab — they do not appear in OpenCart's standard Extensions > Modules list. The tab shows a card grid of the six types, each with an "Add Instance" button and a list of existing instances with Edit + Delete actions. Each module type can have unlimited instances.

10. Home Layout Builder

The Home tab enables a custom home page layout without touching OpenCart's layout system. When the master toggle is OFF, the default OpenCart home layout (content_top + content_bottom) is used.

Master Toggle

Row Builder

• Add unlimited rows to the home page
• Each row has 1 to 4 columns
• 10 column-ratio presets based on Bootstrap's 12-grid system:
  • 2 columns: 6-6, 4-8, 8-4, 3-9, 9-3
  • 3 columns: 4-4-4, 3-3-6, 3-6-3, 6-3-3
  • 4 columns: 3-3-3-3
• Rearrange rows freely, delete rows individually
• Each column can hold one or more stacked modules

Module Picker

The per-column "Add Module" button opens a modal listing every installed module instance, grouped by extension. Both standard OpenCart modules (Featured, Latest, Banner, HTML, etc.) and the six Gaper-exclusive modules are selectable. Multiple modules can stack inside a single column.

Drag-and-Drop Reordering

Every row and every module chip has a grip handle (6-dot icon) on the left side. Click and hold the grip to drag:

• Reorder rows: Grab a row's grip handle (in the row header) and drag up or down to reorder rows on the home page.
• Reorder modules within a column: Grab a module chip's grip handle and drag up or down within the same column.
• Move modules across columns: Drag a module chip from one column and drop it into a different column — even across different rows.
• Row labels (Row 1, Row 2, …) auto-update after reordering. Remember to click Save to persist the new order.

Persistence

The layout is stored in the theme settings as JSON and rendered server-side on home page load. Each module is invoked through OpenCart's controller system, so caching and events behave normally.

11. Footer & Social Tab

Footer Colors

Footer Options

Payment Icons

When enabled, you can toggle individual payment icons:

Up to 4 custom payment icons can be added by uploading images.

Cookie Consent

Social Media Links

Enter full URLs for your social media profiles. Icons are displayed in the footer automatically when a URL is provided:

12. SEO Tab

Structured Data

Social & Business Info

13. Performance Tab

Optimization

CDN & Preloading

Analytics & Tracking

14. Custom Code Tab

15. Dark Theme Mode

The Gaper theme supports a full dark mode that is automatically activated based on the Background Color setting in the Colors & Fonts tab.

How It Works

The theme uses a luminance calculation on the Background Color:

If the luminance value is below 80, the theme adds the gaper-dark class to the <html> element, which triggers comprehensive dark mode CSS overrides for all components.

Activating Dark Mode

Simply select the "Dark Theme" preset in the Colors & Fonts tab, or manually set a dark Background Color (e.g., #1a1a1a). The theme will automatically:

• Add the gaper-dark class to the HTML element
• Apply dark overrides for all Bootstrap components
• Adjust form controls, dropdowns, tables, cards, modals
• Style the navigation bar with white text on primary background
• Apply dark styles to product cards, checkout, OPC, and CMS pages
• Adjust the category sidebar, banner module, and product modules

Dark Preset Colors

The built-in Dark preset uses a gold/amber + black color scheme:

16. Mobile Experience

The theme includes a complete mobile-optimized experience for screens < 992px.

Mobile Header

• Compact header bar: Hamburger menu (left), centered logo, search icon and cart icon (right)
• Cart badge shows item count, syncs with desktop mini-cart via AJAX
• Search icon expands a full-width search bar below the header

Off-Canvas Mobile Menu

• Slide-in menu from the left side with overlay backdrop
• Accordion-style sub-menus auto-populated from desktop navigation
• Account links section at the top
• Quick links at the bottom: Wishlist, Cart, Checkout, Compare
• Smooth slide transition with scrollable body

Responsive Behaviors

• Desktop navigation bar hidden on mobile (replaced by off-canvas menu)
• Top bar simplified: Center message hidden, text labels hidden (icons only)
• Sticky header disabled on mobile (mobile has its own compact header)
• Product countdown timer stacks below price on screens < 576px
• Mini-cart content adapts to full width with truncated product names

17. Quickview

The Quickview feature allows customers to preview product details in a modal without leaving the current page.

Features

• Full product images with gallery thumbnails
• Product name, price, and availability
• All option types supported:
  • Select, Radio, Checkbox (including Modern card style)
  • Text, Textarea
  • File upload (AJAX-based, uses OC4 tool/upload)
  • Date, Time, DateTime (native HTML5 inputs)
• Quantity +/- controls
• Add to Cart button
• "View Full Details" link to the product page

18. One Page Checkout (OPC)

The One Page Checkout replaces OpenCart's default multi-step checkout with a streamlined single-page experience.

Features

• All checkout fields visible on one page
• AJAX auto-save: Form data saves automatically when Region/State is selected
• Real-time shipping and payment method updates
• Shipping methods load immediately on page open (no address required first)
• Payment methods load automatically after shipping is saved
• Two layout options: Two Columns or Single Column
• Sticky order summary sidebar (in Two Column mode)
• Coupon code field (toggleable)
• Order comment field (toggleable)
• Terms agreement checkbox in the sidebar (not in the form)
• Compatible with both registered and guest checkout
• Full dark theme support

How It Works

For guest customers, the theme pre-seeds the session with the store's default country and zone (from System → Settings → General). This allows shipping quotes and payment methods to load immediately without requiring the customer to fill in their address first.

Loading Chain — Physical Products

1. Page loads → shipping methods auto-load (500ms delay)
2. First shipping method auto-selected and saved
3. After shipping save → payment methods load automatically
4. First payment method auto-selected and saved
5. Order summary and confirm section update

Loading Chain — Digital Products

1. Page loads → payment methods auto-load directly (500ms delay)
2. First payment method auto-selected and saved
3. Order summary and confirm section update

When the customer fills in their address and selects a Region/State, the form auto-saves via AJAX. Shipping and payment methods then reload with rates specific to that address.

How to Enable

1. Go to theme settings → Checkout tab
2. Toggle "Enable OPC" to On
3. Configure layout and field options
4. Save

19. Newsletter System

The theme includes a built-in newsletter subscription system.

Frontend

A newsletter signup section appears in the footer (when enabled in Footer tab). Customers enter their email address and subscribe via AJAX. Duplicate emails are handled gracefully with user-friendly messages.

Admin — Subscriber Management

View and manage subscribers from the admin panel:

The subscriber list shows:

• Email address
• IP address
• Subscription date
• Status

20. CMS Blog & Articles Compatibility

OpenCart 4's built-in CMS system (Topics and Articles/Blog) is fully compatible with the Gaper theme. No template overrides are needed — the CMS pages automatically inherit the theme's styling.

Supported Pages

• Blog listing (cms/blog): Search, topic filter, article cards
• Article detail (cms/blog_info): Full content, tags, author
• Comments: Comment cards, reply threads, like/dislike, modal form
• Blog widget module: Product-thumb style cards
• Topic sidebar module: List group with active state

Dark Mode

All CMS components have dark theme overrides:

• Comment cards with dark surface background
• Modal dialogs with themed header
• Form controls and buttons
• Borders and dividers
• Blog widget cards

21. Template Override System

The Gaper theme uses OpenCart 4's event system to override templates without modifying core files.

How It Works

The startup controller (catalog/controller/startup/gaper.php) registers an event listener for view/*/before. When a template route matches the override list, it redirects to the Gaper version at extension/gaper/{route}.

Overridden Templates

Common

• common/header
• common/footer
• common/home
• common/menu
• common/cart (mini-cart)
• common/search
• common/maintenance

Product

• product/thumb (product card)
• product/product (product page)
• product/category
• product/search
• product/special
• product/related
• product/review
• product/manufacturer_info

Account

• account/login
• account/register
• account/account

Checkout (Standard)

• checkout/cart

Checkout (OPC Only — Loaded When OPC Is Enabled)

• checkout/checkout
• checkout/register
• checkout/shipping_method
• checkout/payment_method
• checkout/payment_address
• checkout/shipping_address
• checkout/confirm

Information

• information/information
• information/contact

Error

• error/not_found

Modules

• extension/opencart/module/category (3-level accordion)
• extension/opencart/module/banner (modern redesign)
• extension/opencart/module/featured
• extension/opencart/module/latest
• extension/opencart/module/bestseller
• extension/opencart/module/special

Data Injection

The startup controller also injects additional data into templates:

• All templates: $args['gaper'] array with all theme settings
• Product page: Countdown timer data (date_end for special price)
• Category module: 3-level category hierarchy data
• Header: Compare URL and text_compare language string
• All pages: CSS variables, dark mode class, Google Fonts

22. OCMOD Core Modifications

The theme includes an OCMOD file (gaper.ocmod.xml) that modifies core OpenCart controllers to provide additional data needed by the theme.

Modifications

These modifications are non-destructive and are applied via OCMOD's virtual file system. Original core files are never modified.

23. OCMOD Editor (For Theme Updates)

The OCMOD tab in the Gaper Theme admin panel provides a built-in editor to view and update the OCMOD modification stored in the database. This is primarily used when updating the theme to a new version.

Why is this needed?

OpenCart 4 stores OCMOD modifications in the database (oc_modification table), not as files on disk. When you update theme files via FTP, the OCMOD in the database still contains the old version. The OCMOD Editor allows you to update it without uninstalling the theme (which would delete all your settings).

How to Update the Theme

OCMOD Editor Features

24. Multi-Store Support

Gaper Theme fully supports OpenCart's Multi-Store feature. You can run 2, 3, or more stores on a single OpenCart installation and give each one its own completely independent Gaper configuration — different colors, fonts, logos, layouts, modules, checkout mode, header style, footer links, and every other setting.

How It Works

OpenCart 4 stores all theme settings in its setting database table scoped by store_id. Gaper's admin controller reads and writes settings for the store you are currently editing. When a visitor accesses the frontend, OpenCart automatically loads the settings for that store based on the domain or URL, so each store renders with its own Gaper configuration.

Accessing the Store Switcher

When you have 2 or more stores configured in OpenCart (System > Settings), the Gaper admin page automatically displays a store dropdown at the top of the settings panel, labelled "Editing store:".

• Default Store — selects the default/global settings (store_id = 0)
• Additional stores appear below with their configured store name

Switching stores reloads the page and loads that store's settings for editing. If you have unsaved changes, you will be prompted to confirm before switching.

Inheritance Behavior

When you first open a non-default store for editing, settings that have never been saved for that store will show values from the Default Store. This lets you start from a clean baseline. A blue info banner at the top confirms:

"You are editing settings for a specific store. Unsaved fields inherit values from the Default Store."

Once you save the form for a specific store, that store gets its own complete set of settings that override the default.

Per-Store vs. Global Data

Setup Checklist (Multi-Store)

1. Create your additional store(s) under System > Settings > [New Store] and configure the store URL or domain.
2. For each store (including Default): go to System > Settings > [Edit that store] > General tab, set Theme to "Gaper Theme", then Save.
3. Open the Gaper Theme admin page. The store dropdown appears at the top of the settings card.
4. Select each store from the dropdown and configure its settings individually. Remember to click Save on each store before switching.
5. Verify by visiting the frontend URL of each store — they should render with their respective configured settings.

Troubleshooting

25. File Structure

Changelog

v1.2.1

v1.2.0

v1.1.0

v1.0.0

Initial release.