ZF-11720: Update Zend_Navigation documentation

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

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

@@ -794,33 +794,45 @@ $container = new Zend_Navigation();
 
 // add page by giving a page instance
 $container->addPage(Zend_Navigation_Page::factory(array(
-    'uri' => 'http://www.example.com/'
-)))
+    'uri' => 'http://www.example.com/',
+)));
 
 // add page by giving an array
 $container->addPage(array(
-    'uri' => 'http://www.example.com/'
-)))
+    'uri' => 'http://www.example.com/',
+));
 
 // add page by giving a config object
 $container->addPage(new Zend_Config(array(
-    'uri' => 'http://www.example.com/'
-)))
+    'uri' => 'http://www.example.com/',
+)));
 
 $pages = array(
     array(
-        'label'  => 'Save'
+        'label'  => 'Save',
         'action' => 'save',
     ),
     array(
-        'label' =>  'Delete',
-        'action' => 'delete'
-    )
+        'label'  => 'Delete',
+        'action' => 'delete',
+    ),
 );
 
 // add two pages
 $container->addPages($pages);
 
+// add container
+$container->addPages(new Zend_Navigation(array(
+    array(
+        'label'  => 'Move up',
+        'action' => 'up',
+    ),
+    array(
+        'label'  => 'Move down',
+        'action' => 'down',
+    ),
+)));
+
 // remove existing pages and add the given pages
 $container->setPages($pages);
 ]]></programlisting>
@@ -879,11 +891,13 @@ $container->removePages();      // removes all pages
 
         <para>
             Containers have finder methods for retrieving pages.
-            They are <methodname>findOneBy($property, $value)</methodname>,
-            <methodname>findAllBy($property, $value)</methodname>, and
-            <methodname>findBy($property, $value, $all = false)</methodname>.
+            They are <methodname>findOneBy($property, $value, $useRegex = false)</methodname>,
+            <methodname>findAllBy($property, $value, $useRegex = false)</methodname>, and
+            <methodname>findBy($property, $value, $all = false, $useRegex = false)</methodname>.
             Those methods will recursively search the container for
-            pages matching the given <command>$page->$property == $value</command>.
+            pages matching the given <command>$page->$property == $value</command>
+            or when regular expressions are used: 
+            <command>preg_match($value, $page->$property)</command>.
             The first method, <methodname>findOneBy()</methodname>, will return a
             single page matching the property with the given value, or
             <constant>NULL</constant> if it cannot be found. The second method will return
@@ -951,24 +965,19 @@ $container = new Zend_Navigation(array(
 // The 'id' is not required to be unique, but be aware that
 // having two pages with the same id will render the same id attribute
 // in menus and breadcrumbs.
-$found = $container->findBy('id',
-                            'page_2_and_3');      // returns Page 2
-$found = $container->findOneBy('id',
-                               'page_2_and_3');   // returns Page 2
-$found = $container->findBy('id',
-                            'page_2_and_3',
-                            true);                // returns Page 2 and Page 3
-$found = $container->findById('page_2_and_3');    // returns Page 2
+$found = $container->findBy('id', 'page_2_and_3'); // returns Page 2
+$found = $container->findOneBy('id', 'page_2_and_3'); // returns Page 2
+$found = $container->findBy('id', 'page_2_and_3', true); // returns Page 2 and Page 3
+$found = $container->findById('page_2_and_3'); // returns Page 2
 $found = $container->findOneById('page_2_and_3'); // returns Page 2
 $found = $container->findAllById('page_2_and_3'); // returns Page 2 and Page 3
 
 // Find all matching CSS class my-class
-$found = $container->findAllBy('class',
-                               'my-class');       // returns Page 1.2 and Page 2
+$found = $container->findAllBy('class', 'my-class'); // returns Page 1.2 and Page 2
 $found = $container->findAllByClass('my-class');  // returns Page 1.2 and Page 2
 
 // Find first matching CSS class my-class
-$found = $container->findOneByClass('my-class');  // returns Page 1.2
+$found = $container->findOneByClass('my-class'); // returns Page 1.2
 
 // Find all matching CSS class non-existant
 $found = $container->findAllByClass('non-existant'); // returns array()
@@ -987,6 +996,19 @@ $found = $container->findAllByfoo('bar');
 // Find all with controller = 'index'
 $found = $container->findAllByController('index'); // returns Page 2 and Page 3
 ]]></programlisting>
+
+            <para>
+                Use regular expressions to find pages:
+            </para>
+            
+            <programlisting language="php"><![CDATA[
+$found = $container->findBy('class','/my/', false, true); // returns Page 1.2
+$found = $container->findOneBy('class', '/my/', true); // returns Page 1.2
+$found = $container->findBy('class', '/my/', true, true); // returns Page 1.2 and Page 2
+$found = $container->findAllBy('class', '/my/', true); // returns Page 1.2 and Page 2
+$found = $container->findOneByClass('/my/', true); // returns Page 1.2
+$found = $container->findAllByClass('/my/', true); // returns Page 1.2 and Page 2
+]]></programlisting>
         </example>
     </sect2>
 

documentation/manual/en/module_specs/Zend_Navigation-Pages-Common.xml

@@ -89,6 +89,32 @@
                 </row>
 
                 <row>
+                    <entry><code>accesskey</code></entry>
+                    <entry><type>String</type></entry>
+                    <entry><constant>NULL</constant></entry>
+
+                    <entry>
+                        This attribute assigns an access key to an <code>A</code> element.
+                        An access key is a single character from the document character set.
+                    </entry>
+                </row>
+
+                <row>
+                    <entry><code>fragment</code></entry>
+                    <entry><type>String</type></entry>
+                    <entry><constant>NULL</constant></entry>
+
+                    <entry>
+                        The fragment identifier (anchor identifier) pointing to 
+                        an anchor within a resource that is subordinate to another, 
+                        primary resource. The fragment identifier introduced by 
+                        a hash mark '#'.
+                        Example: http://www.example.org/foo.html#bar 
+                        ('bar' is the fragment identifier)
+                    </entry>
+                </row>
+
+                <row>
                     <entry><code>rel</code></entry>
                     <entry><type>Array</type></entry>
                     <entry><methodname>array()</methodname></entry>

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

@@ -69,6 +69,15 @@
                         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>
@@ -235,4 +244,67 @@ $page = new Zend_Navigation_Page_Mvc(array(
 $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>

documentation/manual/en/module_specs/Zend_View-Helpers-Navigation.xml

@@ -1249,6 +1249,13 @@ Output:
 
             <listitem>
                 <para>
+                    <code>{get|set}ActiveClass()</code> gets/sets the <acronym>CSS</acronym> class
+                    for the active elements when rendering.
+                </para>
+            </listitem>
+
+            <listitem>
+                <para>
                     <code>{get|set}OnlyActiveBranch()</code> gets/sets a flag
                     specifying whether only the active branch of a container
                     should be rendered.
@@ -1357,6 +1364,14 @@ Output:
 
                     <listitem>
                         <para>
+                            <code>activeClass</code>; <acronym>CSS</acronym> class for
+                            for the active elements when rendering. Expects a
+                            <type>String</type>.
+                        </para>
+                    </listitem>
+
+                    <listitem>
+                        <para>
                             <code>onlyActiveBranch</code>; whether only
                             active branch should be rendered. Expects
                             a <type>Boolean</type> value.