Symfony/Use Twig templates

From Aimeos documentation

Symfony
Other languages:
English 100%


All Aimeos templates are written in PHP using a template engine and view helpers that are easy to understand. It works in all integrations in the same way, is extremely fast and doesn't require you as developer to learn a new syntax.

Since version 2017.04, you can alternatively use Symfonys Twig template engine for Aimeos templates overwritten for your project. Thus, all your templates will be in the same template language.

Configure Twig templates

To replace an Aimeos PHP template by our own Twig template, the Twig template needs to be stored at the same location as you would store the PHP template, i.e. the ./client/html/templates/ folder of your project-specific Aimeos extension. You should also keep the directory structure underneath and must save the file as <template-name>.html.twig, e.g.

./client/html/templates/catalog/detail/body-default.html.twig

The file extension .html.twig is important to be recognized as template that should be processed by Symfonys Twig engine. Additionally, you must configure your new template in your ./app/config/config.yml file, e.g.

  1. aimeos_shop:
  2.     client:
  3.         html:
  4.             catalog:
  5.                 detail:
  6.                     standard:
  7.                         template-body: catalog/detail/body-default.html.twig

You can find the available settings for the used templates in the configuration articles.

Aimeos Twig Extensions

The Twig functions available in the templates can't give you access to all data you need. Therefore, the Aimeos package contains some functions to retrieve data from Aimeos specific sources like configuration settings or translations.

Configuration

  1. mixed aiconfig( string $key [, mixed $default = null] )

The aiconfig() function retrieves the Aimeos setting for the given key, e.g. "client/html/catalog/lists/basket-add". If no value is found for the key, the given default value is returned instead.

Translation

  1. string aitrans( string $singular [, array $params = array() [, $domain = 'client' ]] )
  2.  
  3. string aitransplural( string $singular, string $plural, integer $number [, array $params = array() [, $domain = 'client' ]] )

The aitrans() function retrieves the translated value from the Aimeos Gettext files. It's similar to Symfonys trans filter and useful for translating singular phrases only. The aitransplural() function must be used to translate strings where numbers are involved, e.g.

  1. aitransplural( '%1$d apple', '%1$d apples', 10, array( 10 ) );

When the third parameter is "1", the function would return "1 apple" and for values greater than 1 it returns e.g. "10 apples". The method takes care about the different plural rules for all languages.

If the fourth argument (params) contains values, they will be used to replace the placeholders in the translated string. Internally, the vsprintf() method takes care about that.

The domain argument is the same as used in the Aimeos $this->translate() view helper. In the frontend it's either "client" or "client/code" while for templates in the administration interface it's "admin".

Blocks

The Aimeos template engine has a "block" view helper to save a rendered template so it can be inserted in another template. This is very similar to the {% block %} and {% endblock %} tags of Symfonys Twig engine and you should replace the block view helper statements with the appropriate Twig block directives, e.g.

  1.  <?php $this->block()->start( 'cataog/detail/actions' ); ?>
  2.      <div class="actions">
  3.          ...
  4.      </div>
  5.  <?php $this->block()->stop(); ?>
  6.  <?php echo $this->block()->get( 'catalog/detail/actions' ); ?>

by this Twig template:

  1.  {% block cataog_detail_actions %}
  2.      <div class="actions">
  3.          ...
  4.      </div>
  5.  {% endblock %}
  6.  {{ block('cataog_detail_actions') }}

Twig doesn't allow slashes ("/") in block names. Thus, you have to replace each slash with an underscore when using the block/endblock directives. In Aimeos templates, these blocks will be available with slashes as separator again.