Laravel/Adapt pages

From Aimeos documentation

Other languages:
English 100%

When talking about pages we tend to think of the full HTML response that is sent to the visitor's browser after they enter 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 sections:

  • 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)

The templates used by the controller actions decides if there's some content inside these sections. You can find these templates in the src/views directory and its subdirectories of the Aimeos e-commerce package.

Don't change the package

Even if it might seem the easiest way to modify the templates and configuration files directly in the Aimeos e-commerce package, it's really a bad idea! You will lose the ability to update the Aimeos package. If you were to make a package update, all of the changes you had made to the core package would be reset to the standard configuration and templates. Instead, Laravel provides a convenient way to overwrite the configuration files as well as the templates for any package.

To overwrite the configuration, you only have to modify the configuration settings in the config/shop.php file of your Laravel application.

  1. 'page' => array(
  2.     'account-index' => array('account/history'),
  3. ),

This would overwrite the list of components for the "MyAccount" page from the Aimeos package.

Another way you can adapt specific pages is by rewriting existing templates from the vendor/aimeos/aimeos-laravel/src/views directory. These templates can be overwritten by creating your own copies of these files into your Laravel application's resources/views/vendor/shop directory and subdirectories. These copies will overwrite the Aimeos vendor package's views. As stated in Laravel's documentation Overriding Package Views, "When you use the loadViewsFrom method [inside of your service provider's boot method], Laravel actually registers two locations for your views: the application's resources/views/vendor/ directory and the directory you specify."

Reorder components

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

  1. @extends('shop::base')
  3. @section('aimeos_header')
  4.     <?= $aiheader['basket/mini'] ?>
  5.     <?= $aiheader['account/history'] ?>
  6.     <?= $aiheader['account/favorite'] ?>
  7.     <?= $aiheader['account/watch'] ?>
  8.     <?= $aiheader['catalog/session'] ?>
  9. @stop
  11. @section('aimeos_head')
  12.     <?= $aibody['basket/mini'] ?>
  13. @stop
  15. @section('aimeos_body')
  16.     <?= $aibody['account/history'] ?>
  17.     <?= $aibody['account/favorite'] ?>
  18.     <?= $aibody['account/watch'] ?>
  19. @stop
  21. @section('aimeos_aside')
  22.     <?= $aibody['catalog/session'] ?>
  23. @stop

The "@extends('shop::base')" instruction defines the template this one will inherit the rest of the layout from. To change the order of the components in the "@section('aimeos_body')", you can simple reorder the single lines between the "@section('...') ... @stop" tags, e.g:

  1. @section('aimeos_body')
  2.     <?= $aibody['account/favorite'] ?>
  3.     <?= $aibody['account/watch'] ?>
  4.     <?= $aibody['account/history'] ?>
  5. @stop

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 modified page configuration
  • Insert the body and header output in the 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 that are rendered, which are configured in the "page" section of the ./config/shop.php file, are handed over to the template file. e.g.

  1. 'page' => array(
  2.     'account' => array('account/history','account/favorite','account/watch','basket/mini','catalog/session'),
  3. ),

Available components are listed for each 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" and the product detail component is identified 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 configuration array of the page component list:

  1. 'page' => array(
  2.     'account-index' => array('account/history','account/favorite','account/watch','basket/mini','catalog/session','catalog/filter'),
  3. ),

The order of the component names does not matter. The header and body of the catalog filter component will now be available to use inside the "aibody" and "aiheader" array variables in the template file specified in the "account" controller / "index" action. Nevertheless, there's no output yet because you need to tell the template where their content should be rendered to:

  1. @section('aimeos_header')
  2.     ....
  3.     <?= $aiheader['catalog/filter'] ?>
  4. @stop
  6. @section('aimeos_nav')
  7.     <?= $aibody['catalog/filter'] ?>
  8. @stop

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 must be printed directly with the "<?= ... ?>" tags to avoid the HTML being escaped by the Blade 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('shop::base')
  3. @section('aimeos_header')
  4.     <?= $aiheader['basket/mini'] ?>
  5.     <?= $aiheader['account/history'] ?>
  6.     <?= $aiheader['account/favorite'] ?>
  7.     <?= $aiheader['account/watch'] ?>
  8. @stop
  10. @section('aimeos_head')
  11.     <?= $aibody['basket/mini'] ?>
  12. @stop
  14. @section('aimeos_body')
  15.     <?= $aibody['account/history'] ?>
  16.     <?= $aibody['account/favorite'] ?>
  17.     <?= $aibody['account/watch'] ?>
  18. @stop

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. 'page' => array(
  2.     'account-index' => array('account/history','account/favorite','account/watch','basket/mini'),
  3. ),

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.