This example shows how custom properties can be used.

$page = new Zend_Navigation_Page_Mvc();
$page->foo = 'bar';
$page->meaning = 42;

echo $page->foo;

if ($page->meaning != 42) {
    // action should be taken
}

This example shows that MVC pages use Zend_Controller_Action_Helper_Url internally to generate URIs when calling $page->getHref().

// getHref() returns /
$page = new Zend_Navigation_Page_Mvc(array(
    'action'     => 'index',
    'controller' => 'index'
));

// getHref() returns /blog/post/view
$page = new Zend_Navigation_Page_Mvc(array(
    'action'     => 'view',
    'controller' => 'post',
    'module'     => 'blog'
));

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

This example shows that MVC pages determine whether they are active by using the params found in the request object.

/*
 * Dispatched request:
 * - 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(); // returns true
$page2->isActive(); // returns false

/*
 * Dispatched request:
 * - module:     blog
 * - controller: post
 * - action:     view
 * - id:         1337
 */
$page = new Zend_Navigation_Page_Mvc(array(
    'action'     => 'view',
    'controller' => 'post',
    'module'     => 'blog'
));

// returns true, because request has the same module, controller and action
$page->isActive();

/*
 * Dispatched request:
 * - module:     blog
 * - controller: post
 * - action:     view
 */
$page = new Zend_Navigation_Page_Mvc(array(
    'action'     => 'view',
    'controller' => 'post',
    'module'     => 'blog',
    'params'     => array('id' => null)
));

// returns false, because page requires the id param to be set in the request
$page->isActive(); // returns false

Routes can be used with MVC pages. If a page has a route, this route will be used in getHref() to generate the URL for the page.

// the following route is added to the ZF router
Zend_Controller_Front::getInstance()->getRouter()->addRoute(
    'article_view', // route name
    new Zend_Controller_Router_Route(
        'a/:id',
        array(
            'module'     => 'news',
            'controller' => 'article',
            'action'     => 'view',
            'id'         => null
        )
    )
);

// a page is created with a 'route' option
$page = new Zend_Navigation_Page_Mvc(array(
    'label'      => 'A news article',
    'route'      => 'article_view',
    'module'     => 'news',    // required for isActive(), see note above
    'controller' => 'article', // required for isActive(), see note above
    'action'     => 'view',    // required for isActive(), see note above
    'params'     => array('id' => 42)
));

// returns: /a/42
$page->getHref();

// The following route is added to the ZF router
Zend_Controller_Front::getInstance()->getRouter()->addRoute(
    'article_list', // route name
    new Zend_Controller_Router_Route(
        'blog/:category/:page',
        array(
            'module'     => 'blog',
            'controller' => 'article',
            'action'     => 'list',
            'category'   => null,
            'page'       => null,
        )
    )
);

// A page is created with the 'route' option
$page = new Zend_Navigation_Page_Mvc(array(
    'label'      => 'Article list',
    'module'     => 'blog',
    'controller' => 'post',
    'action'     => 'list',
));

// Add multiple parameters at once
$page->addParams(
    array(
        'category' => 'news',
        'page'     => 1,
    )
);

// Add a single parameter
$page->addParam('category', 'news');

// Set multiple parameters at once (Overwrites any previously set parameters!)
$page->setParams(
    array(
        'category' => 'news',
        'page'     => 1,
    )
);

// Set a single parameter
$page->setParam('category', 'news');

// Retrieve all parameters
$params = $page->getParams();

// Retrieve a single parameter
$category = $page->getParam('category');

// Remove a parameter
$page->removeParam('page');

// Clear all parameters
$page->clearParams();
        

The only thing a custom page class needs to implement is the getHref() method.

class My_Simple_Page extends Zend_Navigation_Page
{
    public function getHref()
    {
        return 'something-completely-different';
    }
}

When adding properties to an extended page, there is no need to override/modify setOptions() or 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'   => 'Property names are mapped to setters',
    'foo'     => 'bar',
    'foo_bar' => 'baz'
));

// ...or
$page = Zend_Navigation_Page::factory(array(
    'type'    => 'My_Navigation_Page',
    'label'   => 'Property names are mapped to setters',
    'foo'     => 'bar',
    'foo_bar' => 'baz'
));

$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'
));

$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'
));

To create a custom page type using the factory, use the option type to specify a class name to instantiate.

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'
));