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.

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

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

$page = new Zend_Navigation_Page_Mvc();
$page->foo = 'bar';
$page->meaning = 42;
 
echo $page->foo;
 
if ($page->meaning != 42) {
    // quelque chose à faire ici
}

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.

Example #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().

// getHref() retourne /
$page = new Zend_Navigation_Page_Mvc(array(
    'action'     => 'index',
    'controller' => 'index'
));
 
// getHref() retourne /blog/post/view
$page = new Zend_Navigation_Page_Mvc(array(
    'action'     => 'view',
    'controller' => 'post',
    'module'     => 'blog'
));
 
// getHref() retourne /blog/post/view/id/1337
$page = new Zend_Navigation_Page_Mvc(array(
    'action'     => 'view',
    'controller' => 'post',
    'module'     => 'blog',
    'params'     => array('id' => 1337)
));

Example #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.

/*
 * Requête dispatchée:
 * - module:     default
 * - controller: index
 * - action:     index
 */
$page1 = new Zend_Navigation_Page_Mvc(array(
    'action'     => 'index',
    'controller' => 'index'
));
 
$page2 = new Zend_Navigation_Page_Mvc(array(
    'action'     => 'bar',
    'controller' => 'index'
));
 
$page1->isActive(); // retourne true
$page2->isActive(); // retourne false
 
/*
 * Requête dispatchée:
 * - module:     blog
 * - controller: post
 * - action:     view
 * - id:         1337
 */
$page = new Zend_Navigation_Page_Mvc(array(
    'action'     => 'view',
    'controller' => 'post',
    'module'     => 'blog'
));
 
// retourne true, car la requpete a le même trio module/controller/action
$page->isActive();
 
/*
 * Requête dispatchée:
 * - module:     blog
 * - controller: post
 * - action:     view
 */
$page = new Zend_Navigation_Page_Mvc(array(
    'action'     => 'view',
    'controller' => 'post',
    'module'     => 'blog',
    'params'     => array('id' => null)
));
 
// retourne false, car page a besoin du paramètre id dans la requête
$page->isActive(); // retourne false

Example #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.

// La route suivante est ajoutée au routeur de ZF
Zend_Controller_Front::getInstance()->getRouter()->addRoute(
    'article_view', // nom de la route
    new Zend_Controller_Router_Route(
        'a/:id',
        array(
            'module'     => 'news',
            'controller' => 'article',
            'action'     => 'view',
            'id'         => null
        )
    )
);
 
// Une page est créee avec un paramètre 'route'
$page = new Zend_Navigation_Page_Mvc(array(
    'label'      => 'A news article',
    'route'      => 'article_view',
    'module'     => 'news',    // requis pour isActive(), voyez les notes ci-dessus
    'controller' => 'article', // requis pour isActive(), voyez les notes ci-dessus
    'action'     => 'view',    // requis pour isActive(), voyez les notes ci-dessus
    'params'     => array('id' => 42)
));
 
// retourne: /a/42
$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');.

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

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

class My_Simple_Page extends Zend_Navigation_Page
{
    public function getHref()
    {
        return 'Quelquechose-ici--ce-que-je-veux';
    }
}

Example #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().

class My_Navigation_Page extends Zend_Navigation_Page
{
    private $_foo;
    private $_fooBar;
 
    public function setFoo($foo)
    {
        $this->_foo = $foo;
    }
 
    public function getFoo()
    {
        return $this->_foo;
    }
 
    public function setFooBar($fooBar)
    {
        $this->_fooBar = $fooBar;
    }
 
    public function getFooBar()
    {
        return $this->_fooBar;
    }
 
    public function getHref()
    {
        return $this->foo . '/' . $this->fooBar;
    }
}
 
// can now construct using
$page = new My_Navigation_Page(array(
    'label'   => 'Les noms des propriétés sont dirigés vers les setters',
    'foo'     => 'bar',
    'foo_bar' => 'baz'
));
 
// ...or
$page = Zend_Navigation_Page::factory(array(
    'type'    => 'My_Navigation_Page',
    'label'   => 'Les noms des propriétés sont dirigés vers les setters',
    'foo'     => 'bar',
    'foo_bar' => 'baz'
));

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.

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

$page = Zend_Navigation_Page::factory(array(
    'label'  => 'My MVC page',
    'action' => 'index'
));
 
$page = Zend_Navigation_Page::factory(array(
    'label'      => 'Search blog',
    'action'     => 'index',
    'controller' => 'search',
    'module'     => 'blog'
));
 
$page = Zend_Navigation_Page::factory(array(
    'label'      => 'Home',
    'action'     => 'index',
    'controller' => 'index',
    'module'     => 'index',
    'route'      => 'home'
));
 
$page = Zend_Navigation_Page::factory(array(
    'type'   => 'mvc',
    'label'  => 'My MVC page'
));

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

$page = Zend_Navigation_Page::factory(array(
    'label' => 'My URI page',
    'uri'   => 'http://www.example.com/'
));
 
$page = Zend_Navigation_Page::factory(array(
    'label'  => 'Search',
    'uri'    => 'http://www.example.com/search',
    'active' => true
));
 
$page = Zend_Navigation_Page::factory(array(
    'label' => 'My URI page',
    'uri'   => '#'
));
 
$page = Zend_Navigation_Page::factory(array(
    'type'   => 'uri',
    'label'  => 'My URI page'
));

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

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

class My_Navigation_Page extends Zend_Navigation_Page
{
    protected $_fooBar = 'ok';
 
    public function setFooBar($fooBar)
    {
        $this->_fooBar = $fooBar;
    }
}
 
$page = Zend_Navigation_Page::factory(array(
    'type'    => 'My_Navigation_Page',
    'label'   => 'My custom page',
    'foo_bar' => 'foo bar'
));