repo_zf1/documentation/manual/en/module_specs/Zend_Navigation-Pages-MVC.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.navigation.pages.mvc">
    <title>Zend_Navigation_Page_Mvc</title>

    <para>
        <acronym>MVC</acronym> pages are defined using <acronym>MVC</acronym> parameters known from
        the <classname>Zend_Controller</classname> component. An <acronym>MVC</acronym> page will
        use <classname>Zend_Controller_Action_Helper_Url</classname> internally
        in the <methodname>getHref()</methodname> method to generate hrefs, and
        the <methodname>isActive()</methodname> method will intersect the
        <classname>Zend_Controller_Request_Abstract</classname> params
        with the page's params to determine if the page is active.
    </para>

    <table id="zend.navigation.pages.mvc.options">
        <title>MVC page options</title>

        <tgroup cols="4">
            <thead>
                <row>
                    <entry>Key</entry>
                    <entry>Type</entry>
                    <entry>Default</entry>
                    <entry>Description</entry>
                </row>
            </thead>

            <tbody>
                <row>
                    <entry><code>action</code></entry>
                    <entry><type>String</type></entry>
                    <entry><constant>NULL</constant></entry>
                    <entry>Action name to use when generating href to the page.</entry>
                </row>

                <row>
                    <entry><code>controller</code></entry>
                    <entry><type>String</type></entry>
                    <entry><constant>NULL</constant></entry>
                    <entry>Controller name to use when generating href to the page.</entry>
                </row>

                <row>
                    <entry><code>module</code></entry>
                    <entry><type>String</type></entry>
                    <entry><constant>NULL</constant></entry>
                    <entry>Module name to use when generating href to the page.</entry>
                </row>

                <row>
                    <entry><code>params</code></entry>
                    <entry><type>Array</type></entry>
                    <entry><methodname>array()</methodname></entry>
                    <entry>User params to use when generating href to the page.</entry>
                </row>
                <row>
                    <entry><code>route</code></entry>
                    <entry><type>String</type></entry>
                    <entry><constant>NULL</constant></entry>
                    <entry>Route name to use when generating href to the page.</entry>
                </row>
                <row>
                    <entry><code>reset_params</code></entry>
                    <entry><code>bool</code></entry>
                    <entry><constant>TRUE</constant></entry>

                    <entry>
                        Whether user params should be reset when generating href to the page.
                    </entry>
                </row>
                <row>
                    <entry><code>encode_url</code></entry>
                    <entry><code>bool</code></entry>
                    <entry><constant>TRUE</constant></entry>

                    <entry>
                        Whether href should be encoded when assembling URL.
                    </entry>
                </row>
            </tbody>
        </tgroup>
    </table>

    <note>
        <para>
            The three examples below assume a default <acronym>MVC</acronym> setup with
            the <code>default</code> route in place.
        </para>

        <para>
            The <acronym>URI</acronym> returned is relative to the <code>baseUrl</code> in
            <classname>Zend_Controller_Front</classname>. In the examples, the baseUrl
            is '/' for simplicity.
        </para>
    </note>

    <example id="zend.navigation.pages.mvc.example.getHref">
        <title>getHref() generates the page URI</title>

        <para>
            This example shows that <acronym>MVC</acronym> pages use
            <classname>Zend_Controller_Action_Helper_Url</classname> internally
            to generate <acronym>URI</acronym>s when calling <code>$page->getHref()</code>.
        </para>

        <programlisting language="php"><![CDATA[
// 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)
));
]]></programlisting>
    </example>

    <example id="zend.navigation.pages.mvc.example.isActive">
        <title>isActive() determines if page is active</title>

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

        <programlisting language="php"><![CDATA[
/*
 * 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
]]></programlisting>
    </example>

    <example id="zend.navigation.pages.mvc.example.routes">
        <title>Using routes</title>

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

        <para>
            <note>
                <para>
                    Note that when using the <code>route</code> property in a
                    page, you should also specify the default params that the
                    route defines (module, controller, action, etc.), otherwise
                    the <methodname>isActive()</methodname> method will not be able to
                    determine if the page is active. The reason for this is that
                    there is currently no way to get the default params from a
                    <classname>Zend_Controller_Router_Route_Interface</classname> object,
                    nor to retrieve the current route from a
                    <classname>Zend_Controller_Router_Interface</classname> object.
                </para>
            </note>
        </para>

        <programlisting language="php"><![CDATA[
// 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();
]]></programlisting>
    </example>

    <example id="zend.navigation.pages.mvc.example.setparams">
        <title>Set parameters to use when assembling URL</title>

        <programlisting language="php">
// 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();
        </programlisting>
    </example>
</sect2>