Developers/Html frontend/Overwrite existing templates

From Aimeos documentation

Other languages:
English 100% • ‎русский 73%

2016.x version

Sometimes it is necessary to replace the templates of a component or subpart with a different one (e.g. if you need a different HTML structure or want to add more HTML nodes). In these cases, you can overwrite an existing template by creating a new file with the same name and within the same directory structure in an extension.

Use the Aimeos extension builder to create an extension for your shop site. The generated extension skeletons contains all necessary directories and configuration to be used out of the box.

All default templates are stored in the client/html/templates/ directory of the core. There are sub-directories for each component type and component implementation (e.g. the "catalog/detail" sub-directory for the detail component of the catalog components type). Below are the .php template files stored for the component and all its subparts. The naming of the template files in the directory structure is

<component type>/<component name>/[<subpart name>[-<sub-subpart name>]-]{body,header}-<variant>.php

The naming schema matches the hierarchy of the components and their subparts, which is also reflected by the corresponding classes in the src/ directory. Examples for this naming are:


Extensions that depend on the core and contain PHP template files in the client/html/templates/ directory and named the same as existing ones are used first. It is only if no extension contains an appropriate PHP template then the default one from the core is used.

The output of the basket/mini component is cached in the session of the user for performance reasons. If you change the templates, you will see changes only after the component is updated e.g. by adding a product. To ease development, you can disable the basket cache in your Aimeos installation via configuration.

Changing the templates of the catalog/detail/session component requires some more attention. For example, the output for the last seen items is rendered if you visit a detail view and the HTML snippet is added to the session of the user. If you change the template now and reload the page, nothing will happen because the HTML snippet in the user's session isn't updated. You have to visit the detail page of another product to see a new item in the list.

The existing items will still keep the layout when they have been added! To clear all entries that are using older versions of the template, you have to delete the session cookie in your browser.