Symfony/Adapt pages

From Aimeos documentation

Other languages:
English 100%

When talking about pages we think of the full HTML response that is sent to the browser of the visitors after they entered a shop URL. It includes the output from the Aimeos components embedded into the base template you've provided after installation. This article focuses on changing the components that are visible on a page. If you want to adapt only the layout, please read the article about adapting the base template and theming of the shop components.

All Aimeos pages can contain a list of pre-defined blocks:

  • aimeos_styles ( additional CSS files)
  • aimeos_scripts (additional JS files)
  • aimeos_header (HTML head tags like product title and meta information)
  • aimeos_head (head section including the small basket for example)
  • aimeos_nav (shop navigation and faceted search)
  • aimeos_stage (stage area including breadcrumb navigation)
  • aimeos_body (main content for product lists, details or the checkout process)
  • aimeos_aside (user related content, e.g. last seen products)

If there is some content inside these blocks will be decided by the templates for the actions of the controllers. You can find these templates in the Resources/views/ directory and its subdirectories of the Aimeos web shop bundle.

Don't change the bundle

Even if it seems the easiest way to modify the templates and configuration files in the Aimeos web shop bundle directly, it's really a bad idea! You will loose the ability to update the Aimeos bundle without resetting everything to the standard configuration and templates. Instead, Symfony provides an easy way to overwrite the configuration as well as the templates of any bundle.

To overwrite the configuration, you only have to add the modified configuration settings to your app/config/config.yml file, e.g.

  1. aimeos_shop:
  2.     page:
  3.         "account-index": ['account/history']

would overwrite the list of components for the "MyAccount" page from the Aimeos bundle. In the same way you can replace existing templates by copying the original template to the app/Resources/AimeosShopBundle/views/Page/ directory of your Symfony application and modify it according to your needs.

Reorder components

The easiest possibility is changing the order of the single components inside the pre-defined blocks. Let's use the page template for the account page as example:

  1. {% extends 'AimeosShopBundle::base.html.twig' %}
  3. {% block aimeos_header %}
  4.     {{ aiheader['basket/mini']|raw }}
  5.     {{ aiheader['account/history']|raw }}
  6.     {{ aiheader['account/favorite']|raw }}
  7.     {{ aiheader['account/watch']|raw }}
  8.     {{ aiheader['catalog/session']|raw }}
  9. {% endblock %}
  11. {% block aimeos_head %}
  12.     {{ aibody['basket/mini']|raw }}
  13. {% endblock %}
  15. {% block aimeos_body %}
  16.     {{ aibody['account/history']|raw }}
  17.     {{ aibody['account/favorite']|raw }}
  18.     {{ aibody['account/watch']|raw }}
  19. {% endblock %}
  21. {% block aimeos_aside %}
  22.     {{ aibody['catalog/session']|raw }}
  23. {% endblock %}

The "{% extends ... %}" instruction defines the template this one will inherit the rest of the layout from. To change the order of the components in the "{% block aimeos_body %}, you can simple reorder the single lines inside the "{% block ... %} ... {% endblock %}" tags, e.g:

  1. {% block aimeos_body %}
  2.     {{ aibody['account/favorite']|raw }}
  3.     {{ aibody['account/watch']|raw }}
  4.     {{ aibody['account/history']|raw }}
  5. {% endblock %}

This would move the order history component to the end of the body container in the HTML response.

Add components

Adding more components to an existing page consists of two steps:

  • Add the component name to the overwritten page configuration
  • Insert the body and header output in the copied page template

By default, not all shop components are available on every page as this would create a lot of unnecessary load on your server. Instead, only the components are rendered and handed over to the template which are configured in the "page" section of the ./Resource/config/aimeos_shop.yml file, e.g.

  1. aimeos_shop:
  2.     page:
  3.         "account-index": ['account/history','account/favorite','account/watch','basket/mini','catalog/session']

Available components are listed for each Page controller action and they are identified using the directory structure of the HTML clients in the core. Thus, the account history component in the "Client/Html/Account/History" directory is addressed via the string "account/history". Similarly, the product listing component is identified by "catalog/list" or the product detail component by "catalog/detail". This works for all components besides the ones that are in the "Client/Html/Common" and "Client/Html/Email" directory.

Please keep in mind that some components need specific parameters like the "catalog/detail" component, which requires at least a value for the "d_prodid" parameter. There's a complete list of parameters used available for reference.

For example, if you want to add the catalog filter component to your "MyAccount" page as well, you can add its name inside the square brackets of the page component list:

  1. aimeos_shop:
  2.     page:
  3.         "account-index": ['account/history','account/favorite','account/watch','basket/mini','catalog/session','catalog/filter']

Here, the order of the component names doesn't matter but the header and body of the catalog filter component will be now available inside the "aibody" and "aiheader" array variables in the template of the account page controller action. Nevertheless, there's no output yet because you need to tell the template where their content should be rendered to:

  1. {% block aimeos_header %}
  2.     ...
  3.     {{ aiheader['catalog/filter']|raw }}
  4. {% endblock %}
  6. {% block aimeos_nav %}
  7.     {{ aibody['catalog/filter']|raw }}
  8. {% endblock %}

For the body, we use the "aimeos_nav" block so the filter menu will be located in the same place like in the other pages but you are free to put it in every block you want except the "aimeos_header" block. Contrary to that, the header data must always be placed in the "aimeos_header" block to be effective but the order inside the "aimeos_header" block is most of the time not important. Both lines need the "|raw" modifier after specifying which component to display. This avoids the HTML being escaped by the Twig template engine.

Remove components

Removing components is simple as you only have to provide a page template without the aibody and aiheader lines of the component, e.g.

  1. {% extends 'AimeosShopBundle::base.html.twig' %}
  3. {% block aimeos_header %}
  4.     {{ aiheader['basket/mini']|raw }}
  5.     {{ aiheader['account/history']|raw }}
  6.     {{ aiheader['account/favorite']|raw }}
  7.     {{ aiheader['account/watch']|raw }}
  8. {% endblock %}
  10. {% block aimeos_head %}
  11.     {{ aibody['basket/mini']|raw }}
  12. {% endblock %}
  14. {% block aimeos_body %}
  15.     {{ aibody['account/history']|raw }}
  16.     {{ aibody['account/favorite']|raw }}
  17.     {{ aibody['account/watch']|raw }}
  18. {% endblock %}

That template wouldn't output the "catalog/session" body and header HTML but to avoid rending them at all, you need to overwrite the page configuration as well:

  1. aimeos_shop:
  2.     page:
  3.         "account-index": ['account/history','account/favorite','account/watch','basket/mini']

For testing, it's OK to remove only the lines from the page templates but you get significant speedups in your production environment by providing a modified page configuration too.