The template file.xml

This file is used to define a template and its associated zones. It is located in the directory cms/skins/[skinName]/templates/[templateName] directory.It is optional, but strongly recommended in order to describe at least the"default" zone used by some plugins Ametys files.

Format

template.xml

<template>
<label i18n="true|false">...</label>
<description i18n="true|false">...</description>
<thumbnail>
<small>path_to_16px_image_relative_to_resources_dir</small>
<medium>path_to_32px_image_relative_to_resources_dir</medium>
<large>path_to_48px_image_relative_to_resources_dir</large>
</thumbnail>
<zones>
<zone id="..." inherit="..." type="primary|secondary">
<label i18n="true|false">...</label>
<description i18n="true|false">...</description>
<thumbnails>
<small>path_to_16px_image_relative_to_resources_dir</small>
<medium>path_to_32px_image_relative_to_resources_dir</medium>
<large>path_to_48px_image_relative_to_resources_dir</large>
</thumbnails>
</zone>
</zones>
</template>

All labels and descriptions are internationalizable. The default catalog used is that of the graphic charter located in the cms/skins/[skinName]/i18n/ folder.

Preview images and pictograms must be located in the folder resources/ folder of the template: cms/skins/[skinName]/templates/[templateName]/resources/. They are then called up via a relative path: img/thumb_16.png.

Zone inheritance

Zones are inherited. By default, zones are not inherited, so if a zone contains no content or services, it remains empty. It is possible to integrate a notion of inheritance that allows, when a zone is empty, to retrieve the contents and/or services of its parent.

To do this, use the inherit attribute on the zone tag. Its value can be :

  • empty, it inherits the content or services inserted in its parent's zone of the same name.
  • the name of a zone, it then inherits the content or services inserted in its parent's zone with that name
  • the name of a template to the name of a zone, it then inherits the content or services inserted in the zone bearing this name, if its parent uses this template.

Case 1 - No inheritance

 

<zone id="z1"/>

The inherit attribute does not exist, there is no inheritance.

Case 2 - Simple inheritance

 

<zone id="z1" inherit=""/>
<zone id="z1" inherit="z1"/>
<zone id="z1" inherit="*->z1"/>

Zone z1 inherits zone z1 from the parent page. To avoid errors in logs, all templates must define zone z1.

Case 3 - Inheritance from another zone

 

<zone id="z1" inherit="z2"/>

Zone z1 inherits zone z2 from the parent page. To avoid errors in logs, all templates must define zone z2.

Case 4 - Inheritance by template

 

<zone id="z1" inherit="t1->z1,t2->z2"/>

The z1 zone inherits :

  • zone z1 if the master page uses template t1,
  • zone z2 if the master page uses template t2.

Case 5 - Conditional inheritance

 

<zone id="z1" inherit="*->z1,t2->z2,t3->"/>

The z1 zone inherits :

  • zone z2 if the master page uses template t2,
  • nothing if the parent page uses the t3 template,
  • the z1 zone in all other cases.

Root heritage

Since Ametys 4.6, it has been possible to create a special "sitemap" template (which cannot be assigned to a page).

The sitemap template is automatically assigned to the sitemap root. The root can then be viewed at CMS (and only at CMS), so that zones can be filled in. The advantage is that these zones can be inherited from the sitemap root pages.

For example, I've added the customizable Flux RSS service to the sitemap root in zone 3: it's available as an inheritable service on all pages (with shared customization) in all zones that inherit "sitemap->zone3".

Currently, it's only possible to insert services into the sitemap root.
Not all services work correctly by inheritance, especially from the sitemap root.

Zone type

Declaration

When declaring a zone, you can specify its type as an attribute: primary or secondary.

Zones are primary by default.

Primary zones are the main zones of the template. Usually there is only one, but the order of declaration counts otherwise.

There must always be at least one primary zone.

Use

On versions 3.7 and higher ofAmetys, the page creation wizard takes zone type into account when placing the main content/service: they are placed on the first primary.

Similarly, when assigning a new template via the menu, the first primary zone is selected by default.

Default" zone
A "default" zone identifier is always the highest priority.
Thus, for compatibility, 3.5 charters that have no primary zone highlighted but do have a "default" zone will function as expected.
Note that it is always interesting to have "default" as the main primary zone: this is for other functionalities or plugins.

Template, zone and zone element parameters

These elements can be set by the user.

Read the next page: View settings

Charter inheritance from template file.xml

As of Ametys 4.3, it is possible to inherit a charter and therefore its templates.
However, a template file.xml in a child charter simply replaces that of the parent charter.

As of Ametys 4.7, it is possible to inherit certain attributes within a template file.xml by following the documentation below.

Missing file

As the generic inheritance rule indicates, if the file is absent, the file from the parent charter is used.

Heritage

If the file is present it will be mixed with the parent chart file according to the following rules:

  • Si <label>, <description> ou <thumbnail> est spécifié dans la charte fille, il remplace celui de la charte parente, sinon il en hérite,
  • Pour <parameters>
    • Il est possible de désigner un <parameter> existant dans la charte parente en utilisant le même attribut "name",
      sa définition remplace celle de la charte parent
    • Il est possible de supprimer un <parameter> existant dans la charte parente en utilisant le même attribut "name",
      et en ajoutant l'attribute remove="true".
  • Pour <zones>
    • Il est possible de désigner une <zone> existante dans la charte parente en utilisant le même attribut "id",
      sa définition remplace celle de la charte parent
    • Il est possible de supprimer une <zone> existant dans la charte parente en utilisant le même attribut "id",
      et en ajoutant l'attribute remove="true".
<template>
   <parameters>
     <parameter name="existinginparent-1" type="boolean">...</parameter>
     <parameter name="existinginparent-2" remove="true"/>
     <!-- other parameters from parent are kept -->
  </parameters>
  <zones>
   <zone id="existinginparent-1" type="secondary">...</parameter>
   <zone id="existinginparent-2" remove="true"/>
   <!-- other zones from parent are kept -->
 </zones>
</template>

Blocking inheritance

By default, inheritance applies, but if the file has the attribute inherit="false", then only the local file is used.

<?xml version="1.0" encoding="UTF-8" ?>
<template inherit="false">
  ...
</template>

The template-default file.xml

From Ametys 4.8

It is possible to have a cms/skins/[skinName]/conf/template-default.xml file in the graphic charter, which will be used as the default value for all template files.xml.
There is the equivalent of an inheritance between these 2 files, so it is possible to use the options described above between these two files.

On the other hand, it's possible to mix this pseudo-inheritance with a classic charter inheritance: in this case, here's the order of operations:

  1. The final template-default.xml file is determined by charter inheritance.
  2. The final template file.xml is determined by charter inheritance.
  3. The complete file is the pseudo-inherited file between these two final files.
Back to top

Setup and integration manual