Utilisation et fonctionnement des layouts (blocs de vues)

Détails
Catégorie parente: Joomla
Catégorie : developpement d'extensions
Affichages : 1887

Layout : définition

Pour rappel : dans la terminologie de Joomla un layout (au sens du FrameWork de Joomla) est un bloc dans une vue (donc un découpage de la partie "composant" du template).
On entend assez régulièrement  le terme de layout pour définir les surcharges des templates de vues, mais ceci n'est pas correct.

Emplacement et nommage des fichiers de layout

Les principaux fichiers de Layout sont dans /layouts

Voici les dossiers dans lesquels on peut placer les layouts :

En administration

  • /administrator/templates/admin_template_name/html/layouts/com_component_name
  • /administrator/components/com_component_name/layouts
  • /administrator/templates/admin_template_name/html/layouts
  • /layouts

En frontal

  • /template/front_template/html/layouts/com_component_name
  • /components/com_components_name/layouts
  • /template/front_template/html/layouts
  • /layouts

Le loader ira chercher le fichier d'un layout dans cet ordre des dossiers.
(voir /librairies/src/Layout/FileLayout.php ligne 97 (fonction render et ligne 139 fonction getPath())

Ensuite le fichier php sera cherché dans un sous-dossier calculé selon le nom du layout.

Par exemple : le fichier du layout "joomla.toolbar.title" sera en joomla/toolbar/title.php dans un des dossiers "racine" listés ci-dessus selon qu'on en en partie publique ou administration.

Override

Au vu de l'ordre de recherche dans les dossiers, la première chose que l'on peut en déduire, c'est que l'on peut surcharger les layouts dans le template.
La recherche du layout dans le dossier template de l'application courante (front ou admin) se faisant en premier.

Dans la logique générale de Joomla, les fichiers de layout situés dans les dossiers de template, sont prévu pour la surcharge (override) du layout natif, ceci de la même manière que l'on fera un override d'un template de vue (override classique)

Une fois de plus les développeurs de Joomla ont bien pensé le système, en laissant énormément de possibilités aux stylistes pour jouer avec la présentation, sans toucher à la partie purement technique.

Appel d'un layout

Un layout est généralement appelé et rendu dans un template de vue par un appel de ce type :
echo JLayoutHelper::render('joomla.edit.global', $this);

Paramètres

Dans le fichier du layout, on récupère le 2ème paramètre de la méthode JLayoutHelper::render  dans la variable $displayData.
Donc dans l'exemple ci-dessus le paramètre étant $this, il s'agit de l’instance de la vue.

Le 3èeme paramatre permet de rajouter en premier rang un chemin de recherche.
Pour utiliser un layout placé dans une de vos librairies par exemple cela revient à faire un : $layout->addIncludePaths(JPATH_LIBRARIES . '/malib');
Il est è null en général.

Le 4ème parametres est un tableau d'options.

  • debut : true ou false
  • component : on peut force les nom du composant (si utilisation dans un module ou un plugin, ou pour charger un layout dans un autre composant que le composant courant)
  • client : 1 chercher le layout en admin, 2 = font

Exemple :

echo JLayoutHelper::render('afficheresultats.evenement', array('items' => $this->items, 'options' => array('filtersHidden' => false)), JPATH_LIBRARIES . '/lib_malib', array('debug' => true, 'client' => 2, 'component' => 'com_moncomposant'));

Ceci cherchera le fichier de layout dans cet ordre :

  • /libraries/lib_malib/afficheresultats/evenement.php
  • /templates/mon_template/html/layouts/com_moncomposant/afficheresultats/evenement.php
  • /components/com_moncomposant/layouts/afficheresultats/evenement.php
  • /templates/mon_template/layouts/afficheresultats/evenement.php
  • /layouts/afficheresultats/evenement.php

Un autre cas d'appel est par la méthode JToolbarHelper.
Par exemple : JToolbarHelper::title : appelle le layout : joomla.toolbar.title (voir /libraries/src/Tolbar/ToolbarHelper.php ligne 41).
Cette façon de faire est généralement utilisé dans le méthode addToolbar de la vue.

Mapping

Les layouts "standards" utilisent des tableaux de rubriques (voir dans les tables de Joomla).
Si ce nom de rubrique n'existe pas comme nom de champ dans le formulaire associé, le rendu de ce champ n'est pas traité.
Il est donc conseillé d'utiliser les mêmes noms de rubriques de table que Joomla, afin de vous permettre d’utiliser les layouts du Framework.
Sinon vous devrez créer les votre si vous souhaitez utiliser cette techniques de factorisation du code.

sublayout

si dans un layout de nom searchtools.php vous appelez la méthode : $this->sublayout('bar', $data);
le framework ira chercher le fichier bar.php situé dans le sous-dossier de même nom que le fichier de layout en cours (donc en ./searchtools/bar.php)

Appel en cascade

Dans un layout, on peut bien sûr appeler un autre layout.

Exemple le layout de filtres

Un exemple très utilisé dans joomla est le layout de filtres, appelé dans les templates de vues par :

echo JLayoutHelper::render('joomla.searchtools.default', array('view' => $this, 'options' => array('filtersHidden' => false)));

On le rencontre très souvent des les vues de type list en admin, mais je l'utilise aussi régulièrement en frontal.

Si vous avez retenu mes explications, ci-dessus, vous trouverez le fichier correspondant en /layout/jooomla/searchtools/default.php

Ce layout a une particularité, il utilise un autre formulaire (fichier xml) que celui de la vue principale.
Il est donc autonome à ce niveau et les champs n'auront pas à être redéfinis (ici les champs de filtres) quand on utilisera ce layout dans un autre vue.

Ce formulaire est généralement chargé dans la méthode display de la vue (fichier view.html.php) par cet appel :

$this->filterForm = $this->get('FilterForm');

qui comme vous le savez lance la méthode getFilterForm de la classe mère du modèle de type list (JModelList).

Cette méthode cherche une description de form du nom filters_nomdelavue dans le dossier ./models/forms du composant.

Donc :

  • en /administrator/components/com_moncomposant/models/forms/filter_nomdemavue.xml si on est en admin,
  • en /components/com_moncomposant/models/forms/filter_nomdemavue.xml si on est sur la partie publique.

Layouts particuliers

Rendu de JForm

L'appel de Form->renderField utilisera le layout : renderfields qu'il ira chercher dans les dossiers énumérés ci-dessus selon qu'on est en admin ou en front.

  • /layouts/joomla/form/renderfield.php

La méthode renderField accepte un tableau d'options qui sont :

  • class
  • rel
  • hiddenLabel (true ou false)

La méthode renderField appele les 2 methodes de JFormField  :

  • getInput : qui apelle les valeurs du champ (selon le type de champ du framework ou de votre composant :
    • text (standard) : methode getInput de /librairies/joomla/form/fields/text.php
      avec son layout standard joomla.form.field.text situe en /layouts/joomla/form/field/text.php
    • list...
    • etc...
  • getLabel : qui appelle le rendu du label avec le layout renderlabel.php

En ensuite passera ces valeurs (code html) à son propre layout comme décrit en début de ce paragraphe qui retournera le code html global du rendu du label et du champ.

Mode "debug"

JFormfield accepte un mode débug.
Pour cela il suffit d'ajjouter l'attribut debug="true" dans la description du champ dans le xml de la form.

Par exemple :

<?xml version="1.0" encoding="utf-8"?>
<form>
<fields name="proxy">
<field
name="adresse"
type="text"
label="COM_GSKITITRES_CLUBS_PROXY_VILLE_LABEL"
description="COM_GSKITITRES_CLUBS_PROXY_VILLE_DESC"
hint="COM_GSKITITRES_CLUBS_PROXY_VILLE_FILTER"
debug="true"
/>
<field name="rayon" type="list" default="15" label="Rayon" description="selectionnez un royon de recherche autour de votre ville">
<option value="5">5KM</option>
<option value="10">10KM</option>
<option value="15">15KM</option>
<option value="20">20KM</option>
<option value="25">25KM</option>
</field>
</fields>
</form>

Exemples

Terminons par quelques exemples.

Comme dit précédemment, j'utilise beaucoup les vues de type List dans la partie publique de mes composants, avec l'usage du layout joomla.searchtools.default ou en utilisant des layouts spécifiques dérivés.

Un besoin très simple est d'adapter le clés de langues standard, par des clés spécifiques à cette vue de votre composant.

En général je rajoute aussi des options d'affichage (ou de nom affichage), qui proviennent des options de lien de menu que je propose dans mes vues de type list.

Les deux exemples suivant utilisent le même layout juste avec des paramètres différents dans le lien de menu.
(Si les liens des exemples ci-dessous sortent en erreur 404, cliquez juste dans la barre d'adresse du navigateur + intro pour valider l'url).

Celui-ci, affiche la liste des clubs de la Ligue Grand Est de Ski...

Le deuxième exemple accessible ici... concerne le même lien de menu, avec juste des paramètres différents appliqué au layout et affiche un sublayout supplémentaire permettant la géolocalisation de l'internaute.

Dans ces exemples, vous constaterez aussi que le sub-layout des filtres nommé "bar" (fichier bar.php dans le dossier du layout : /layout/joomla/searchtools/default/), qui normalement s'ouvre lors du clic sur le bouton "outils de recherche" est déployé d'office à l'affichage de la vue.
C'est également par un paramètre de mon lien de menu qui est transmis au layout que j’obtiens ce résultat.
Les infobulles sont aussi spécifiques à la vue.

Voir aussi

https://docs.joomla.org/J3.x:JLayout_Improvements_for_Joomla!/fr