Raccourcis : Contenu - rubriques - sous rubriques
EN FR

Divers plugins sont de simple fonctions qui affichent quelque chose selon les paramètres.

zone

Permet l'affichage d'une zone.


  <div>
    {zone 'module~une_zone'}
  </div>

C'est en fait l'équivalent de


    $tpl->assignZone('ZONE','module~une_zone');

<div>
    {$ZONE}
</div> </code>

fetchzone

Pour récupérer le contenu d'une zone, afin de pouvoir par exemple l'afficher plusieurs fois sans appeler la zone plusieurs fois, ou pour tester son contenu avant affichage.


{fetchzonecontent 'submenu', 'navigation', array('parent'=>3)}
{if $submenu !== ''}
<div id="submenu">
    <h2>Submenu</h2>
    {$submenu}
    <hr />
</div>
{/if}

jlocale

Permet l'affichage d'une chaine localisée.


  {jlocale 'module~ma.locale.key'}

L'interêt par rapport à la syntaxe module~ma.locale.key, est que l'on peut indiquer des paramètres si le contenu de la chaine localisée est une chaine pour sprintf :


  {jlocale 'module~ma.locale.key', array("str1", "str2")}

jurl

Permet l'affichage d'une url correspondant à une action de jelix


  {jurl 'module~controlleur:action', array('id'=>$id)}

Il y a trois paramètres possibles :

  • Le sélecteur de l'action : 'module~controlleur:action'
  • les paramètres pour l'action (facultatif) : array('id'=>$id)
  • un boolean indiquant si on veut que certains caractères soient échappés (true) ou pas (false). Il vaut true par défaut.

Lorsque que l'on doit afficher une liste de résultats à l'écran et que cette liste est longue, il peut être judicieux de la répartir sur plusieurs pages. Le plugin Pagelinks facilite l'affichage d'un tel système de pagination, avec des liens pointant vers les différentes pages de résultats.

Pour utiliser le plugin avec les comportements par défaut, il suffit d'utiliser la syntaxe suivante.


  {pagelinks <module~action>, <paramètres de l'action>, <nombre total de résultats>, 
             <index résultat courant>, <nombre de résultats par page>, 
             <nom du paramètre d'offset>, <propriétés d'affichage>}

Exemple :


  <p>{pagelinks 'myModule~default_index', array(),  283, 60, 15, "offset"}</p>

Paramètres

  • <module~action> : Sélecteur de l'action qui doit être appelée par les liens de pages.
  • <paramètres de l'action> : Tableau contenant les paramètres métiers à placer dans l'url des liens de pages. Ex : array("param1" => 1, "param2" => "deux")
  • <nombre total de résultats> : Nombre entier représentant le nombre total des résultats répondant à votre requête. Vous devez donc l'avoir calculé au préalable.
  • <index résultat courant> : Nombre entier représentant l'offset, c'est-à-dire l'index du résultat courant. En clair : le numéro d'ordre du premier enregistrement afficher sur la page. Pour la première page, vous mettrez 0. Pour les pages suivantes, il est calculé automatiquement et passé dans le paramètre dont vous indiquez le nom dans <nom du paramètre d'offset>.
  • <nombre de résultats par page> : Nombre entier représentant le nombre de résultats contenus dans une page de résultats. Important : le plugin ne s'affichera pas s'il n'y a pas au moins 2 pages de résultats disponibles.

<propriétés d'affichage> est un tableau contenant les paramètres liés à l'affichage du plugin. Ce paramètre est optionnel. S'il est omis, le plugin utilise le comportement par défaut, à savoir qu'il affiche l'intégralité des liens avec leur intitulé par défaut.

Il est donc possible de personnaliser l'affichage, en définissant le nombre de liens à afficher ainsi que les intitulés des liens spéciaux (page suivante, page précédente, etc.). Pour cela on ajoute simplement un tableau de paramètres supplémentaires comme ci-dessous dans l'appel.


  <p>{pagelinks 'myModule~default_index', array(),  283, 60, 15, "offset", 
     array('start-label' => 'début', 
           'end-label' => 'fin', 
           'prev-label'  => 'précédent', 
           'next-label'  => 'suivant', 
           'area-size'  => 5)}</p>

Il est ainsi possible de renseigner une ou plusieurs des valeurs d'index suivantes qui viendront écraser le comportement défini par défaut.

  • @@start-label@ : Libellé du lien de la première page de résultats disponible.
  • prev-label : Libellé du lien de la page de résultats précédente.
  • next-label : Libellé du lien de la page de résultats suivante.
  • end-label : Libellé du lien de la dernière page de résultats disponible.
  • area-size : Nombre de liens à afficher avant et après la page courante. Si la valeur est 0, tous les liens seront affichés.

Siun label est vide, le lien correspondant ne sera jamais affiché. Bien entendu, il est aussi possible de possible d'utiliser un tableau de paramètres déclaré dans le contrôleur.


  $properties = array('start-label' => '',
                      'prev-label'  => 'précédent',
                      'next-label'  => 'suivant',
                      'end-label'   => '',
                      'area-size'   => 5);
  
  $rep->body->assign('properties',$properties);

L'appel du template aura donc la forme suivante.


  <p>{pagelinks 'myModule~default_index', array(),  283, 80, 15, 
              "offset", $properties}</p>

Il est possible de localiser les intitulés des liens spéciaux en utilisant jLocale de la façon suivante.


  $properties = array('start-label' => jLocale::get("bar~foo.pagelinks.start"),
                      'prev-label'  => jLocale::get("bar~foo.pagelinks.prev"),
                      'next-label'  => jLocale::get("bar~foo.pagelinks.next"),
                      'end-label'   => jLocale::get("bar~foo.pagelinks.end"),
                      'area-size'   => 0);

Mise en forme avec CSS

Le plugin Pagelinks ajoute des classes CSS sur les elements html qu'il génère pour permettre de styler les liens de pagination comme désiré.

  • ul.pagelinks : sélecteur css de la liste des pages disponibles
  • li.pagelinks-start : sélecteur css du lien vers la première page de résultats
  • li.pagelinks-prev : sélecteur css du lien vers la page de résultats précédente
  • li.pagelinks-current : sélecteur css de la page de résultats courante
  • li.pagelinks-disabled : sélecteur css des pages de résultats désactivées
  • li.pagelinks-next : sélecteur css du lien vers la page de résultats suivante
  • li.pagelinks-end : sélecteur css du lien vers la dernière page de résultats

Exemple de feuille de style minimaliste pour une utilisation de Pagelinks avec les propriétés d'affichage par défaut.


  ul.pagelinks>li {
      display: inline;
  }
  
  ul.pagelinks>li:before {
      content: ' | ';
  }
  
  ul.pagelinks>li.pagelinks-start:before {
      content: '';
  }

html : urljsstring

Le plugin de template urljsstring permet de générer une chaîne pour du javascript, qui contient une url généré par le moteur d'url de Jelix, et qui contient aussi des paramètres dynamiques en javascript. Par exemple, imaginons que l'on veuille ça en javascript :


  "/index.php/foo/default/bar?t=1547&param1=" + uneValeur + "&param2=" + (val*5)

On pourrait bien évidement écrire cela directement dans le script javascript. Mais si la forme d'url change ? On est alors obligé de modifier le template.

urljsstring permet d'éviter cela.

Ce plugin accepte trois paramètres :

  1. le sélecteur d'action (ex: "foo~default:bar")
  2. un tableau contenant les paramètres de l'url qui ont une valeur déjà calculée. Clés = noms des paramètres. Valeurs = valeurs des paramètres
  3. un tableau contenant les paramètres qui seront créés dynamiquement par le script javascript. Clés = noms des paramètres. Valeurs = expressions javascript.

Pour générer une url comme l'exemple ci-dessus, on affichera :


    {urljsstring "foo~default:bar" , array('t'=>1547) , 
                 array('param1'=>'uneValeur', 'param2'=>'(val*5)')}

Astuce : pour plus de lisibilité, vous pouvez bien sûr utiliser des variables de template


    {assign $paramjs=array('param1'=>'uneValeur', 'param2'=>'(val*5)')}
    {urljsstring $selecteur , $paramstatic , $paramjs}

Note : urljsstring génère les doubles quotes de la chaîne. Donc inutile de les rajouter dans votre script.


   // ceci est incorrect
   var foo = "{urljsstring $selecteur , $paramstatic , $paramjs}"
   
   // ceci est correct
   var foo = {urljsstring $selecteur , $paramstatic , $paramjs}

common : cycle

Le plugin cycle et d'autres qui lui sont associés, permettent d'afficher une serie de valeur de manière cyclique. Très utile dans une boucle, quand tour à tour vous voulez afficher une valeur différente. Exemple typique:


  {foreach $liste as $item}
   <tr class="{cycle array('impair','pair')}">
      <td>...<td>
   </tr>
  {/foreach}

À chaque tour de boucle, cycle va afficher "impair", puis "pair", puis "impair" (retour au debut de la liste de cycle) etc.

Contrôler un cycle

Il y a deux autres plugins à votre disposition pour mieux contrôler un cycle. cycle_init pour (ré)initialiser un cycle, et cycle_reset pour le repositionner au debut de la liste des valeurs.


  {cycle_init 'style1,style2,style3'}
  {foreach $liste as $item}
   <tr class="{cycle}">
      <td>...<td>
   </tr>
   {if $item == 'truc'}
      {cycle_reset}
   {/if}
  {/foreach}

Notez que cycle_init attend une chaine avec les valeurs séparées par des virgules, ou un tableau de valeurs.

Cycles nommés

Il se peut que dans une page web, vous voulez reutiliser le même cycle à plusieurs endroits, ou utiliser plusieurs cycles dans une même boucle. Il vous faut alors donner des noms à vos cycles. Le nom doit être indiqué en tant que premier argument.


  {foreach $liste as $item}
   <tr class="{cycle 'premier', array('impair','pair')}">
      <td class="{cycle 'styletd',array('style1,style2,style3')}">...<td>
   </tr>
  {/foreach}


  {cycle_init 'styles', 'style1,style2,style3'}
  {foreach $liste as $item}
   <tr>
      <td class="{cycle 'styles'}">...<td>
      <td class="{cycle 'styles'}">...<td>
   </tr>
  {/foreach}

Le résultat de la deuxième boucle sera


   <tr>
      <td class="style1">...<td>
      <td class="style2">...<td>
   </tr>
   <tr>
      <td class="style3">...<td>
      <td class="style1">...<td>
   </tr>
   <tr>
      <td class="style2">...<td>
      <td class="style3">...<td>
   </tr>
...

resurl

Permet d'utiliser une ressource par module, la ressource doit être placée dans un repertoire www dans le module.


    {resurl 'module', 'exemple.png'}

Paramètres

Module

Le module ou la ressource est placée.

File

Le fichier, avec son chemin relatif au repertoire www du module.

Paramètres additionnels

Ce plugin prend 2 paramètres additionnels :

In Theme ?

Indiquez true, en troisième paramètre, pour indiquer que la ressource est dans un thème (false par défaut)

Echappement

Indiquez false en quatrième paramètre pour que les caractères spéciaux ne soient pas échappés lors de l'affichage (true par défaut)

gravatar

ce modificateur permet d'afficher un avatar issu du site http://gravatar.com/

Pour ce faire il suffit de fournir le courriel dans le template comme suit :


{gravatar 'foo@bar.com'}

ce qui aura pour effet d'afficher votre gravatar à l'endroit voulu dans le template.

hook

Introduction

Ce modificateur, permet d'ajouter toutes les fonctionnalités de votre choix dans vos templates.

Pour exploiter les hooks vous écrirez dans votre template :


{hook 'eventname', $params}

eventname est le nom de l'évènement déclenchant la récuperation de toutes les fonctionnalités et $params est un tableau de paramètres à passer au listener qui répondra à eventname.

Exemple dans le template main.tpl :


{hook 'SampleBannerAnnouncement'}

affichera une bannière d'annonce dans le template de votre choix, en répondant à l'évènement SampleBannerAnnouncement.

Hook : convention de nommage

Ceci vous permettra de comprendre, en lisant le nom d'un évènement, à quel template il est lié. Ceci n'est pas une règle figée dans le marbre mais une façon de vous y retrouver dans vos futurs hooks.

  • BeforeTemplateName
  • TemplateName
  • AfterTemplateName

où :

  • TemplateName est le nom du template où le hook est utilisé
  • BeforeTemplateName est le nom du hook appelé au début du template TemplateName
  • TemplateName est le nom de l'évènement où le hook est appelé (en général au beau milieu du template)
  • AfterTemplateName est le nom du hook appelé à la fin du template TemplateName

Comment répondre aux hooks ?

Il faut produire un module (ou mettre toute la mécanique suivante dans une module existant) avec :

  • un listener
  • une zone
  • un template

Le Listener sera chargé de la réponse à l'évènement appelé dans la zone :


class hookListener extends jEventListener{
    
   function onhfbSampleBannerAnnouncement ($event) {
        $event->add( jZone::get('hook~samplebanner_accouncement') );
   } 
}

Le fichier events.xml définissant le listener qui répondra à l'évènement :


<?xml version="1.0" encoding="iso-8859-1"?>
<events xmlns="http://jelix.org/ns/events/1.0">
   <listener name="hook">
	    <event name="hfbSampleBannerAnnouncement" />
   </listener>
</events>

La zone qui exploitera les données de votre choix et fournira le template :


class samplebanner_accouncementZone extends jZone {
    protected $_tplname='zone.samplebanner_accouncement';
    
    protected function _prepareTpl(){    
        $this->_tpl->assign('text',jLocale::get('hook~main.welcome'));
    }        
}

Le template qui affichera les données retournées au template appelant :


<div class="grid_16">
    <div class="box">
    <h2>Banner</h2>
    {$text}
    </div>
</div>
<div class="clear"></div>

Tout ceci sera renvoyé automatiquement au template main.tpl (de notre exemple) à l'endroit voulu.