Zones in Jelix represent small parts of the final response. They are intended to manage and generate the content of a part of the screen, the web page. A web page is then primarily made of zones.

What is interesting in using zones is to :

• be able to reuse a zone in different pages : a zone is in theory independent from the context : it calls business classes by itself and has its own template.
• have a generation of content that accept parameters.
• be able to generate pages faster, activating the zone's cache : only the zones whose parameters have changed (the main zone in general) are regenerated (or those whose cache hase been deleted).
• make the code of controllers lighter.

Creation ¶

class ZoneTest extends jZone {

}

class testZone extends jZone {

   protected function _createContent(){
      return "<p>This is the content of a zone</p>";
   }
}

class testZone extends jZone {

   protected $_tplname='template_test';

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

<p>This is a template. And foo = {$foo}.</p>

php dev.php module:create-zone <MyModule> <MyZone> [<MyTemplate>]

php dev.php module:create-zone --notpl <MyModule> <MyZone>

There are several ways to retrieve the content of a zone according to what we want to do.

If you simply want to retrieve its content (in a controller), you do:

   $content = jZone::get('test'); // or 'TheModule~test'...

However, you will often have to affect the content of the zone to a main template variable, when the response has a main template (which is the case of html responses, through its $body property which is a jTpl object). In the controller, we will thus be able to use the assignZone method of jTpl:

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

• test correspondant to the file test.zone.php
• MAIN correspondant to the template variable {$MAIN}

Another solution is to have a direct call to a zone in a template :

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

It is possible pass parameters to a zone. Parameters should be in an associative array.

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

With the assignZone method of jTpl:

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

To retrieve the variable in the zone, we use the param() method:

class testZone extends jZone {

   protected $_tplname='template_test';

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

In this example we pass the 'foo' variable with 'bar' value as parameter of the zone. We have retrieved the 'foo' variable in the zone to process it (here: to make it upper case) and we affected 'foo' to the template of the zone.

Don't forget that Jelix affects automatically the variables passed as parameters of the zone to the template of the zone if it exists. You then can avoid to write:

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

If you use the zone plugin template, you pass the parameters to the zone this way:

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

It is possible to put the generated content in a cache. And you can have a cache for each parameter value of the zone.

Enabling the cache ¶

Class testZone extends jZone {
    Protected $_useCache = true;
}

Refreshing the cache ¶

Class testZone extends jZone {

    Protected $_useCache = true;
 
    Protected $_cacheTimeout = 60;
}

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

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

    jZone::clearAll ();

It should be noted that the methods _createContent() and _prepareTpl() (that you can override), are called only when the cache must be regenerated. It may be that for some reason or another (depending on the value of a parameter for example), you don't want sometimes to use the cache of the zone.

To do it, in _createContent() or _prepareTpl(), you just have to set $_cancelCache property to true:

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

To disable all zone cache, and thus be able to build your zone contents and see directly the results, you can set a config parameter, in [zones] section :

[zones]
disableCache = on

The display of a zone may depend explicitly given parameters, but also on "external" parameters implicitly. One example is a zone which displays the version of an article based on the language set in the app. You can of course indicate the code language at each call of the zone, but it is not practical. It might not have to indicate the parameters, and recover them in _createContent() or _prepareTpl(), but then it is not possible for this implicit parameters to be criterions for the cache system.

The solution is to override the constructor, and initialize this parameter:

class articleZone extends jZone {

    protected $_useCache = true;

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