Skip to main content
page last edited on 17 January 2023


Version: 5.5.1

Themes differ from regular modules in that they are used primarily when choosing a template and a resource (js, css).

To create a theme, you need to specify skin as the type in main.yaml


A theme can be inherited from another theme. For that, the parent theme needs to be specified in the dependsOn list in the list of dependencies in main.yaml.

type: skin
authorName: 'X-Cart team'
moduleName: 'Sample Module'
description: 'The sample module'
minorRequiredCoreVersion: 0
- XC-CrispWhiteSkin
incompatibleWith: { }
showSettingsForm: false

In this case, it can be considered that the child theme extends not the core, but the parent theme, taking into account the fact that the parent theme itself extends the core or another theme along the chain. Building long inheritance chains is not recommended, as this will create difficulties with support.


In order for a theme to be able to redefine the templates of the core or the other modules, the template storage structure is organised as follows: In the <XCart>/modules/{AuthorId}/{ModuleId}/templates folder, the same structure is used as in <XCart>/templates; that way, if the theme has a template with the same file path relative to the templates folder as in the core, then the theme template will be used.

Resources (js, css, images)

For resources, the same principle is used as for templates - except that core resources are stored in <XCart>/assets, and module resources are stored in <XCart>/modules/{AuthorId}/{ModuleId}/public

When replacing the less file in a theme, it is possible to inject the code of the file being replaced without completely copying it by using the following construct:

@import "~parent";

Theme images for use in X-Cart Admin area

In order for theme preview images to be displayed on the Design→Themes page, you need to upload these images to the folder <XCart>/modules/{AuthorId}/{ModuleId}/config/images :

  • preview_left.jpg - two-column mode with left sidebar
  • preview_one.jpg - one-column mode
  • preview_right.jpg - two-column mode with right sidebar
  • preview_three.jpg - three-column mode
  • preview_list.jpg - theme image in the list

In order for the preview image of the theme to be displayed on the Apps→My Apps page, you need to upload this image to the folder <XCart>/modules/{AuthorId}/{ModuleId}/config/images/skin_list_image.jpg

Thumbnails for business objects

For traffic optimization, XCart has a mechanism for preparing thumbnails for the images of business objects.

The list of dimensions according to which thumbnails need to be created is stored in the database.

For a theme, it may be necessary to change the dimensions for a certain type of thumbnail or add a new one. There are two main ways to do that:


In the install.yaml file it is possible to create a section XLite\Model\ImageSettings and use this section to specify thumbnail dimensions for the object and type. For example:

- model: XLite\Model\Image\Category\Image
code: Default
width: 100
height: 100
- model: XLite\Model\Image\Product\Image
code: LGThumbnailGrid
width: 300
height: 300


It is possible to call the method \XLite\Logic\ImageResize\Generator::addImageSizes and pass into it a list of dimensions of thumbnail images for the object and type. For example:

\XLite\Logic\ImageResize\Generator::MODEL_CATEGORY => [
'Default' => [100, 100],
'XSThumbnail' => [60, 60],
'MSThumbnail' => [60, 60],
\XLite\Logic\ImageResize\Generator::MODEL_PRODUCT => [
'LGThumbnailGrid' => [300, 300],

It is best to do it in the init hook of the module.