repo_zf1/documentation/manual/en/module_specs/Zend_Navigation-Migration.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.navigation.migration">
    <title>Migrating from Previous Versions</title>

    <para>
        This chapter documents primarily backwards compatibility breaks made in
        Zend_Navigation and Zend_View_Helper_Navigation, and should serve to aid
        in migration from previous versions.
    </para>

    <sect2 id="zend.view.navigation.zf7341">
        <title>Migrating from versions prior to 1.9</title>
        
        <para>
            Prior to the 1.9 release, the menu helper 
            (<classname>Zend_View_Helper_Navigation_Menu</classname>) did not
            render sub menus correctly. When the <code>onlyActiveBranch</code>
            was <code>true</code> and the option <code>renderParents</code>
            <code>false</code>, nothing would be rendered if the deepest active
            page was at a depth lower than the <code>minDepth</code> option. 
        </para>
        
        <para>
            In simpler words; if <code>minDepth</code> was set to <code>1</code>
            and the active page was at one of the first level pages, nothing
            would be rendered, as the following example shows.
        </para>
        
        <para>
            Consider the following container setup:
        </para>

        <programlisting language="php"><![CDATA[
<?php
$container = new Zend_Navigation(array(
    array(
        'label' => 'Home',
        'uri'   => '#'
    ),
    array(
        'label'  => 'Products',
        'uri'    => '#',
        'active' => true,
        'pages'  => array(
            array(
                'label' => 'Server',
                'uri'   => '#'
            ),
            array(
                'label' => 'Studio',
                'uri'   => '#'
            )
        )
    ),
    array(
        'label' => 'Solutions',
        'uri'   => '#'
    )
));
]]></programlisting>

        <para>
            The following code is used in a view script:
        </para>

        <programlisting language="php"><![CDATA[
<?php echo $this->navigation()->menu()->renderMenu($container, array(
    'minDepth'         => 1,
    'onlyActiveBranch' => true,
    'renderParents'    => false
)); ?>]]></programlisting>

        <para>
            Before release 1.9, the code snippet above would output nothing.
        </para>

        <para>
            Since release 1.9, the <code>_renderDeepestMenu()</code> method in 
            <classname>Zend_View_Helper_Navigation_Menu</classname> will accept
            active pages at one level below <code>minDepth</code>, as long as 
            the page has children. 
        </para>
        
        <para>
            The same code snippet will now output the following:
        </para>

        <programlisting language="html"><![CDATA[
<ul class="navigation">
    <li>
        <a href="#">Server</a>
    </li>
    <li>
        <a href="#">Studio</a>
    </li>
</ul>]]></programlisting>
    </sect2>
</sect1>