ZF Zend Framework

Behind the Site

Programmer's Reference Guide

Introduction
Zend_Navigation
Guide de référence du programmeur

Pages

Zend_Navigation est fournie par défaut avec deux types de page:

  • Pages MVC – utilisant la classe Zend_Navigation_Page_Mvc

  • Pages URI – utilisant la classe Zend_Navigation_Page_Uri

Les pages MVC proposeront des liens pour l'application courante et utilisent les paramètres MVC (action, controller, module, route, params). Les pages URI utilisent elles une seule option,uri, ce qui vous offre la possibilité de créer des liens vers des sites externes ou encore de créer des liens personnalisés comme par exemple <a href="#">foo<a>.

Caractéristiques communes aux pages

Toutes les classes pour des pages doivent étendre Zend_Navigation_Page, elles partageront ainsi des caractéristiques communes. Ces options sont représentées dans le tableau ci-après.

Les noms des options (en clés) sont dirigées vers les setters appropriés set. Ceci signifie qu'une option appelée order sera passée à la méthode setOrder(), et une option nommée reset_params sera dirigée vers setResetParams(). Si aucune méthode setter ne correspond, l'option sera alors évaluée comme un attribut personnalisé de la page.

Documentez vous au sujet de la création de pages Zend_Navigation_Page dans la documentation appropriée.

Options communes aux pages
Clé Type Valeur par défaut Description
label chaine NULL Un nom de page, comme 'Home' ou 'Blog'.
id chaine | entier NULL Un tag id à utiliser lors du rendu de la page, typiquement pour repérer un élément.
class chaine NULL Une classe CSS à utiliser lors du rendu de la page.
title chaine NULL Un titre de page utilisé lors du rendu, utilisé typiquement sous forme d'attribut title.
target chaine NULL La cible à utiliser dans la page.
rel tableau array() Attribue les relations de la page. Chaque élément dans le tableau est une paire clé-valeur où la clé désigne le type de relation et la valeur un pointeur vers la page. Par exemple 'alternate' => 'format/plain.html'. Pour une fléxibilité maximale, il n'y a pas de restrictions quant aux valeurs, elles peuvent être autre chose qu'une chaine. Concernant rel et rev, voyez la section de documentation sur l'aide de vue Links..
rev tableau array() Spécifie les relations inverses de la page. Fonctionne tout comme rel.
order chaine | entier | NULL NULL Fonctionne comme order pour les éléments de Zend_Form. Si spécifiée, la page sera parcourue dans un ordre précis ce qui signifie que vous pouvez forcer la page à apparaitre avant les autres en utilisant une valeur de order basse, comme -100. Si une chaine est passée, elle doit pouvoir être convertie en entier. Si NULL est utilisé, le paramètre sera remis à zéro, donc l'ordre dans lequel la page a été ajoutée sera utilisé.
resource chaine | Zend_Acl_Resource_Interface | NULL NULL Une ressource d'ACL à associer à la page. Voyez la documentation de la section sur les ACL concernant les aides de vue..
privilege chaine | NULL NULL Un privilège d'ACL à associer à la page. Voyez la documentation de la section sur les ACL concernant les aides de vue..
active booléen FALSE Si oui ou non la page doit être considérée comme active. Si à FALSE (ou non fourni), les pages MVC vont aller vérifier l'objet requête suite à l'appel à $page->isActive().
visible booléen TRUE Si oui ou non la page doit être visible à l'utilisateur ou juste présente dans la structure mais non représentée visuellement.
pages tableau | Zend_Config | NULL NULL Pages enfant de la page en cours. Peut être de type tableau ou Zend_Config contenant des options à passer à la méthode factory() ou des instances de Zend_Navigation_Page, ou un mélange des deux types.

Note: Propriétés personnalisées
 Toutes les pages supportent la gestion de propriétés personnalisées, ceci via les méthodes magiques __set($name, $value), __get($name), __isset($name) et __unset($name). Ces propriétés peuvent prendre n'importe quelle valeur et seront incluses dans le tableau retourné par $page->toArray(), ce qui signifie que les pages peuvent être dé/sérialisées même si elles comportent des propriétés non natives à leur classe.
Que les pages soient natives ou personnalisées par vos soins, les propriétés peuvent être gérées au moyen des méthodes $page->set($name, $value) et $page->get($name), ou encore via des méthodes magiques.

Exemple #1 Propriétés de pages personnalisées

Cet exemple montre comment les propriétés personnalisées des pages peuvent être utilisées.

  1. $page = new Zend_Navigation_Page_Mvc();
  2. $page->foo = 'bar';
  3. $page->meaning = 42;
  4.  
  5. echo $page->foo;
  6.  
  7. if ($page->meaning != 42) {
  8.     // quelque chose à faire ici
  9. }

Zend_Navigation_Page_Mvc

Les pages de type MVC utilisent des paramètres MVC issus du composant Zend_Controller. Une page MVC utilisera en interne Zend_Controller_Action_Helper_Url dans la méthode getHref() pour générer des cibles (hrefs), et la méthode isActive() utilisera les paramètres issus de Zend_Controller_Request_Abstract et les comparera aux paramètres internes à la page.

Options des pages de type MV
Clé Type Valeur par défaut Description
action chaine NULL Nom de l'action pour générer des cibles vers la page.
controller chaine NULL Nom du contrôleur pour générer des cibles vers la page.
module chaine NULL Nom du module pour générer des cibles vers la page.
params Array array() Paramètres utilisateurs pour générer des cibles vers la page.
route chaine NULL Nom de la route à utiliser pour générer des cibles vers la page.
reset_params bool TRUE Remettre à zéro les paramètres de la route ou non.

Note: Les trois exemples qui suivent supposent une configuration MVC par défaut, avec une route default.
L'URI retournée est relative au baseUrl de Zend_Controller_Front. Dans nos exemples, le baseUrl vaut '/' pour simplifier.

Exemple #2 getHref() génères les URI de la page

Cet exemple montre que les pages de type MVC utilisent Zend_Controller_Action_Helper_Url en interne pour générer les URIs suite à l'appel à $page->getHref().

  1. // getHref() retourne /
  2. $page = new Zend_Navigation_Page_Mvc(array(
  3.     'action'     => 'index',
  4.     'controller' => 'index'
  5. ));
  6.  
  7. // getHref() retourne /blog/post/view
  8. $page = new Zend_Navigation_Page_Mvc(array(
  9.     'action'     => 'view',
  10.     'controller' => 'post',
  11.     'module'     => 'blog'
  12. ));
  13.  
  14. // getHref() retourne /blog/post/view/id/1337
  15. $page = new Zend_Navigation_Page_Mvc(array(
  16.     'action'     => 'view',
  17.     'controller' => 'post',
  18.     'module'     => 'blog',
  19.     'params'     => array('id' => 1337)
  20. ));

Exemple #3 isActive() détermine si la page est active

Cet exemple montre que les pages de type MVC utilisent l'objet de requête afin de déterminer si elles sont actives ou non.

  1. /*
  2. * Requête dispatchée:
  3. * - module:     default
  4. * - controller: index
  5. * - action:     index
  6. */
  7. $page1 = new Zend_Navigation_Page_Mvc(array(
  8.     'action'     => 'index',
  9.     'controller' => 'index'
  10. ));
  11.  
  12. $page2 = new Zend_Navigation_Page_Mvc(array(
  13.     'action'     => 'bar',
  14.     'controller' => 'index'
  15. ));
  16.  
  17. $page1->isActive(); // retourne true
  18. $page2->isActive(); // retourne false
  19.  
  20. /*
  21. * Requête dispatchée:
  22. * - module:     blog
  23. * - controller: post
  24. * - action:     view
  25. * - id:         1337
  26. */
  27. $page = new Zend_Navigation_Page_Mvc(array(
  28.     'action'     => 'view',
  29.     'controller' => 'post',
  30.     'module'     => 'blog'
  31. ));
  32.  
  33. // retourne true, car la requpete a le même trio module/controller/action
  34. $page->isActive();
  35.  
  36. /*
  37. * Requête dispatchée:
  38. * - module:     blog
  39. * - controller: post
  40. * - action:     view
  41. */
  42. $page = new Zend_Navigation_Page_Mvc(array(
  43.     'action'     => 'view',
  44.     'controller' => 'post',
  45.     'module'     => 'blog',
  46.     'params'     => array('id' => null)
  47. ));
  48.  
  49. // retourne false, car page a besoin du paramètre id dans la requête
  50. $page->isActive(); // retourne false

Exemple #4 Utiliser les routes

Les routes sont utilisables dans les pages de type MVC. Si une page a une route, elle sera utilisée par getHref() pour générer l'URL de la page.

Note: Notez que si vous utilisez le paramètre route, vous devrez préciser les paramètres par défaut de la route (module, controller, action, etc.), autremant isActive() ne pourra déterminer si la page est active ou pas. La raison est qu'il n'existe actuellement aucune méthode permettant de récupérer les paramètres par défaut d'une route un objet Zend_Controller_Router_Route_Interface, ni même de récupérer la route courante depuis un objet Zend_Controller_Router_Interface.

  1. // La route suivante est ajoutée au routeur de ZF
  2. Zend_Controller_Front::getInstance()->getRouter()->addRoute(
  3.     'article_view', // nom de la route
  4.     new Zend_Controller_Router_Route(
  5.         'a/:id',
  6.         array(
  7.             'module'     => 'news',
  8.             'controller' => 'article',
  9.             'action'     => 'view',
  10.             'id'         => null
  11.         )
  12.     )
  13. );
  14.  
  15. // Une page est créee avec un paramètre 'route'
  16. $page = new Zend_Navigation_Page_Mvc(array(
  17.     'label'      => 'A news article',
  18.     'route'      => 'article_view',
  19.     'module'     => 'news',    // requis pour isActive(), voyez les notes ci-dessus
  20.     'controller' => 'article', // requis pour isActive(), voyez les notes ci-dessus
  21.     'action'     => 'view',    // requis pour isActive(), voyez les notes ci-dessus
  22.     'params'     => array('id' => 42)
  23. ));
  24.  
  25. // retourne: /a/42
  26. $page->getHref();

Zend_Navigation_Page_Uri

Les pages de type Zend_Navigation_Page_Uri peuvent être utilisées pour pointer vers des sites externes, ou des pages internes personnalisées. Les pages URI sont simples, en plus des options classiques des pages, les pages URI utilisent une seule option : uri. L' uri sera retourné à l'appel de $page->getHref() et retournera une chaine ou NULL.

Note: Zend_Navigation_Page_Uri ne pourra pas calculer elle même si elle est active ou pas suite à un appel à $page->isActive(). L'appel retournera la valeur que vous aurez spécifier vous-mêmes grâce à $page->setActive() ou via l'option de constructeur active.

URI page options
Clé Type Valeur par défaut Description
uri chaine NULL URI vers la page. Une chaine, ou NULL.

Créer des pages de type personnalisé

Etendre Zend_Navigation_Page ne nécessite pas forcément de réécrire le constructeur ou les méthodes setOptions() ou setConfig(). Le constructeur prend un seul paramètre de type Array ou Zend_Config et il est passé à setOptions() ou setConfig() respectivement. Ces méthodes appellerons par la suite les setters set() qui distribueront leurs options. Si l'option internal_id est présente, alors la méthode setInternalId() sera évaluée si présente, et l'option en question lui sera passée. Si une telle méthode n'existe pas, l'option sera alors vue comme une propriété de la page et sera accessible sous $internalId = $page->internal_id; ou $internalId = $page->get('internal_id');.

Exemple #5 La page personnalisée la plus simple possible

La seule chose à définir dans une page personnalisée est la méthode getHref().

  1. class My_Simple_Page extends Zend_Navigation_Page
  2. {
  3.     public function getHref()
  4.     {
  5.         return 'Quelquechose-ici--ce-que-je-veux';
  6.     }
  7. }

Exemple #6 Une page personnalisée avec des propriétés

Ajouter des propriétés à vos pages étendues ne nécessite pas de réécrire setOptions() ou setConfig().

  1. class My_Navigation_Page extends Zend_Navigation_Page
  2. {
  3.     private $_foo;
  4.     private $_fooBar;
  5.  
  6.     public function setFoo($foo)
  7.     {
  8.         $this->_foo = $foo;
  9.     }
  10.  
  11.     public function getFoo()
  12.     {
  13.         return $this->_foo;
  14.     }
  15.  
  16.     public function setFooBar($fooBar)
  17.     {
  18.         $this->_fooBar = $fooBar;
  19.     }
  20.  
  21.     public function getFooBar()
  22.     {
  23.         return $this->_fooBar;
  24.     }
  25.  
  26.     public function getHref()
  27.     {
  28.         return $this->foo . '/' . $this->fooBar;
  29.     }
  30. }
  31.  
  32. // can now construct using
  33. $page = new My_Navigation_Page(array(
  34.     'label'   => 'Les noms des propriétés sont dirigés vers les setters',
  35.     'foo'     => 'bar',
  36.     'foo_bar' => 'baz'
  37. ));
  38.  
  39. // ...or
  40. $page = Zend_Navigation_Page::factory(array(
  41.     'type'    => 'My_Navigation_Page',
  42.     'label'   => 'Les noms des propriétés sont dirigés vers les setters',
  43.     'foo'     => 'bar',
  44.     'foo_bar' => 'baz'
  45. ));

Créer des pages avec la fabrique

Toute les pages (même les personnalisées) peuvent petre créer via la fabrique Zend_Navigation_Page::factory(). Celle-ci peut prendre un tableau d'options ou un objet Zend_Config. Chaque clé correspondant à une option de l'obet page à créer comme l'indique la section concernant les Pages. Si le paramètre uri est passé et qu'aucun paramètre concernant MVC ne sont présents (action, controller, module, route), une page de type URI sera créee. Si un ou plusieurs paramètres concernant MVC sont passés, une page de type MVC sera retournée.

Si le paramètre type est passé, la fabrique l'utilisera pour déterminer le nom de la classe à utiliser. Les valeurs mvc ou uri créeront des pages de types MVC/URI.

Exemple #7 Créer une page MVC avec la fabrique

  1. $page = Zend_Navigation_Page::factory(array(
  2.     'label'  => 'My MVC page',
  3.     'action' => 'index'
  4. ));
  5.  
  6. $page = Zend_Navigation_Page::factory(array(
  7.     'label'      => 'Search blog',
  8.     'action'     => 'index',
  9.     'controller' => 'search',
  10.     'module'     => 'blog'
  11. ));
  12.  
  13. $page = Zend_Navigation_Page::factory(array(
  14.     'label'      => 'Home',
  15.     'action'     => 'index',
  16.     'controller' => 'index',
  17.     'module'     => 'index',
  18.     'route'      => 'home'
  19. ));
  20.  
  21. $page = Zend_Navigation_Page::factory(array(
  22.     'type'   => 'mvc',
  23.     'label'  => 'My MVC page'
  24. ));

Exemple #8 Créer une page URI avec la fabrique

  1. $page = Zend_Navigation_Page::factory(array(
  2.     'label' => 'My URI page',
  3.     'uri'   => 'http://www.example.com/'
  4. ));
  5.  
  6. $page = Zend_Navigation_Page::factory(array(
  7.     'label'  => 'Search',
  8.     'uri'    => 'http://www.example.com/search',
  9.     'active' => true
  10. ));
  11.  
  12. $page = Zend_Navigation_Page::factory(array(
  13.     'label' => 'My URI page',
  14.     'uri'   => '#'
  15. ));
  16.  
  17. $page = Zend_Navigation_Page::factory(array(
  18.     'type'   => 'uri',
  19.     'label'  => 'My URI page'
  20. ));

Exemple #9 Créer une page personnalisée avec la fabrique

Utilisez l'option type afin de nommer la classe à utiliser.

  1. class My_Navigation_Page extends Zend_Navigation_Page
  2. {
  3.     protected $_fooBar = 'ok';
  4.  
  5.     public function setFooBar($fooBar)
  6.     {
  7.         $this->_fooBar = $fooBar;
  8.     }
  9. }
  10.  
  11. $page = Zend_Navigation_Page::factory(array(
  12.     'type'    => 'My_Navigation_Page',
  13.     'label'   => 'My custom page',
  14.     'foo_bar' => 'foo bar'
  15. ));
Introduction
Zend_Navigation
Guide de référence du programmeur

Comments

Posted by: Hector Virgen on: 2010-03-23 20:12:47 ⁋
Note that if you are building an MVC navigation page, the route will default to the currently matched route (similar to the "url" view helper).

If your application uses a mix of routes, it's always a good idea to specify exactly which route to use for each navigation page so that the URLs are created correctly.
Posted by: Hector Virgen on: 2010-03-23 20:13:45 ⁋
Note that if you are building an MVC navigation page, the route will default to the currently matched route (similar to the "url" view helper).

If your application uses a mix of routes, it's always a good idea to specify exactly which route to use for each navigation page so that the URLs are created correctly.
Posted by: Dominic Watson on: 2011-10-25 19:39:30 ⁋
Ignore EVERYTHING up there. It's CRAP. This is what you're after:

Copy and paste this (1.11)

/application/configs/navigation.xml
--------------------------------------------------

<?xml version="1.0" encoding="UTF-8"?>
<configdata>
<nav>

<home>
<label>Home</label>
<controller>index</controller>
<action>index</action>
</home>

<user>
<label>Users</label>
<controller>user</controller>
<action>index</action>

<pages>
<login>
<label>Login</label>
<controller>index</controller>
<action>index</action>
</login>
<register>
<label>Register</label>
<controller>register</controller>
<action>index</action>
</register>
</pages>
</user>

</nav>
</configdata>


/application/Bootstrap.php
-------------------------------------------------

<?php

class Bootstrap extends Zend_Application_Bootstrap_Bootstrap
{

protected function _initNavigation()
{

$this->bootstrap("layout");
$layout = $this->getResource('layout');
$view = $layout->getView();

$config = new Zend_Config_Xml(APPLICATION_PATH . '/configs/navigation.xml','nav');
$navigation = new Zend_Navigation($config);

$view->navigation($navigation);

}

}


application/layouts/scripts/layout.phtml
---------------------------------------------------------

<!DOCTYPE html>
<html>
<head>
<?php echo $this->headTitle() ?>
<?php echo $this->headMeta() ?>
<?php echo $this->headScript() ?>
<?php echo $this->headStyle() ?>
</head>
<body>
<?php echo $this->navigation()->menu()->setMaxDepth(1); ?>
<?php echo $this->layout()->content; ?>
</body>
</html>



Bing, bang, boom. This is ALL anyone wanted to come here for.
Posted by: Rodrigo Valim on: 2012-01-14 11:02:02 ⁋
Perfect, Dominic Watson! You said it all!
Posted by: imacatlol on: 2012-01-25 23:08:04 ⁋
Using $layout->getView() in the bootstrap caused the script paths to break so I found an alternative example.

Instead of getting the view in the bootstrap in Dominic's example. You can put the navigation container into the registry.

$navigation = new Zend_Navigation($config);
Zend_Registry::set('Zend_Navigation', $navigation);

Then calling when doing:

$this->navigation()->menu()

In the view container stored in the registry will be used.

+ Add A Comment

Please do not report issues via comments; use the ZF Issue Tracker.

If you have a JIRA/Crowd account, we suggest you login first before commenting.

  • BBCode is allowed in the comment markup

    • Select a Version

    Languages Available

    Components

    Search the Manual

    • Navigation