Skip to content

Create new themes

Since 2020.10, there's a simple way to create new themes, install and configure them. Please read the article about theme basics first to understand how a theme is structured. Then, the steps are:

Create extension#

To create a portable theme, you should generate an extension for your theme first using the Aimeos extension generator. Copy it to the ./ext/ directory of your application and you should also put that extension under version control, e.g. by adding it to a Git repository.

Custom templates#

Most often, you don't need to change the structure of the HTML templates because you can rearrange the layout using CSS to a large degree. If your layout requires a different HTML structure, you can overwrite the HTML client templates from the ai-client-html extension.

The base layout of your application offers the general structure including HTML head and body tags but for Laravel and Symfony, there are additional layouts for each page. This doesn't apply to TYPO3 because as full-featured CMS, you can choose from different layout structures for each page and add or move the compenents to the slot where you need them.

Custom themes#

For a custom theme, you need to create the required CSS and JS files in ./client/html/themes/<themename>/ of your extension:

  • aimeos.css
  • email.css
  • aimeos.js
  • aimeos-detail.js

For the start, you can copy the existing "default" Aimeos theme directory and the included CSS, Javascript and image files and adapt them according to your needs, e.g.

cp -r ./client/html/themes/default/ ./client/html/themes/mytheme/

How to deploy your files depends on your host application:

Run composer up or execute cp -r ext/<themename>/client/html/themes/<themename> public/vendor/shop/themes/
Run composer up or execute cp -r ext/<themename>/client/html/themes/<themename> Resources/public/themes/
Adapt the TypoScript constants offered by the Aimeos extension in the "Template" panel of the navigation bar

For Laravel and Symfony, you have to adapt the client/html/common/template/baseurl setting to point to your new theme. The value must be the absolute directory to your theme and it's required to fetch the styling for the e-mail templates.

Custom CSS styles#

You have to adapt the two CSS files named

  • aimeos.css
  • email.css

to your theme directory in ./client/html/themes/<themename>/. These files must contain all styles for the HTML frontend (aimeos.css) and the sent e-mails (email.css).

The simplest way is to copy the files from the default "default" Aimeos theme and adapt them to your needs. Remove the styles you don't need to keep the file small and add the new styles for your theme.

The CSS class names used in the templates are semantic, so you can add CSS styles for the shop components only. To learn more about semantic naming, please read the article about theme basics.

You can also add icons you need for your theme to the ./client/html/themes/<themename>/media/ directory and reference them in the CSS using:


Custom Javascript#

By default, there are two standard JS files included in the theme directories: aimeos.js and aimeos-detail.js (catalog detail page only). Both are offered by the Aimeos ai-client-html extension and are located in ./ext/ai-client-html/client/html/themes/default of your installation. They contain the JS code for all dynamic features, which is described in the theme basics article.


Become an Aimeos Partner

Aimeos partners are first-class specialists in creating or hosting your Aimeos e-commerce project. They have proven their expertise by building top level e-commerce applications using Aimeos.