Closes ZF-7341: Added migration chapter to Zend_Navigation.

git-svn-id: http://framework.zend.com/svn/framework/standard/trunk@16981 44c647ce-9c0f-0410-b52a-842ac1e357ba

documentation/manual/en/manual.xml.in

@@ -360,6 +360,7 @@
         <xi:include href="module_specs/Zend_Navigation-Introduction.xml" />
         <xi:include href="module_specs/Zend_Navigation-Pages.xml" />
         <xi:include href="module_specs/Zend_Navigation-Containers.xml" />
+        <xi:include href="module_specs/Zend_Navigation-Migration.xml" />
     </chapter>
 
     <chapter id="zend.openid">

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

@@ -0,0 +1,99 @@
+<?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>