An In-Depth Look at Magento Theme Fallback
An In-Depth Look at Magento Theme Fallback

An In-Depth Look at Magento Theme Fallback

Published August 5, 2014 in Development
Compiling Sass with Phpstorm
June 10, 2014
Avoiding Code Errors
Avoiding Coding Errors
August 25, 2014

Magento supports unparalleled theme flexibility and sophistication that allow for incredibly custom branding while still retaining development efficiency and upgrade compatibility. In particular, the theme asset fallback system allows theme developers to only modify the parts of a theme which actually need to be customized. This feature also enables merchants to quickly deploy stylized stores while still retaining features developed for the overall brand.

Current Fallback Structure

Magento Enterprise 1.14 and Community 1.9 introduced a new, more flexible theme fallback mechanism. Each theme can now specify its parent, which can then specify its parent, and so on. This theoretically allows infinite fall back levels instead of the fixed number of fall back “slots” in older versions.

 

As powerful as this concept is, the core code powering it is relatively straightforward.

Config Discovery

While loading the current area in a controller’s preDispatch() method, a singleton instance of Mage_Core_Model_Design_Configis instantiated. This class’s constructor scans all themes for an etc/theme.xml file, and loads the contents into a in-memory config instance.

Mage_Core_Model_Design_Config::__construct()

Mage_Core_Model_Design_Config::__construct() screenshot

The contents of the theme.xml files are not yet interpreted, but the config tree is ready for when the time comes.

Fallback Determination

When a theme asset (translation, layout update file, template, etc) is loaded,Mage_Core_Model_Design_Package::getFilename() is used to determine the actual filesystem path to the file.

Mage_Core_Model_Design_Package::getFilename()

Mage_Core_Model_Design_Package::getFilename() screenshot

The package model tries each theme in the fallback path, then finally falls back to base/default if all else fails. The fallback path itself, however, is generated by Mage_Core_Model_Design_Fallback::getFallbackScheme() as seen below.

Mage_Core_Model_Design_Fallback::getFallbackScheme()

Mage_Core_Model_Design_Fallback::getFallbackScheme() screenshot

For compatibility with themes developed before 1.14/1.9, this method looks for the presence of a node in the design config for the current area/package/theme (which, of course, was directly populated from the contents of that theme’s theme.xml).

In the event that the theme does specify a parent node (and therefore opts-in to the new fallback logic),Mage_Core_Model_Design_Fallback::_getFallbackScheme() walks up the chain of parent nodes, starting from the current theme’s parent.

Mage_Core_Model_Design_Fallback::_getFallbackScheme()

Mage_Core_Model_Design_Fallback::_getFallbackScheme() screenshot

Otherwise, _getLegacyFallbackScheme() takes over and emulates the old fallback behavior.

Mage_Core_Model_Design_Fallback::_getLegacyFallbackScheme()

Mage_Core_Model_Design_Fallback::_getLegacyFallbackScheme() screenshot

This method returns a fallback path of the following form:

  1. First check the theme specified as default in System Configuration
  2. Then check the /default theme

Theme Overrides

In the event that a translation/template/skin/layout override is specified in System Configuration, the theme fallback is calculated in the same way, but the overridden file type follows an independent fallback path starting with the configured override theme.

Summary Flowchart

Considering the new theme fallback capabilities, current versions of Magento will use this fallback path to load theme asset files.

Current Magento theme fallback flowchart

Classic Fallback

Magento versions before Enterprise 1.14 and Community 1.9 used much simpler, albeit far less powerful and flexible, fallback logic.

Mage_Core_Model_Design_Package::getFilename() from Enterprise 1.13

Mage_Core_Model_Design_Package::getFilename() screenshot

Just as the legacy fallback logic used in current versions, the classic fallback logic simply checked the current theme for the given file type, the default theme set in System Configuration, the hard-coded /default theme, then finally fell back to base/default.

With this in mind, classic versions of Magento will use the following fallback path.

Classic Magento theme fallback flowchart

Summary

By allowing merchants to configure a chain of overriding themes combined with the ability to configure the current theme at the store view level, Magento provides a powerful and efficient mechanism to customize individual stores or landing pages while ensuring that core theme assets are consolidated and centralized. Additionally, Magento Enterprise 1.14 and Community 1.9 support endless flexibility and scalability by providing support for infinite levels of theme fallback.

4 Comments

  1. […] Eric Wiese from Classy Llama explains how the new infinite theme inheritance works internally: An In-Depth Look at Magento Theme Fallback […]

  2. Noetical says:

    Thank you for this informative post.
    BTW, all of the images in this post are missing…wanted to give you a heads–up! ;^D

    • Eric Wiese says:

      @Noetical

      Thanks for the heads up! A recent website migration ate some of my blog images, but it’s fixed now.

  3. MagentoTina says:

    Is this working also in Magento Admin? I already have custom Admin theme app/design/adminhtml/default/mycustom created and in use. But now, for some stores, I want to use another Admin theme, which will fallback to mycustom theme. I already tried defining parent theme in etc/theme.xml, but it seems like it’s not working. Do you know why?

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Related postsView all
March 27, 2018

How to Create a Payment Method in Magento 2

Sometimes you might need more than the standard out-of-the-box payment method. Perhaps you have an agreement with a credit card processor and a solution for their […]
March 6, 2018

How to Build a Theme in Magento 2

When building a custom theme for Magento, it’s important to follow best practices for how the system is designed to be extended. Magento 2’s frontend is […]
February 12, 2018

Display Configurable Product Price Ranges in Magento 2

Today we’re going to look at the advantages of using configurable products and how we can update how their prices display on Magento 2 product listing […]
Most Recent PostsView all
May 23, 2019

More Sites, Same Staff, Less Maintenance

April 23, 2019

Create and Apply Patches to Magento 2

This article covers how to create and apply patches to Magento 2. This article assumes you’re using Composer to install Magento (the second method listed in […]
April 22, 2019

One Step Checkout