Les zones dans Jelix représentent des morceaux de la réponse finale. En d'autre termes, elles sont destinées à gérer et générer le contenu d'une portion de l'écran, de la page web. Une page web est donc composée essentiellement de zones.

L'intérêt d'utiliser les zones est de :

• pouvoir réutiliser une zone dans des pages différentes : une zone est en théorie indépendante du contexte : elle fait elle-même appel aux classes métiers et possède son propre template.
• avoir une génération de contenu paramétrable : les zones acceptent des paramètres.
• pouvoir générer plus rapidement les pages, en activant la mise en cache des zones : seules les zones dont les paramètres changent (la zone principale en général) sont régénérées (ou celles dont on aura effacé le cache).
• au passage, alléger le code des contrôleurs.

Création ¶

class testZone extends jZone {

}

class testZone extends jZone {

   protected function _createContent(){
      return "<p>Ceci est le contenu d'une zone</p>";
   }
}

class testZone extends jZone {

   protected $_tplname='template_test';

   protected function _prepareTpl(){
       $this->_tpl->assign('foo','bar');
   }
}

<p>Ceci est un template. Et foo vaut {$foo}.</p>

php dev.php module:create-zone <MonModule> <MaZone> [<MonTemplate>]

php dev.php module:create-zone --notpl <MonModule> <MaZone>

Il y a plusieurs façons de récupérer le contenu d'une zone en fonction de ce que l'on veut faire.

Si on veut récupérer simplement son contenu (dans un contrôleur) on fait :

   $contenu = jZone::get('test'); // ou 'leModule~test'...

Cependant, il arrive très souvent qu'il s'agisse d'affecter le contenu de la zone à une variable du template principal, lorsque la réponse possède un template principal (ce qui est le cas des réponses HTML qui possèdent un objet jTpl dans sa propriété $body). Dans le contrôleur, on pourra donc utiliser la méthode assignZone de jTpl :

    $rep = $this->getResponse('html');
    $rep->title = 'page de test';
    $rep->bodyTpl = 'testapp~main';
    $rep->body->assignZone('MAIN', 'test');

• test correspondant au nom du fichier test.zone.php
• MAIN correspondant à la variable de template {$MAIN}

Autre solution, on peut avoir dans un template, un appel de zone direct :

  <div id="menu"> {zone 'leModule~test'} </div>

Appel avec des paramètres ¶

   $contenu = jZone::get('test', array('foo'=>'bar'));

    $rep = $this->getResponse('html');
    $rep->title = 'page de test';
    $rep->bodyTpl = 'testapp~main';
    $rep->body->assignZone('MAIN', 'test', array('foo'=>'bar'));

class testZone extends jZone {

   protected $_tplname='template_test';

   protected function _prepareTpl(){
       $foo = $this->param('foo');
       $foo = strtoupper($foo);
       $this->_tpl->assign('foo', $foo);
   }
}

   protected function _prepareTpl(){
       $this->_tpl->assign('foo', $this->param('foo'));
   }

  <div id="menu"> {zone 'leModule~test', array('foo'=>'bar')} </div>

Il est possible de mettre le contenu généré dans un cache. Et il peut y avoir un cache pour chaque valeur des paramètres de la zone.

Activation du cache ¶

class testZone extends jZone {

   protected $_useCache = true;
}

Rafraîchissement du cache ¶

class testZone extends jZone {
 
   protected $_useCache = true;
 
   protected $_cacheTimeout = 60; 
}

   jZone::clear('mymodule~article', array('id_article'=>546));

   jZone::clearAll('mymodule~article');

   jZone::clearAll();

Il faut noter que les méthodes _createContent() et _prepareTpl() (que vous pouvez surcharger), ne sont appelées que lorsque le cache doit être régénéré.

Il se peut que pour une raison ou pour une autre (en fonction de la valeur d'un certain paramètre par exemple), vous ne vouliez pas que parfois le résultat de la zone soit mis en cache.

Il suffit alors, dans _createContent() ou _prepareTpl(), de mettre la propriété $_cancelCache à true.

   protected function _prepareTpl(
      // ....
      $this->_cancelCache=true;
      //...
   }

Parfois, il peut arriver que l'on veuille désactiver le cache des zones, pour voir le résultat de ces zones quand on les modifie. Pour cela, vous pouvez modifier un paramètre dans la configuration, au niveau de la section [zones]

[zones]
disableCache = on

L'affichage d'une zone peut dépendre de paramètres donnés explicitement, mais aussi de paramètres "externes" implicites. C'est le cas par exemple pour une zone qui affiche la version d'un article en fonction de la langue configurée dans l'application. On peut bien sûr passer à chaque appel de zone le code langue, mais ce n'est pas forcément pratique. On pourrait ne pas avoir à l'indiquer dans les paramètres, et le récupérer soi-même dans _createContent() ou _prepareTpl(), mais alors il n'est pas possible que cela devienne un critère discriminant pour le système de cache si vous l'utilisez.

La solution est de surcharger le constructeur, et d'initialiser ce paramètre :

class articleZone extends jZone {

   protected $_useCache = true;

   public function __construct($params=array()){
       $params['lang'] = jApp::config()->locale;
       parent::__construct($params);
   }

}