Dispositions de templates

Structures des fichiers de mise en page

Dans un template, chaque extension qui génère une sortie html place le code de sortie dans un fichier de template au sein de la structure de fichiers de l'extension, souvent dans un dossier nommé tmpl. Quelques exemples :

• /modules/mod_login/tmpl/default.php
• /modules/mod_login/tmpl/default_logout.php
• /components/com_content/tmpl/article/default.php
• /plugins/content/vote/tmpl/vote.php

Dans une surcharge de template, un fichier portant le même nom est créé au sein de la structure de fichiers du template et celui-ci est utilisé à la place du fichier présent dans la structure de fichiers de l'extension. Exemples correspondants :

• /templates/cassiopeia/html/mod_login/default.php
• /templates/cassiopeia/html/mod_login/default_logout.php
• /templates/cassiopeia/html/com_content/article/default.php
• /templates/cassiopeia/html/plg_content_vote/vote.php

Cela vous permet de personnaliser la sortie selon vos besoins. Cependant, vous n'avez pas la possibilité de choisir d'utiliser ou non votre surcharge. Elle est toujours utilisée.

Dans une mise en page alternative de template, vous créez un fichier portant un nom différent de l'original mais dans le même dossier de template. Le nouveau nom ne doit pas contenir de caractère de soulignement. Vous créez également tout fichier qui partage la première partie du nom original. Un exemple :

• /templates/cassiopeia/html/mod_login/expires.php
• /templates/cassiopeia/html/mod_login/expires_logout.php

Il devient alors possible de choisir d'utiliser la mise en page par défaut d'origine ou la mise en page alternative. Le choix se fait dans le formulaire d'édition du module ou du composant (onglet Avancé pour les modules, onglet Paramètres pour les Articles). Notez que toutes les extensions ne permettent pas les surcharges ou les mises en page alternatives.

Attention : les plugins ne fournissent pas de mécanisme pour sélectionner des mises en page alternatives.

Mises en page alternatives de module

Créer une mise en page alternative pour un module est similaire à créer une surcharge de template pour un module. Dans les deux cas, vous créez un dossier appelé templates/.../html/. Par exemple, le dossier pour une surcharge de template ou une mise en page alternative de "mod_login" pour le template cassiopeia serait templates/cassiopeia/html/mod_login/.

Il existe deux différences importantes entre une surcharge de template et une mise en page alternative. La première concerne le nom du fichier. Pour la surcharge de template, vous nommeriez le fichier default.php pour correspondre au nom du fichier du noyau. Pour une mise en page alternative, vous utilisez un nom différent. La seule règle est que le nom du fichier ne doit contenir aucun caractère de soulignement.

La seconde différence importante est que, contrairement aux fichiers de surcharge de template qui sont utilisés automatiquement chaque fois que le module est affiché en utilisant le template avec la surcharge, un fichier de mise en page alternative n'est utilisé que si vous le sélectionnez en tant que paramètre dans les réglages des paramètres du Module.

Un exemple concret - mod_login

• Aller dans Système → Templates du site → Cassiopeia Détails et fichiers
• Sélectionner l'onglet Créer des surcharges.
• Dans la liste des Modules, sélectionner l'élément mod_login.
• Dans l'onglet Éditeur, sélectionner html → mod_login pour voir vos copies nouvellement créées des templates de sortie de mod_login.
• Renommer default.php en autre chose sans caractère de soulignement, expires.php dans cet exemple.
• Renommer default_logout.php en expires_logout.php.

Vous disposez maintenant de deux fichiers avec exactement le même contenu que les originaux. Modifiez le contenu de expires_logout.php pour ajouter un message informant l'utilisateur de l'heure à laquelle la session expirera après chaque chargement de page.

À la ligne 16, immédiatement sous les instructions use existantes, ajoutez ce qui suit :

use Joomla\CMS\Factory;

date_default_timezone_set('Europe/London');
$config = Factory::getContainer()->get('config');
$lifetime = $config->get('lifetime', 0);
$time = time() + $lifetime * 60;
$endTime = date('H:i:s', $time); // time() returns a time in seconds already

Et à la ligne 36, immédiatement après la ligne contenant l'instruction endif, ajoutez ce code :

<p class="text-center">
Your session will expire at <br><?php echo $endTime; ?>
</p>

Fermez les fichiers de Cassiopeia. Sélectionnez Contenu → Modules du site et ouvrez le module Connexion. Dans l'onglet Avancé, à l'élément Disposition, vous trouverez un choix entre -- Depuis le module -- / Par défaut et -- Depuis le template cassiopeia -- / expires.

Une façon d'utiliser cette fonctionnalité est d'avoir deux formulaires de connexion, l'un avec un accès Public et l'autre avec un accès Super Administrateurs. Pour ce dernier, sélectionnez l'option expires et seuls les Super Administrateurs verront le rappel de l'heure d'expiration de la session.

Il est important de comprendre que, si cela est spécifié dans l'écran des paramètres du module, une mise en page alternative pour un module sera utilisée pour ce module quel que soit le template utilisé pour afficher la page où le module est affiché. Il est donc de la responsabilité de l'administrateur de s'assurer que le fichier de mise en page fonctionnera comme souhaité dans tous les templates où ce module pourrait être affiché.

Traduction

Vous pouvez traduire le nom du fichier en utilisant les Redéfinitions de langue. Essayez la procédure suivante :

• Sélectionnez Système → Panneau de gestion → Redéfinitions de langue
• Sélectionnez votre langue et l'Emplacement Administration.
• Sélectionnez le bouton Nouveau et remplissez le formulaire. Dans cet exemple, la clé de langue est TPL_CASSIOPEIA_MOD_LOGIN_LAYOUT_EXPIRES et le texte pourrait être Connexion / Déconnexion avec heure d'expiration
• Enregistrez et fermez, puis revenez au formulaire du module Connexion.

Le champ de sélection de la mise en page du module avec expires traduit :

Mises en page alternatives des composants

Les mises en page alternatives des composants fonctionnent de manière similaire à celles des modules. Un fichier est placé dans le même dossier où vous placeriez un fichier de surcharge de template. Par exemple, pour créer une mise en page alternative pour un article avec le template "cassiopeia", vous placeriez un fichier dans le dossier templates/cassiopeia/html/com_content/article/. Comme pour les mises en page de module, le fichier ne doit pas porter le même nom que le fichier d'origine et ne doit pas comporter de tirets bas dans le nom. De plus, il ne doit pas y avoir de fichier XML portant le même nom dans ce dossier. (Nous aborderons les fichiers XML plus loin, dans la section Mises en page alternatives des liens de menu.)

Vous pouvez définir une valeur globale pour les mises en page des composants dans la fenêtre Paramètres du composant. Par exemple, dans la fenêtre Article : Paramètres, il existe un paramètre Choisir une mise en page comme indiqué ci-dessous :

Comme pour les mises en page de module, les mises en page des composants s'affichent sous forme de paramètres dans l'écran d'édition individuel du composant. Par exemple, pour un article, le paramètre apparaît dans l'onglet Articles : Paramètres de modification comme indiqué ci-dessous.

Comme pour les autres paramètres, le paramètre Valeur Globale utilisera le réglage du paramètre Paramètres. Le paramètre Valeur par Défaut du composant utilisera la mise en page par défaut du composant. Les mises en page alternatives que vous avez créées pour différents templates sont affichées sous l'en-tête de chaque template.

Les noms de fichiers peuvent être traduits. La ligne ci-dessous :

    TPL_CASSIOPEIA_COM_CONTENT_ARTICLE_LAYOUT_MYLAYOUT="Title Only No XML"

traduira un fichier nommé "mylayout.php" en "Title Only No XML".

Vous pouvez avoir plusieurs fichiers pour une même mise en page. Le fichier initial doit être nommé sans tirets bas et les fichiers supplémentaires doivent comporter des tirets bas.

Les mises en page alternatives de composant peuvent être utilisées avec les articles, les contacts ou les fils d'actualité.

Les mises en page alternatives de composant ne sont utilisées que lorsque deux conditions sont remplies : (1) elles sont spécifiées dans les paramètres du composant ; et (2) il n'existe aucun lien de menu pour ce composant spécifique. Par exemple, si vous avez un ou plusieurs liens de menu de type "Article unique" configurés pour un article donné, alors la mise en page alternative pour cet article ne sera pas utilisée. C'est la mise en page spécifiée dans le lien de menu qui sera utilisée à la place. Ceci est cohérent avec la manière générale dont fonctionnent les paramètres de composant, où le plus spécifique (dans ce cas un lien de menu d'article unique) prévaut sur le moins spécifique (dans ce cas, les paramètres de l'article).

Mises en page alternatives de catégorie

Les mises en page alternatives de catégorie fonctionnent comme les mises en page de composant. Les règles de spécification des fichiers de mise en page sont les mêmes. La seule différence est que le dossier est le dossier de la catégorie, et non celui du composant. Par exemple, une mise en page alternative de catégorie de contact pour cassiopeia se trouverait dans le dossier templates/cassiopeia/html/com_contact/category.

Vous pouvez définir les mises en page de catégorie globalement, dans l'écran Paramètres de chaque composant. Voici un exemple issu du formulaire Contacts : Paramètres / Catégorie :

Les mises en page alternatives de catégorie apparaissent lorsque vous ajoutez ou modifiez une catégorie dans le formulaire Composant : Ajouter/Modifier une catégorie / Paramètres, comme indiqué ci-dessous.

Les mises en page alternatives de catégorie peuvent être utilisées pour les articles, les bannières, les contacts et les fils d'actualité.

Comme pour les mises en page de composant, une mise en page de catégorie ne sera utilisée que si :

1. elle est sélectionnée dans les paramètres globaux ou de catégorie.
2. il n'existe aucun lien de menu spécifique pour la catégorie.

S'il existe un lien de menu configuré pour une catégorie spécifique, la mise en page sélectionnée dans le menu sera utilisée à la place de la mise en page alternative de catégorie.

Article Catégorie Blog et Liste

Pour les articles, deux mises en page de catégorie principales sont disponibles : Blog et Liste. Chacune de ces mises en page apparaît dans l'onglet Catégorie du formulaire Article : Paramètres, sous l'en-tête "Depuis le composant". Les mises en page alternatives apparaissent également dans la liste, permettant de sélectionner Blog, Liste ou une mise en page alternative de template comme mise en page de catégorie par défaut, soit globalement, soit lors de la modification d'une catégorie d'article unique.

Cela signifie que, comme pour les autres paramètres de disposition, vous pouvez contrôler si les liens de catégorie d'articles utilisent les dispositions blog ou liste. Il est important de comprendre que, comme pour les autres paramètres de disposition, cette option ne prend effet que lorsqu'il n'existe pas de lien de menu de catégorie unique pour la catégorie.

Liens de menu alternatifs

Les liens de menu alternatifs présentent une différence importante par rapport aux autres. Pour créer une mise en page alternative de lien de menu, vous devez inclure un fichier XML dont le nom correspond au fichier de disposition initial. Par exemple, pour créer un lien de menu alternatif appelé "myarticle" pour un article dans le template cassiopeia, vous devez créer deux fichiers dans le dossier templates/cassiopeia/html/com_content/article appelés myarticle.php et myarticle.xml. Si vous souhaitez inclure davantage de fichiers de disposition, vous ajouteriez ces fichiers avec des underscores dans les noms de fichiers.

Le fichier XML utilise le même format que les fichiers XML des liens de menu du noyau. Cela permet non seulement de créer une disposition personnalisée pour ce lien de menu, mais aussi de créer des paramètres personnalisés. Par exemple, vous pourriez masquer certains paramètres ou en ajouter de nouveaux.

Les liens de menu alternatifs apparaissent lorsque vous sélectionnez un type de lien de menu, comme indiqué ci-dessous.

Les liens de menu alternatifs sont utilisés et fonctionnent de la même manière que les liens de menu standards. Comme ils reposent déjà sur des dispositions personnalisées, les surcharges de template ne s'appliquent pas aux liens de menu alternatifs.

Comme indiqué ci-dessus, les dispositions de lien de menu sont prioritaires sur les mises en page alternatives de composant ou de catégorie.

La traduction des liens de menu alternatifs se fait à l'aide des balises suivantes dans les fichiers XML. Le format est "TPL_"<nom du template>_<composant>_<vue>_<nom du lien de menu>_<type de balise>. Par exemple, les lignes ci-dessous traduisent le titre, l'option et la description d'un lien de menu alternatif appelé "catmenuitem".

    TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE="cassiopeia Custom Category Layout"
    TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION="cassiopeia Custom"
    TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC="Description for cassiopeia custom category layout."

Ces chaînes doivent être ajoutées à administrator/language/overrides/en-GB.override.ini, mais vous pouvez utiliser le formulaire des redéfinitions de langue décrit ci-dessus.

Le fichier catmenuitem.xml commencerait par :

<?xml version="1.0" encoding="utf-8"?>
<metadata>
   <layout title="TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE" option="TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION">
      <help
         key = "JHELP_MENUS_MENU_ITEM_ARTICLE_SINGLE_ARTICLE"
      />
      <message>
         <![CDATA[TPL_CASSIOPEIA_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC]]>
      </message>
   </layout>

Contrôler le template pour les liens de menu alternatifs

Comme indiqué ci-dessus, la présence d'un fichier XML transforme une mise en page alternative en lien de menu. Le format du fichier XML est le même que celui des fichiers XML des liens de menu natifs. Avec ce fichier XML, vous pouvez ajouter les paramètres que vous souhaitez inclure pour ce lien de menu. Ils peuvent être identiques à ceux de l'un des liens de menu natifs, ou vous pouvez omettre des paramètres natifs ou en ajouter de nouveaux. Notez que si vous ajoutez de nouveaux paramètres, ceux-ci pourront être utilisés dans le fichier de disposition mais ne seront pas utilisés dans le modèle ou les fichiers de vue natifs.

Il est également possible de redéfinir les paramètres natifs. Un exemple est de contrôler avec quels templates une mise en page de lien de menu alternative peut être affichée. Dans certains cas, vous pouvez vouloir autoriser un lien de menu personnalisé à être affiché avec n'importe quel template du site. Dans d'autres cas, vous pouvez vouloir limiter la mise en page de ce lien de menu à un template spécifique. Dans ce cas, il vous suffit d'ajouter le paramètre suivant au fichier XML du lien de menu :

<fields>
  <field
    name="template_style_id"
    type="templatestyle"
    label="COM_MENUS_ITEM_FIELD_TEMPLATE_LABEL"
    description="COM_MENUS_ITEM_FIELD_TEMPLATE_DESC"
    filter="int"
    template="cassiopeia"
    class="inputbox">
  </field>
 </fields>

Ceci redéfinira le paramètre natif template_style_id. Définir le template à "cassiopeia" dans ce cas limitera l'utilisateur à ne sélectionner que les styles de template du template "cassiopeia".

Informations complémentaires

• Bases du template
• Dossiers et fichiers du template Cassiopeia
• Personnalisation du template Cassiopeia
• Surcharges de template
• Mises en page de template
• Template Cassiopeia simplifié - Une étude de cas - un template simple basé sur Cassiopeia