New fallback themes architecture

Fallback themes, introduced in SuiteCommerce and SuiteCommerce Advanced version 2023.2, allow developers to customize specific parts of a theme without taking responsibility for the entire codebase. This architecture enables a custom theme to "fall back" to the base theme for any components not explicitly modified, simplifying maintenance and updates.

SuiteCommerce fallback themes: what they are and how they work

Fallback Themes are a mechanism that allows the system to use a predefined hierarchy of themes when rendering a website. Instead of having to manually copy and maintain all theme files, fallback themes inherit missing templates and styles from a parent theme. This ensures that if a file is not present in the active theme, the system automatically pulls it from the fallback theme.

This system simplifies theme management by:

➡️ Reducing code duplication by avoiding redundant copies of theme files.
➡️ Easing maintenance by allowing global updates in parent themes.
➡️ Ensuring compatibility by automatically retrieving missing assets from a base theme.

How it Works

The system checks for a requested template, CSS file, or asset in the active theme.

If the file is missing, it searches in the fallback theme.

If it’s still not found, it continues searching in the base theme (e.g., SuiteCommerce theme).

The first available version of the file is used.

This hierarchical structure ensures that websites remain functional even when certain assets are not explicitly defined in the active theme.

Examples of Fallback Themes Usage

1. Inheriting a Template from a Fallback Theme

If you modify a theme and remove a template file (e.g., product_list.tpl), the system will automatically use the same file from the fallback theme.

Example:

Active Theme: MyCustomTheme

Fallback Theme: SuiteCommerce Base Theme

If MyCustomTheme/Templates/product_list.tpl is missing, the system uses SuiteCommerce Base Theme/Templates/product_list.tpl.

2. Customizing a Specific Template Without Affecting Others

If you want to customize only the header template (header.tpl) but keep all other templates from the fallback theme:

Steps

Create MyCustomTheme/Templates/header.tpl and modify it.

Do not include other templates unless needed.

The system will load the customized header.tpl but retrieve other templates from the fallback theme.

3. Extending Sass Files from a Fallback Theme

You can override or extend styles by only defining the changes needed in your theme.

Example:

The fallback theme has variables.scss defining: $primary-color: blue;

In your custom theme (MyCustomTheme), you override it: $primary-color: red;

The system will apply red as the new primary color while keeping other styles from the fallback theme.

4. Using a Fallback Theme for Multiple Brands

If you manage multiple brands with slight variations, you can:

Create a base theme with shared elements (e.g., layout, fonts, common styles).

Create child themes that override only brand-specific elements like logos, colors, or typography.

Example Structure:

BaseTheme (fallback) - Standard header, footer, buttons

BrandATheme (active) - Changes logo and primary color

BrandBTheme (active) - Uses different fonts and background styles

Each brand theme inherits everything else from BaseTheme, reducing maintenance effort.

Key Benefits

✅ Modular & Scalable – Makes managing multiple themes easier.
✅ Less Maintenance – Only update what's necessary in the active theme.
✅ Update Independence – Allows to update SuiteCommerce Base Theme to the latest version without any risk.
✅ Automatic Inheritance – Ensures missing files are retrieved seamlessly.

Frequently Asked Questions

What are fallback themes in SuiteCommerce?expand_more

How do fallback themes reduce maintenance effort?expand_more

Can I use fallback themes for multiple brands on SuiteCommerce?expand_more

What happens if a file is missing in my custom theme?expand_more

🔗 Sources

SuiteCommerce Themes: Interface Improvements, Upgrades, Maintenance

Introducing Template and Sass Changes to a Fallback Theme