Developers/Themes/Theme fundamentals

From Aimeos documentation

Other languages:
Deutsch 93% • ‎English 100% • ‎русский 94%

Themes are an easy way to use an existing design or to create a new one for an Aimeos web shop. A theme only consists of CSS and Javascript to style and animate the structural HTML of the front-end clients. In combination with the possibility to rearrange the sub-parts of the front-end, it's a powerful way to completely redesign a shop without touching the HTML code.

The default themes are located in the client/html/themes directory of the core. Each theme has its own directory containing the CSS and Javascript files as well as its images. The shared Javascript files are located in the base directory, which are used by all themes.


A theme must consist of these files and directories:

Contains the CSS styles that are used by the HTML front-end as well as in the HTML e-mails.
All CSS styles which makes the theme unique. You may also include styles that are necessary for any jQuery plug-in that is used.
Additional Javascript code for animations or to modify the existing JS code.
media/ (optional) 
Directory for all images, fonts and other media items that are used by the theme. They must be referenced relatively in the aimeos.css file like "url(images/aimeos.png)".

Cascading Style Sheets

CSS is a very powerful style sheet language used to describe the presentation for the existing HTML structure. It is possible to create a totally different layout by using individual styles for the same HTML elements.

If you want to create a new theme it is best to start with a CSS file of an existing theme. Their CSS definitions already contain a great amount of brain-power which makes them compatible with different browsers and for different devices like smart phones or tablets.

CSS classes and selectors

Styling the HTML for a theme is pretty straight forward as each component and almost all of its child elements have CSS class attributes associated to them. The root node of each component also contains a CSS class named "aimeos". Thus, you are able to identify and style all components that belong to the web shop at once, e.g. applying a font definition to the "aimeos" CSS class.

<section class="aimeos account-history">...</section>
<section class="aimeos catalog-filter">...</section>
<section class="aimeos catalog-detail">...</section>
<section class="aimeos basket-standard">...</section>
<section class="aimeos checkout-standard">...</section>

Furthermore, each component can be uniquely identified by its CSS class. The catalog detail component has the class "catalog-detail" for example. The names of the CSS classes for all other components follow the same naming scheme which is

<component type>-<component name>

Since the components are built with subparts (e.g. the "catalog-detail" view consists of an image section, a basic information section, a basket section, and so on), each subpart has its own CSS class (e.g. "catalog-detail-basket"). Additionally, the subparts of subparts have their own CSS class too (e.g. "catalog-detail-basket-selection"). This allows you as a theme designer to uniquely identify each subpart and apply a specific styling.

When defining new styles for a theme, always start with the CSS class of the subpart you want to style and then the class that is associated to the relevant HTML node, e.g.

.catalog-detail-basic .name { font-size: 125%; }

This uniquely identifies the node and keeps the CSS path short so the browser isn't required to check for intermediate CSS classes that aren't necessary.

For partials used several times at different locations, the same CSS classes apply to all. Examples for those classes are:

  • product
  • media-list and media-item
  • price-list and price-item

Don't use simple CSS classes like "product", "name" or similar for styling without a class identifying the component or the "aimeos" CSS class. This would cause side effects to the HTML the components are embedded into!

Responsive web design

Today, we have very different device sizes starting from small smart phones with 320px width to really big 4k TVs that span 3960px in width and countless device widths in between. The art of web design is to create pages that look great on all of these devices.

Frameworks like Twitter bootstrap or Foundation provide fluid grid systems that help developers create web sites optimized for different device sizes.

The first rule of responsive web design is: Avoid fixed measure units like px! They are only useful for defining a maximum or minimum device width for media queries. If you pay no attention to this advice, your theme will scale miserably! If you define a margin of 50px to both sides of a div container it will eat up most of the space on a smart phone and won't be noticed on a 4k TV. Instead, use

  • "%" for relative widths and font sizes
  • "em" for fixed widths
  • "em" for heights

Dump all thoughts about pixel perfect layouts immediately to the trash bin! Layouts must be fluid and adapt to the content, not the other way round.


Javascript code of a theme should only be used to improve site usability (by doing client side checks), to display necessary content, and to create animations. It should NOT be essential to use the shop! This usually results in poor usability for your site's visitors who do not use a mouse.

It's guaranteed that these jQuery libraries are available and included before the aimeos.js file:

  • jQuery >= 1.10 (not 2.0 or later)
  • jQuery-migrate
  • jQuery-UI (customized)

The jQuery-UI package contains the following features:

  • core
  • widget
  • mouse
  • position
  • autocomplete
  • menu

If you need additional jQuery-UI plug-ins for your theme, you can add them to the aimeos.js file of your theme. As they can be very big, you should be careful what you want to use in your theme. Otherwise, customers will be disappointed with the page load time.

The Aimeos shared library files contains some objects that are named just like the HTML clients that are available as components:

  • Aimeos
  • AimeosAccountHistory
  • AimeosAccountFavorite
  • AimeosAccountWatch
  • AimeosBasketMini
  • AimeosBasketRelated
  • AimeosBasketStandard
  • AimeosCatalogDetail
  • AimeosCatalogList
  • AimeosCatalogFilter
  • AimeosCatalogStage
  • AimeosCatalogSession
  • AimeosCheckoutConfirm
  • AimeosCheckoutStandard
  • AimeosLocaleSelect

These Javascript objects are globally available and their methods are responsible for executing the implemented actions if the required HTML DOM nodes are available. You can extend or overwrite each method to perform additional action, another action, or no action at all. The article about adapting existing themes has more information and examples of how to do this in detail.

To initialize the objects and set up the available methods, the init() method of each object is called after the DOM is ready.


This JS object contains the common methods used by more than one component.

Creates a floating container over the page displaying the given content node
Adds an overlay on top of the current page
Removes an existing overlay from the current page
Lazy load product image in list views
Sets up the ways to close the container by the user
Initializes the setup methods


The account history is a feature for the personal account of each customer displaying their orders.

Shows order details without page reload
setupOrderClose() Closes the order details without page reload
Initializes the account history actions


Customers can save products and they will be listed in their personal accounts.

Deletes a favorite item without page reload
Initializes the account favorite actions


Each customer has a personal watch list of products. If a product is added to the watch list, customers will be notified if the price of the product decreases or the product is back in stock again.

Deletes a watched item without page reload
Saves a modifed watched item without page reload
Initializes the account watch actions


The small basket is responsible to display the number of products in the basket and their total price.

Initializes the basket mini actions


The related basket component can be used to display e.g. products related to the basket content.

Initializes the basket related actions


This is the standard basket component displaying all details of the products as well as the delivery and payment costs of the chosen service items and any redeemed coupon codes.

Updates the basket using the given HTML code without page reload
Goes back to underlying page when back or close button of the basket is clicked
Hides the update button and show only on quantity change
Updates basket without page reload
Updates quantity and deletes products without page reload
Initializes the basket standard actions


The catalog detail component shows all information that is available for a product.

zoomImage(item, container) 
Initializes the image zoom for big images given in the item parameter within the container
Initializes the slider for the thumbnail gallery (small images)
Enables image zoom for first image by default
Displays the big image and highlight thumbnail after it was selected
Opens the lightbox with big images
Evaluates the product variant dependencies
Displays the associated stock level, price items and attributes for the selected product variant
Checks if all required variant attributes are selected
Initializes the slide in/out for block prices
Initializes the slide in/out for additional content
Adds a product to the favorite list without page reload
Adds a product to the watch list without page reload
Adds products to the basket without page reload
Initializes the catalog detail actions


For displaying categories, the full text search box and the faceted search, the catalog filter component is required.

Autocompleter for quick search
Sets up the form checks
Sets up the fade out of the catalog list
Toggles the categories if hover isn't available
Toggles the attribute filters if hover isn't available
Toggles the attribute filters if hover isn't available
Submits the form when clicking on filter attribute names or counts
Submits the form when clicking on filter attribute input fields
Initialize the catalog filter actions


All product lists are managed by the catalog list component.

Switches product images on hover
Initializes the catalog list actions


The catalog session is user content related like for the last seen products.

Initializes the catalog session actions


The catalog stage component is usually placed on top of the catalog list and detail views. It can display per-category images and the breadcrumb navigation.

Initializes the catalog stage actions


The checkout process is represented by the checkout standard component. It's one of the multi-step components that display different content based on the given parameters.

Shows only selected address forms
Shows company and VAT ID fields if salutation is "company", otherwise hide the fields
Shows states only from selected countries
Shows only form fields of selected service option
Checks for mandatory fields in all forms
Redirect to payment provider / confirm page when order has been created successfully
Initializes the checkout standard section


The last step of each successful order is the "thank you" page.

Initializes the checkout confirm section


To allow users to switch the used language and/or currency, the locale selector component provides a list of available languages and/or currencies. Both depend on the site of the shop and the combinations added by the shop owner.

Keeps menu open on click resp. closes on second click
Initializes the locale selector actions

New components

If you decided to implement a new component like an additional one for the catalog views, you should also provide a new Javascript object in your aimeos.js theme file. As long as you don't need any methods to interact with the HTML DOM, not more than an empty init() method is required:

  1. /**
  2.  * <type> <component> client actions
  3.  */
  4. Aimeos<type><component> = {
  6. 	/**
  7. 	 * Initializes the <type> <component> actions
  8. 	 */
  9. 	init: function() {
  10. 	}
  11. }

Please replace the placeholders for <type> and <component> with the appropriate names, like "Catalog" (type) and "Mycomponent" (component) depending on the names you've used for the HTML client class so you get e.g.

AimeosCatalogMycomponent = {}