File substitution system enables you to easily extend themes and minimize the maintenance efforts. It allows you to replace the default interface files (such as templates, styles, images) at runtime based on current enabled skin module and locale conditions.
When X-Cart view system has to render a template or include a style, or somehow reference a file inside
<X-Cart>/skins folder, it will go through a certain algorithm to choose the best file given certain circumstances. Practically it will take a set of folder paths in the certain order and search for the file by given path inside those folders.
This system is based on the fallback scheme, which guarantees that if a view file is not found in the current skin, the system searches in the default skin and common files.
The fallback scheme is the following:
Current enabled skin paths:
<X-Cart>/skins/<skin_path>/<interface>. This path has to be defined by skin (read more about definition format).
Default skin path:
Common files, which are used regardless of interface:
<interface> stands for current displayed interface key, combined with locale code.
For example, when X-Cart renders a widget for a Russian-speaking customer,
<interface> will be:
The locale code also fallbacks to the default language - English. If file is not found by other language code or English is the enabled one,
<interface> will be simply
Such fallback can particularly help you when you have to display one image in different languages. You simply define page layout and style in default
customer interface path and provide only the translated image inside
Also, you can read more about available interfaces at Templates and interface page
The special case here is the
mail/<interface> folder for a message template.
So if you need to customize a certain template or file, you put an overriding one with the same name in the
<X-Cart>/skins/<skin_path>/<interface>/<path_to_file> directory, where
<path_to_file> is the path to the original template.
For example, the task is to add a message to the customer invoice below the logo and invoice number.
The red zone can be modified through
<X-Cart>/skins/common/order/invoice/parts/bottom.twig file. But it is the core file and you don't want to break the upgrade. Also, the task is to add the message to customer invoice only.
Using file substitution system, you create either
skins/theme_tweaker/customer/order/invoice/parts/bottom.twig with modified content, or go through the whole skin defining process and after that create
skins/new_skin/customer/order/invoice/parts/bottom.twig file (let's just assume that skin registers its path as
If you need to modify this template for a mailed invoice, you have to use
skins/new_skin/mail/common/order/invoice/parts/bottom.twig (in case of separate skin module). Also, starting from 5.3.2 version, you can create
skins/theme_tweaker/mail/common/order/invoice/parts/bottom.twig with modified content.
One way or another, the result is: