TYPO3/Use Fluid templates

From Aimeos documentation

TYPO3
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 the TYPO3 Fluid template engine for Aimeos templates overwritten for your project. Thus, all your templates will be in the same template language.

The Aimeos templates contains nested objects and their methods sometimes needs arguments. To be able to call these methods within Fluid templates, you need to install the VHS view helper extension and use the v:call() view helper for this.

Configure Fluid templates

To replace an Aimeos PHP template by our own Fluid template, the Fluid 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, e.g.

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

The file extension .html is important to be recognized as template that should be processed by the Fluid engine. Additionally, you must configure your new template in your setup TypoScript file or section, e.g.

  1. plugin.tx_aimeos.settings.client.html.catalog.detail.standard.template-body = catalog/detail/body-default.html

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

Aimeos view helpers

The Fluid view helpers available by default can't give you access to all data you need. Therefore, the Aimeos package contains some view helpers to retrieve data from Aimeos specific sources like configuration settings or translations. You have to include this view helpers by adding this to the Fluid template before using them:

{namespace ai=Aimeos\Aimeos\ViewHelper}

Configuration

  1. {ai:config(key: 'key/to/config', default: '' )}
  2.  
  3. <ai:config key="key/to/config" default="" />

The ai:config view helper 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 (optional) is returned instead.

Translation

  1. {ai:translate(singular: 'string for singular', plural: 'string for plural', number: 1, arguments: {0: 10, 1: 'value'}, domain: 'client', escape: true)}
  2.  
  3. <ai:translate singular="string for singular" plural="string for plural" number="1" arguments="{0: 10, 1: 'value'}" domain="client" escape="true" />

The ai:translate view helper retrieves the translated value from the Aimeos Gettext files. It's similar to the f:translate view helper and useful for translating singular and plural phrases, e.g.

  1. {ai:translate(singular: ''%1$d apple', plural: '%1$d apples', number: 10, arguments: {0: 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 (arguments) 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".

If you don't want the output to be escaped (i.e. HTML tags returned as source), you should set the escape argument to "false".

All arguments besides "singular" are optional.

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 f:section tags of the Fluid engine and you should replace the block view helper statements with the appropriate Fluid section tags, 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 Fluid template:

  1.  <f:section name="catalog/detail/actions">
  2.      <div class="actions">
  3.          ...
  4.      </div>
  5.  </f:section>
  6.  <f:render section="catalog/detail/actions" arguments="{...}"/>