Joomla! Documentation™

Joomla! 

3.x

série

Il est fréquent que des parties de pages soient répliquées dans plusieurs vues d'une extension, ou même de plusieurs extensions. Voici quelques exemples :

• une extension partageant certains rendus entre les vues de frontend et de backend, ou avec un ou plusieurs modules,
• les extensions du backend ayant des paramètres communs et devant donc répliquer des rendus communs afin de permettre aux utilisateurs de les modifier.

Jusqu'à Joomla! 3.0, le chargement (et la substitution de template) des fichiers de rendu était limité à une vue donnée. L'interface JLayout et un ensemble de classes ont été ajoutés à Joomla! 3.0 pour aider à résoudre ce problème. Il encapsule un rendu et les données nécessaires pour l'afficher de sorte qu'ils puissent être réutilisés dans des vues et extensions. Au moment de l'écriture de cette documentation, JLayout est utilisé par la classe JHtmlSidebar permettant d'afficher le sous-menu et les filtres sur la plupart des pages des extensions en backend.

JLayout consiste en une interface et 2 classes :

• L'interface JLayout définit les méthodes de rendu et d'échappement, à l'instar de la classe Jview de la plateforme Joomla,
• JLayoutBase implémente une classe de rendu de base, où, par exemple, le rendu peut être codé en dur dans la classe elle-même,
• JLayoutFile, la classe la plus couramment utilisée, enveloppe et affiche un rendu stocké dans un fichier, en vérifiant les substitutions dans le template avant de procéder.

Voici un exemple d'utilisation de base d'un fichier JLayout :

// Create a layout object and ask it to render the sidebar
$layout      = new JLayoutFile('joomla.sidebars.submenu', $basePath = null);
$sidebarHtml = $layout->render($data);

L'exécution de ce code créé un objet JLayoutFile, enveloppe un fichier de rendu et le transmet dans une structure $data qui peut être nécessaire pour l'affichage lui-même.

Le premier paramètre, 'joomla.sidebars.submenu' est l'identificateur de fichier. La dernière partie ('submenu') correspond au nom du fichier, tout ce qui précède ('joomla.sidebars') est le chemin relatif. Un paramètre optionnel $basePath peut être ajouté au chemin relatif. Si $basePath est manquant, les fichiers de rendu seront recherchés dans le répertoire /layouts.

Notre exemple :

new JLayoutFile('joomla.sidebars.submenu', $basePath = null)

aura pour résultat que le fichier de rendu 'submenu.php' sera chargé depuis le repertoire '/layouts/joomla/sidebars'.

Passer par un chemin de base non vide permet d'accéder et de stocker les fichiers de rendu dans n'importe quel répertoire du site, par exemple :

$layout = new JLayoutFile('my_layout', JPATH_ROOT .'/components/com_something/layouts');
$html = $layout->render($data);

chargera et affichera le fichier de rendu 'my_layout.php' situé dans le répertoire JPATH_ROOT .'/components/com_something/layouts' .

Indiquer le paramètre de client en tant que 3ème paramètre permet de charger les fichiers de mise en page depuis le répertoire du site public (frontend) au lieu du backend, par exemple :

$layout = new JLayoutFile('my_layout', NULL, array('client' => 0));
$html = $layout->render($data);

va charger et afficher le fichier de mise en page 'my_layout.php' trouvé dans le répertoire JPATH_ROOT .'/components/com_something/layouts' - mais qui peut toujours être surchargé dans le template de site.

Les substitutions de template :

Lors de l'exécution de la méthode render(), qui charge le fichier de rendu, JLayoutFile va vérifier l'existence d'une substitution dans le template actuellement sélectionné, dans un répertoire 'layouts'. En revenant à notre exemple initial, si vous voulez substituer la mise en page de la barre latérale de toutes les extensions Joomla! du backend, vous devriez mettre un fichier 'submenu.php' dans : /administrator/templates/{template_actuellement_selectionne}/html/layouts/joomla/sidebars/

Remarque : JLayoutFile va vérifier les substitutions du template sélectionné. Les rendus pouvant être partagés pour le frontend et le backend, si vous avez besoin de substituer un fichier de rendu pour l'un et l'autre, il vous faudra placer un fichier de substitution dans le template de backend et dans le template de frontend.

Stocker les rendus :

Les fichiers de rendu peuvent être stockés n'importe où, un chemin complet étant spécifié lors de leur utilisation (et permettent toujours la substitution de template). Cependant, pour plus de cohérence et pour éviter des conflits de noms, nous vous recommandons ce qui suit :

• par défaut, stockez les fichiers de rendu de votre extension dans son propre dossier layouts d'administration. Par exemple : /administrator/components/com_example/layouts
• si votre extension n'a pas de dossier d'administration (composant, module, plugin de frontend seul), alors utilisez un dossier layouts tel que :
  • /components/com_exemple/layouts
  • /plugins/content/exemple/layouts
  • /modules/mod_exemple/layouts

En outre, notez que le dossier lui-même DOIT être nommé layouts. L'utilisation du dossier racine/layouts est normalement réservé à Joomla! lui-même, et à d'autres futures applications officielles comme par exemple, le programme d'installation. Enfin, bien que non obligatoire, je vous conseille de mettre tous vos fichiers de rendu dans un sous-dossier supplémentaire "com_exemple" ou "mod_exemple" à l'intérieur du dossier principal "layouts". Cela ne sert à rien pour votre extension mais, si vous avez des substitutions de rendu de template pour plusieurs extensions, cela évitera des conflits de noms. Par exemple, si 2 extensions utilisent le JLayout "filters.search_all", alors un template ne pourra pas fournir de substitution séparée pour chacune d'entre elles. Une seule substitution sera utilisée pour les deux extensions, ce qui peut ne pas être souhaitable. Utiliser "com_exemple_1.filters.search_all" et "com_exemple_2.filters.search_all" permet aux templates de fournir des substitutions de rendu, même si elles ont la même id.

Exemples :

Voici un exemple très simple.

Créez un fichier /layouts/joomla/content/helloworld.php :

<?php
defined('JPATH_BASE') or die;

?>
<div id="helloworld">
  <h1>Hello World!</h1>
</div>

Puis dans n'importe quel fichier de rendu, tel que components/com_content/views/article/tmpl/default.php ajoutez :

<?php
$layout      = new JLayoutFile('joomla.content.helloworld');
echo $layout->render();
 ?>

Affichez un article sur le frontend et vous pourrez voir Hello World!. Bien sur, vous souhaiterez généralement transmettre certaines données via la méthode render().

Un exemple simple pourrait être :

<?php
defined('JPATH_BASE') or die;

?>
<div id="helloworld">
  <h1>Hello <?php echo $displayData['name']; ?>!</h1>
</div>

(Vous remarquerez que la variable transmise pour le rendu est appelée $displayData)

Avec le code PHP correspondant

<?php
$layout      = new JLayoutFile('joomla.content.helloworld');
$data = array('name' => 'Bob');
echo $layout->render($data);
 ?>

Maintenant, lorsque vous regardez votre article, vous devriez avoir : Hello Bob!.

D'autres informations sont disponibles sur cet article du Joomla! Community Magazine™ : Les améliorations de JLayout pour Joomla! 3.2 par Roberto Segura.