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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect3 id="zend.view.helpers.initial.navigation">
   4     <title>Navigation Helpers</title>
   5
   6     <para>
   7         The navigation helpers are used for rendering navigational elements
   8         from <link linkend="zend.navigation.containers">Zend_Navigation_Container</link>
   9         instances.
  10     </para>
  11
  12     <para>
  13         There are 5 built-in helpers:
  14     </para>
  15
  16     <itemizedlist>
  17         <listitem>
  18             <para>
  19                 <link
  20                     linkend="zend.view.helpers.initial.navigation.breadcrumbs">Breadcrumbs</link>,
  21                 used for rendering the path to the currently active page.
  22             </para>
  23         </listitem>
  24
  25         <listitem>
  26             <para>
  27                 <link linkend="zend.view.helpers.initial.navigation.links">Links</link>,
  28                 used for rendering navigational head links (e.g.
  29                 <command>&lt;link rel="next" href="..." /&gt;</command>)
  30             </para>
  31         </listitem>
  32
  33         <listitem>
  34             <para>
  35                 <link linkend="zend.view.helpers.initial.navigation.menu">Menu</link>,
  36                 used for rendering menus.
  37             </para>
  38         </listitem>
  39
  40         <listitem>
  41             <para>
  42                 <link linkend="zend.view.helpers.initial.navigation.sitemap">Sitemap</link>,
  43                 used for rendering sitemaps conforming to the <ulink
  44                     url="http://www.sitemaps.org/protocol.php">Sitemaps <acronym>XML</acronym>
  45                     format</ulink>.
  46             </para>
  47         </listitem>
  48
  49         <listitem>
  50             <para>
  51                 <link
  52                     linkend="zend.view.helpers.initial.navigation.navigation">Navigation</link>,
  53                 used for proxying calls to other navigational helpers.
  54             </para>
  55         </listitem>
  56     </itemizedlist>
  57
  58     <para>
  59         All built-in helpers extend
  60         <classname>Zend_View_Helper_Navigation_HelperAbstract</classname>, which
  61         adds integration with <link linkend="zend.acl">ACL</link> and
  62         <link linkend="zend.translate">translation</link>. The abstract class
  63         implements the interface
  64         <classname>Zend_View_Helper_Navigation_Helper</classname>, which
  65         defines the following methods:
  66     </para>
  67
  68     <itemizedlist>
  69         <listitem>
  70             <para>
  71                 <methodname>getContainer()</methodname> and <methodname>setContainer()</methodname>
  72                 gets and sets the navigation container the helper should operate on by default, and
  73                 <methodname>hasContainer()</methodname> checks if the helper
  74                 has container registered.
  75             </para>
  76         </listitem>
  77
  78         <listitem>
  79             <para>
  80                 <methodname>getTranslator()</methodname> and
  81                 <methodname>setTranslator()</methodname> gets and sets the
  82                 translator used for translating labels and titles.
  83                 <methodname>getUseTranslator()</methodname> and
  84                 <methodname>setUseTranslator()</methodname> controls whether
  85                 the translator should be enabled. The method
  86                 <methodname>hasTranslator()</methodname> checks if the helper has
  87                 a translator registered.
  88             </para>
  89         </listitem>
  90
  91         <listitem>
  92             <para>
  93                 <methodname>getAcl()</methodname>, <methodname>setAcl()</methodname>,
  94                 <methodname>getRole()</methodname> and <methodname>setRole()</methodname>,
  95                 gets and sets <acronym>ACL</acronym> (<classname>Zend_Acl</classname>) instance and
  96                 role (<type>String</type> or
  97                 <classname>Zend_Acl_Role_Interface</classname>) used for
  98                 filtering out pages when rendering. <methodname>getUseAcl()</methodname> and
  99                 <methodname>setUseAcl()</methodname> controls whether <acronym>ACL</acronym> should
 100                 be enabled. The methods <methodname>hasAcl()</methodname> and
 101                 <methodname>hasRole()</methodname> checks if the helper has an
 102                 <acronym>ACL</acronym> instance or a role registered.
 103             </para>
 104         </listitem>
 105
 106         <listitem>
 107             <para>
 108                 <methodname>__toString()</methodname>, magic method to ensure that
 109                 helpers can be rendered by echoing the helper instance directly.
 110             </para>
 111         </listitem>
 112
 113         <listitem>
 114             <para>
 115                 <methodname>render()</methodname>, must be implemented by concrete
 116                 helpers to do the actual rendering.
 117             </para>
 118         </listitem>
 119      </itemizedlist>
 120
 121     <para>
 122          In addition to the method stubs from the interface, the abstract
 123          class also implements the following methods:
 124     </para>
 125
 126      <itemizedlist>
 127         <listitem>
 128             <para>
 129                 <methodname>getIndent()</methodname> and <methodname>setIndent()</methodname>
 130                 gets and sets indentation. The setter accepts a <type>String</type> or an
 131                 <type>Integer</type>. In the case of an <type>Integer</type>, the helper will use
 132                 the given number of spaces for indentation. I.e.,
 133                 <methodname>setIndent(4)</methodname> means 4 initial spaces of
 134                 indentation. Indentation can be specified for all helpers
 135                 except the Sitemap helper.
 136             </para>
 137         </listitem>
 138
 139         <listitem>
 140             <para>
 141                 <methodname>getMinDepth()</methodname> and <methodname>setMinDepth()</methodname>
 142                 gets and sets the minimum depth a page must have to be included by the helper.
 143                 Setting <constant>NULL</constant> means no minimum depth.
 144             </para>
 145         </listitem>
 146
 147         <listitem>
 148             <para>
 149                 <methodname>getMaxDepth()</methodname> and <methodname>setMaxDepth()</methodname>
 150                 gets and sets the maximum depth a page can have to be included by the helper.
 151                 Setting <constant>NULL</constant> means no maximum depth.
 152             </para>
 153         </listitem>
 154
 155         <listitem>
 156             <para>
 157                 <methodname>getRenderInvisible()</methodname> and
 158                 <methodname>setRenderInvisible()</methodname> gets and sets whether to
 159                 render items that have been marked as invisible or not.
 160             </para>
 161         </listitem>
 162
 163         <listitem>
 164             <para>
 165                 <methodname>__call()</methodname> is used for proxying calls to the
 166                 container registered in the helper, which means you can
 167                 call methods on a helper as if it was a container. See <link
 168                     linkend="zend.view.helpers.initial.navigation.proxy.example">example</link>
 169                 below.
 170             </para>
 171         </listitem>
 172
 173         <listitem>
 174             <para>
 175                 <methodname>findActive($container, $minDepth, $maxDepth)</methodname>
 176                 is used for finding the deepest active page in the given
 177                 container. If depths are not given, the method will use
 178                 the values retrieved from <methodname>getMinDepth()</methodname> and
 179                 <methodname>getMaxDepth()</methodname>. The deepest active page must
 180                 be between <varname>$minDepth</varname> and <varname>$maxDepth</varname>
 181                 inclusively. Returns an array containing a reference to the
 182                 found page instance and the depth at which the page was
 183                 found.
 184             </para>
 185         </listitem>
 186
 187         <listitem>
 188             <para>
 189                 <methodname>htmlify()</methodname> renders an <emphasis>'a'</emphasis>
 190                 <acronym>HTML</acronym> element from a <classname>Zend_Navigation_Page</classname>
 191                 instance.
 192             </para>
 193         </listitem>
 194
 195         <listitem>
 196             <para>
 197                 <methodname>accept()</methodname> is used for determining if a page
 198                 should be accepted when iterating containers. This method
 199                 checks for page visibility and verifies that the helper's
 200                 role is allowed access to the page's resource and privilege.
 201             </para>
 202         </listitem>
 203
 204         <listitem>
 205             <para>
 206                 The static method <methodname>setDefaultAcl()</methodname> is used for setting
 207                 a default <acronym>ACL</acronym> object that will be used by helpers.
 208             </para>
 209         </listitem>
 210
 211         <listitem>
 212             <para>
 213                 The static method <methodname>setDefaultRole()</methodname> is used for setting
 214                 a default <acronym>ACL</acronym> that will be used by helpers
 215             </para>
 216         </listitem>
 217     </itemizedlist>
 218
 219     <para>
 220         If a navigation container is not explicitly set in a helper using
 221         <command>$helper->setContainer($nav)</command>, the helper will look
 222         for a container instance with the key <classname>Zend_Navigation</classname> in
 223         <link linkend="zend.registry">the registry</link>.
 224         If a container is not explicitly set or found in the registry, the
 225         helper will create an empty <classname>Zend_Navigation</classname>
 226         container when calling <command>$helper->getContainer()</command>.
 227     </para>
 228
 229     <example id="zend.view.helpers.initial.navigation.proxy.example">
 230         <title>Proxying calls to the navigation container</title>
 231
 232         <para>
 233             Navigation view helpers use the magic method <methodname>__call()</methodname>
 234             to proxy method calls to the navigation container that is
 235             registered in the view helper.
 236         </para>
 237
 238         <programlisting language="php"><![CDATA[
 239 $this->navigation()->addPage(array(
 240     'type' => 'uri',
 241     'label' => 'New page'));
 242 ]]></programlisting>
 243
 244         <para>
 245             The call above will add a page to the container in the
 246             <classname>Navigation</classname> helper.
 247         </para>
 248     </example>
 249
 250     <sect4 id="zend.view.helpers.initial.navigation.i18n">
 251         <title>Translation of labels and titles</title>
 252
 253         <para>
 254             The navigation helpers support translation of page labels and titles.
 255             You can set a translator of type <classname>Zend_Translate</classname>
 256             or <classname>Zend_Translate_Adapter</classname> in the helper using
 257             <command>$helper->setTranslator($translator)</command>, or like with other
 258             I18n-enabled components; by adding the translator to
 259             <link linkend="zend.registry">the registry</link> by using the key
 260             <classname>Zend_Translate</classname>.
 261         </para>
 262
 263         <para>
 264             If you want to disable translation, use
 265             <command>$helper->setUseTranslator(false)</command>.
 266         </para>
 267
 268         <para>
 269             The
 270             <link linkend="zend.view.helpers.initial.navigation.navigation">proxy
 271             helper</link> will inject its own translator to the helper it
 272             proxies to if the proxied helper doesn't already have a translator.
 273         </para>
 274
 275         <note>
 276             <para>
 277                 There is no translation in the sitemap helper, since there
 278                 are no page labels or titles involved in an <acronym>XML</acronym> sitemap.
 279             </para>
 280         </note>
 281     </sect4>
 282
 283     <sect4 id="zend.view.helpers.initial.navigation.acl">
 284         <title>Integration with ACL</title>
 285
 286         <para>
 287             All navigational view helpers support <acronym>ACL</acronym> inherently from the
 288             class <classname>Zend_View_Helper_Navigation_HelperAbstract</classname>.
 289             A <classname>Zend_Acl</classname> object can be assigned to
 290             a helper instance with <code>$helper->setAcl($acl)</code>, and role
 291             with <code>$helper->setRole('member')</code> or
 292             <code>$helper->setRole(new Zend_Acl_Role('member'))</code> . If <acronym>ACL</acronym>
 293             is used in the helper, the role in the helper must be allowed by
 294             the <acronym>ACL</acronym> to access a page's <code>resource</code> and/or have the
 295             page's <code>privilege</code> for the page to be included when
 296             rendering.
 297         </para>
 298
 299         <para>
 300             If a page is not accepted by <acronym>ACL</acronym>, any descendant page will also
 301             be excluded from rendering.
 302         </para>
 303
 304         <para>
 305             The
 306             <link linkend="zend.view.helpers.initial.navigation.navigation">proxy
 307             helper</link> will inject its own <acronym>ACL</acronym> and role to the helper it
 308             proxies to if the proxied helper doesn't already have any.
 309         </para>
 310
 311         <para>
 312             The examples below all show how <acronym>ACL</acronym> affects rendering.
 313         </para>
 314     </sect4>
 315
 316     <sect4 id="zend.view.helpers.initial.navigation.setup">
 317         <title>Navigation setup used in examples</title>
 318
 319         <para>
 320             This example shows the setup of a navigation container for a
 321             fictional software company.
 322         </para>
 323
 324         <para>
 325             Notes on the setup:
 326         </para>
 327
 328         <itemizedlist>
 329             <listitem>
 330                 <para>
 331                     The domain for the site is <code>www.example.com</code>.
 332                 </para>
 333             </listitem>
 334
 335             <listitem>
 336                 <para>
 337                     Interesting page properties are marked with a comment.
 338                 </para>
 339             </listitem>
 340
 341             <listitem>
 342                 <para>
 343                     Unless otherwise is stated in other examples, the user
 344                     is requesting the <acronym>URL</acronym>
 345                     <code>http://www.example.com/products/server/faq/</code>,
 346                     which translates to the page labeled <constant>FAQ</constant>
 347                     under <code>Foo Server</code>.
 348                 </para>
 349             </listitem>
 350
 351             <listitem>
 352                 <para>
 353                     The assumed <acronym>ACL</acronym> and router setup is shown below the
 354                     container setup.
 355                 </para>
 356             </listitem>
 357         </itemizedlist>
 358
 359         <programlisting language="php"><![CDATA[
 360 /*
 361  * Navigation container (config/array)
 362
 363  * Each element in the array will be passed to
 364  * Zend_Navigation_Page::factory() when constructing
 365  * the navigation container below.
 366  */
 367 $pages = array(
 368     array(
 369         'label'      => 'Home',
 370         'title'      => 'Go Home',
 371         'module'     => 'default',
 372         'controller' => 'index',
 373         'action'     => 'index',
 374         'order'      => -100 // make sure home is the first page
 375     ),
 376     array(
 377         'label'      => 'Special offer this week only!',
 378         'module'     => 'store',
 379         'controller' => 'offer',
 380         'action'     => 'amazing',
 381         'visible'    => false // not visible
 382     ),
 383     array(
 384         'label'      => 'Products',
 385         'module'     => 'products',
 386         'controller' => 'index',
 387         'action'     => 'index',
 388         'pages'      => array(
 389             array(
 390                 'label'      => 'Foo Server',
 391                 'module'     => 'products',
 392                 'controller' => 'server',
 393                 'action'     => 'index',
 394                 'pages'      => array(
 395                     array(
 396                         'label'      => 'FAQ',
 397                         'module'     => 'products',
 398                         'controller' => 'server',
 399                         'action'     => 'faq',
 400                         'rel'        => array(
 401                             'canonical' => 'http://www.example.com/?page=faq',
 402                             'alternate' => array(
 403                                 'module'     => 'products',
 404                                 'controller' => 'server',
 405                                 'action'     => 'faq',
 406                                 'params'     => array('format' => 'xml')
 407                             )
 408                         )
 409                     ),
 410                     array(
 411                         'label'      => 'Editions',
 412                         'module'     => 'products',
 413                         'controller' => 'server',
 414                         'action'     => 'editions'
 415                     ),
 416                     array(
 417                         'label'      => 'System Requirements',
 418                         'module'     => 'products',
 419                         'controller' => 'server',
 420                         'action'     => 'requirements'
 421                     )
 422                 )
 423             ),
 424             array(
 425                 'label'      => 'Foo Studio',
 426                 'module'     => 'products',
 427                 'controller' => 'studio',
 428                 'action'     => 'index',
 429                 'pages'      => array(
 430                     array(
 431                         'label'      => 'Customer Stories',
 432                         'module'     => 'products',
 433                         'controller' => 'studio',
 434                         'action'     => 'customers'
 435                     ),
 436                     array(
 437                         'label'      => 'Support',
 438                         'module'     => 'prodcts',
 439                         'controller' => 'studio',
 440                         'action'     => 'support'
 441                     )
 442                 )
 443             )
 444         )
 445     ),
 446     array(
 447         'label'      => 'Company',
 448         'title'      => 'About us',
 449         'module'     => 'company',
 450         'controller' => 'about',
 451         'action'     => 'index',
 452         'pages'      => array(
 453             array(
 454                 'label'      => 'Investor Relations',
 455                 'module'     => 'company',
 456                 'controller' => 'about',
 457                 'action'     => 'investors'
 458             ),
 459             array(
 460                 'label'      => 'News',
 461                 'class'      => 'rss', // class
 462                 'module'     => 'company',
 463                 'controller' => 'news',
 464                 'action'     => 'index',
 465                 'pages'      => array(
 466                     array(
 467                         'label'      => 'Press Releases',
 468                         'module'     => 'company',
 469                         'controller' => 'news',
 470                         'action'     => 'press'
 471                     ),
 472                     array(
 473                         'label'      => 'Archive',
 474                         'route'      => 'archive', // route
 475                         'module'     => 'company',
 476                         'controller' => 'news',
 477                         'action'     => 'archive'
 478                     )
 479                 )
 480             )
 481         )
 482     ),
 483     array(
 484         'label'      => 'Community',
 485         'module'     => 'community',
 486         'controller' => 'index',
 487         'action'     => 'index',
 488         'pages'      => array(
 489             array(
 490                 'label'      => 'My Account',
 491                 'module'     => 'community',
 492                 'controller' => 'account',
 493                 'action'     => 'index',
 494                 'resource'   => 'mvc:community.account' // resource
 495             ),
 496             array(
 497                 'label' => 'Forums',
 498                 'uri'   => 'http://forums.example.com/',
 499                 'class' => 'external' // class
 500             )
 501         )
 502     ),
 503     array(
 504         'label'      => 'Administration',
 505         'module'     => 'admin',
 506         'controller' => 'index',
 507         'action'     => 'index',
 508         'resource'   => 'mvc:admin', // resource
 509         'pages'      => array(
 510             array(
 511                 'label'      => 'Write new article',
 512                 'module'     => 'admin',
 513                 'controller' => 'post',
 514                 'aciton'     => 'write'
 515             )
 516         )
 517     )
 518 );
 519
 520 // Create container from array
 521 $container = new Zend_Navigation($pages);
 522
 523 // Store the container in the proxy helper:
 524 $view->getHelper('navigation')->setContainer($container);
 525
 526 // ...or simply:
 527 $view->navigation($container);
 528
 529 // ...or store it in the reigstry:
 530 Zend_Registry::set('Zend_Navigation', $container);
 531 ]]></programlisting>
 532
 533         <para>
 534             In addition to the container above, the following setup is assumed:
 535         </para>
 536
 537         <programlisting language="php"><![CDATA[
 538 // Setup router (default routes and 'archive' route):
 539 $front = Zend_Controller_Front::getInstance();
 540 $router = $front->getRouter();
 541 $router->addDefaultRoutes();
 542 $router->addRoute(
 543     'archive',
 544     new Zend_Controller_Router_Route(
 545         '/archive/:year',
 546         array(
 547             'module'     => 'company',
 548             'controller' => 'news',
 549             'action'     => 'archive',
 550             'year'       => (int) date('Y') - 1
 551         ),
 552         array('year' => '\d+')
 553     )
 554 );
 555
 556 // Setup ACL:
 557 $acl = new Zend_Acl();
 558 $acl->addRole(new Zend_Acl_Role('member'));
 559 $acl->addRole(new Zend_Acl_Role('admin'));
 560 $acl->add(new Zend_Acl_Resource('mvc:admin'));
 561 $acl->add(new Zend_Acl_Resource('mvc:community.account'));
 562 $acl->allow('member', 'mvc:community.account');
 563 $acl->allow('admin', null);
 564
 565 // Store ACL and role in the proxy helper:
 566 $view->navigation()->setAcl($acl)->setRole('member');
 567
 568 // ...or set default ACL and role statically:
 569 Zend_View_Helper_Navigation_HelperAbstract::setDefaultAcl($acl);
 570 Zend_View_Helper_Navigation_HelperAbstract::setDefaultRole('member');
 571 ]]></programlisting>
 572     </sect4>
 573
 574     <sect4 id="zend.view.helpers.initial.navigation.breadcrumbs">
 575         <title>Breadcrumbs Helper</title>
 576
 577         <para>
 578             Breadcrumbs are used for indicating where in a sitemap
 579             a user is currently browsing, and are typically rendered
 580             like this: "You are here: Home > Products > FantasticProduct 1.0".
 581             The breadcrumbs helper follows the guidelines from <ulink
 582                 url="http://developer.yahoo.com/ypatterns/pattern.php?pattern=breadcrumbs">Breadcrumbs
 583                 Pattern - Yahoo! Design Pattern Library</ulink>,
 584             and allows simple customization (minimum/maximum depth, indentation,
 585             separator, and whether the last element should be linked), or
 586             rendering using a partial view script.
 587         </para>
 588
 589         <para>
 590             The Breadcrumbs helper works like this; it finds the deepest active
 591             page in a navigation container, and renders an upwards path to
 592             the root. For <acronym>MVC</acronym> pages, the "activeness" of a page is
 593             determined by inspecting the request object, as stated in the
 594             section on <link linkend="zend.navigation.pages.mvc">Zend_Navigation_Page_Mvc</link>.
 595         </para>
 596
 597         <para>
 598             The helper sets the <code>minDepth</code> property to 1 by default,
 599             meaning breadcrumbs will not be rendered if the deepest active page
 600             is a root page. If <code>maxDepth</code> is specified, the helper
 601             will stop rendering when at the specified depth (e.g. stop at level
 602             2 even if the deepest active page is on level 3).
 603         </para>
 604
 605         <para>
 606             Methods in the breadcrumbs helper:
 607         </para>
 608
 609         <itemizedlist>
 610            <listitem>
 611                <para>
 612                    <code>{get|set}Separator()</code> gets/sets separator
 613                    string that is used between breadcrumbs. Defualt is
 614                    <code>' &amp;gt; '</code>.
 615                </para>
 616            </listitem>
 617
 618            <listitem>
 619                <para>
 620                    <code>{get|set}LinkLast()</code> gets/sets whether the
 621                    last breadcrumb should be rendered as an anchor or not.
 622                    Default is <constant>FALSE</constant>.
 623                </para>
 624            </listitem>
 625
 626            <listitem>
 627                <para>
 628                    <code>{get|set}Partial()</code> gets/sets a partial view
 629                    script that should be used for rendering breadcrumbs.
 630                    If a partial view script is set, the helper's
 631                    <methodname>render()</methodname> method will use the
 632                    <methodname>renderPartial()</methodname> method. If no partial is
 633                    set, the <methodname>renderStraight()</methodname> method is used.
 634                    The helper expects the partial to be a <type>String</type>
 635                    or an <type>Array</type> with two elements. If the partial
 636                    is a <type>String</type>, it denotes the name of the partial
 637                    script to use. If it is an <type>Array</type>, the first
 638                    element will be used as the name of the partial view
 639                    script, and the second element is the module where the
 640                    script is found.
 641                </para>
 642            </listitem>
 643
 644            <listitem>
 645                <para>
 646                    <methodname>renderStraight()</methodname> is the default render
 647                    method.
 648                </para>
 649            </listitem>
 650
 651            <listitem>
 652                <para>
 653                    <methodname>renderPartial()</methodname> is used for rendering
 654                    using a partial view script.
 655                </para>
 656            </listitem>
 657        </itemizedlist>
 658
 659         <example id="zend.view.helpers.initial.navigation.breadcrumbs.example1">
 660             <title>Rendering breadcrumbs</title>
 661
 662             <para>
 663                 This example shows how to render breadcrumbs with default
 664                 settings.
 665             </para>
 666
 667             <programlisting language="php"><![CDATA[
 668 In a view script or layout:
 669 <?php echo $this->navigation()->breadcrumbs(); ?>
 670
 671 The two calls above take advantage of the magic __toString() method,
 672 and are equivalent to:
 673 <?php echo $this->navigation()->breadcrumbs()->render(); ?>
 674
 675 Output:
 676 <a href="/products">Products</a> &gt; <a href="/products/server">Foo Server</a> &gt; FAQ
 677 ]]></programlisting>
 678         </example>
 679
 680         <example id="zend.view.helpers.initial.navigation.breadcrumbs.example2">
 681             <title>Specifying indentation</title>
 682
 683             <para>
 684                 This example shows how to render breadcrumbs with initial
 685                 indentation.
 686             </para>
 687
 688             <programlisting language="php"><![CDATA[
 689 Rendering with 8 spaces indentation:
 690 <?php echo $this->navigation()->breadcrumbs()->setIndent(8);?>
 691
 692 Output:
 693         <a href="/products">Products</a> &gt; <a href="/products/server">Foo Server</a> &gt; FAQ
 694 ]]></programlisting>
 695         </example>
 696
 697         <example id="zend.view.helpers.initial.navigation.breadcrumbs.example3">
 698             <title>Customize breadcrumbs output</title>
 699
 700             <para>
 701                 This example shows how to customze breadcrumbs output by
 702                 specifying various options.
 703             </para>
 704
 705             <programlisting language="php"><![CDATA[
 706 In a view script or layout:
 707
 708 <?php
 709 echo $this->navigation()
 710           ->breadcrumbs()
 711           ->setLinkLast(true)                   // link last page
 712           ->setMaxDepth(1)                      // stop at level 1
 713           ->setSeparator(' &#9654;' . PHP_EOL); // cool separator with newline
 714 ?>
 715
 716 Output:
 717 <a href="/products">Products</a> &#9654;
 718 <a href="/products/server">Foo Server</a>
 719
 720 /////////////////////////////////////////////////////
 721
 722 Setting minimum depth required to render breadcrumbs:
 723
 724 <?php
 725 $this->navigation()->breadcrumbs()->setMinDepth(10);
 726 echo $this->navigation()->breadcrumbs();
 727 ?>
 728
 729 Output:
 730 Nothing, because the deepest active page is not at level 10 or deeper.
 731 ]]></programlisting>
 732         </example>
 733
 734         <example id="zend.view.helpers.initial.navigation.breadcrumbs.example4">
 735             <title>Rendering breadcrumbs using a partial view script</title>
 736
 737             <para>
 738                 This example shows how to render customized breadcrumbs using
 739                 a partial vew script. By calling <methodname>setPartial()</methodname>,
 740                 you can specify a partial view script that will be used
 741                 when calling <methodname>render()</methodname>. When a partial is specified,
 742                 the <methodname>renderPartial()</methodname> method will be called. This
 743                 method will find the deepest active page and pass an array
 744                 of pages that leads to the active page to the partial view
 745                 script.
 746             </para>
 747
 748             <para>
 749                 In a layout:
 750             </para>
 751
 752             <programlisting language="php"><![CDATA[
 753 $partial = ;
 754 echo $this->navigation()->breadcrumbs()
 755                         ->setPartial(array('breadcrumbs.phtml', 'default'));
 756 ]]></programlisting>
 757
 758             <para>
 759                 Contents of
 760                 <code>application/modules/default/views/breadcrumbs.phtml</code>:
 761             </para>
 762
 763             <programlisting language="php"><![CDATA[
 764 echo implode(', ', array_map(
 765         create_function('$a', 'return $a->getLabel();'),
 766         $this->pages));
 767 ]]></programlisting>
 768
 769             <para>
 770                 Output:
 771             </para>
 772
 773             <programlisting language="php"><![CDATA[
 774 Products, Foo Server, FAQ
 775 ]]></programlisting>
 776         </example>
 777     </sect4>
 778
 779     <sect4 id="zend.view.helpers.initial.navigation.links">
 780         <title>Links Helper</title>
 781
 782         <para>
 783             The links helper is used for rendering <acronym>HTML</acronym> <constant>LINK</constant>
 784             elements. Links are used for describing document relationships
 785             of the currently active page. Read more about links and link
 786             types at <ulink url="http://www.w3.org/TR/html4/struct/links.html#h-12.3">Document
 787                 relationships: the LINK element (HTML4 W3C Rec.)</ulink>
 788             and <ulink
 789                 url="http://www.w3.org/TR/html4/types.html#h-6.12">Link types (HTML4 W3C
 790                 Rec.)</ulink> in the <acronym>HTML</acronym>4 W3C Recommendation.
 791         </para>
 792
 793         <para>
 794             There are two types of relations; forward and reverse, indicated
 795             by the keyords <code>'rel'</code> and <code>'rev'</code>. Most
 796             methods in the helper will take a <varname>$rel</varname> param, which
 797             must be either <code>'rel'</code> or <code>'rev'</code>. Most
 798             methods also take a <varname>$type</varname> param, which is used
 799             for specifying the link type (e.g. alternate, start, next, prev,
 800             chapter, etc).
 801         </para>
 802
 803         <para>
 804             Relationships can be added to page objects manually, or found
 805             by traversing the container registered in the helper. The method
 806             <methodname>findRelation($page, $rel, $type)</methodname> will first try
 807             to find the given <varname>$rel</varname> of <varname>$type</varname> from
 808             the <varname>$page</varname> by calling <code>$page->findRel($type)</code>
 809             or <code>$page->findRel($type)</code>. If the <varname>$page</varname>
 810             has a relation that can be converted to a page instance, that
 811             relation will be used. If the <varname>$page</varname> instance doesn't
 812             have the specified <varname>$type</varname>, the helper will look for
 813             a method in the helper named <code>search$rel$type</code> (e.g.
 814             <methodname>searchRelNext()</methodname> or
 815             <methodname>searchRevAlternate()</methodname>).
 816             If such a method exists, it will be used for determining the
 817             <varname>$page</varname>'s relation by traversing the container.
 818         </para>
 819
 820         <para>
 821             Not all relations can be determined by traversing the container.
 822             These are the relations that will be found by searching:
 823         </para>
 824
 825         <itemizedlist>
 826             <listitem>
 827                 <para>
 828                     <methodname>searchRelStart()</methodname>, forward 'start'
 829                     relation: the first page in the container.
 830                 </para>
 831             </listitem>
 832
 833             <listitem>
 834                 <para>
 835                     <methodname>searchRelNext()</methodname>, forward 'next'
 836                     relation; finds the next page in the container, i.e.
 837                     the page after the active page.
 838                 </para>
 839             </listitem>
 840
 841             <listitem>
 842                 <para>
 843                     <methodname>searchRelPrev()</methodname>, forward 'prev'
 844                     relation; finds the previous page, i.e. the page before
 845                     the active page.
 846                 </para>
 847             </listitem>
 848
 849             <listitem>
 850                 <para>
 851                     <methodname>searchRelChapter()</methodname>, forward 'chapter'
 852                     relations; finds all pages on level 0 except the 'start'
 853                     relation or the active page if it's on level 0.
 854                 </para>
 855             </listitem>
 856
 857             <listitem>
 858                 <para>
 859                     <methodname>searchRelSection()</methodname>, forward 'section'
 860                     relations; finds all child pages of the active page if
 861                     the active page is on level 0 (a 'chapter').
 862                 </para>
 863             </listitem>
 864
 865             <listitem>
 866                 <para>
 867                     <methodname>searchRelSubsection()</methodname>, forward 'subsection'
 868                     relations; finds all child pages of the active page if
 869                     the active pages is on level 1 (a 'section').
 870                 </para>
 871             </listitem>
 872
 873             <listitem>
 874                 <para>
 875                     <methodname>searchRevSection()</methodname>, reverse 'section'
 876                     relation; finds the parent of the active page if the
 877                     active page is on level 1 (a 'section').
 878                 </para>
 879             </listitem>
 880
 881             <listitem>
 882                 <para>
 883                     <methodname>searchRevSubsection()</methodname>, reverse 'subsection'
 884                     relation; finds the parent of the active page if the
 885                     active page is on level 2 (a 'subsection').
 886                 </para>
 887             </listitem>
 888         </itemizedlist>
 889
 890         <note>
 891             <para>
 892                 When looking for relations in the page instance
 893                 (<code>$page->getRel($type)</code> or
 894                 <code>$page->getRev($type)</code>), the helper accepts the
 895                 values of type <type>String</type>, <type>Array</type>,
 896                 <classname>Zend_Config</classname>, or
 897                 <classname>Zend_Navigation_Page</classname>. If a string
 898                 is found, it will be converted to a
 899                 <classname>Zend_Navigation_Page_Uri</classname>. If an array
 900                 or a config is found, it will be converted to one or several
 901                 page instances. If the first key of the array/config is numeric,
 902                 it will be considered to contain several pages, and each
 903                 element will be passed to the
 904                 <link linkend="zend.navigation.pages.factory">page factory</link>.
 905                 If the first key is not numeric, the array/config will be
 906                 passed to the page factory directly, and a single page will
 907                 be returned.
 908             </para>
 909         </note>
 910
 911         <para>
 912             The helper also supports magic methods for finding relations.
 913             E.g. to find forward alternate relations, call
 914             <code>$helper->findRelAlternate($page)</code>, and to find
 915             reverse section relations, call
 916             <code>$helper->findRevSection($page)</code>. Those calls correspond
 917             to <code>$helper->findRelation($page, 'rel', 'alternate');</code>
 918             and <code>$helper->findRelation($page, 'rev', 'section');</code>
 919             respectively.
 920         </para>
 921
 922         <para>
 923             To customize which relations should be rendered, the helper
 924             uses a render flag. The render flag is an integer value, and will be
 925             used in a
 926             <ulink url="http://php.net/manual/en/language.operators.bitwise.php">bitwse
 927             <code>and</code> (<code>&amp;</code>) operation</ulink> against the
 928             helper's render constants to determine if the relation that belongs
 929             to the render constant should be rendered.
 930         </para>
 931
 932         <para>
 933             See the
 934             <link linkend="zend.view.helpers.initial.navigation.links.example3">example
 935             below</link> for more information.
 936         </para>
 937
 938         <itemizedlist>
 939             <listitem>
 940                 <para>
 941                     <constant>Zend_View_Helper_Navigation_Link::RENDER_ALTERNATE</constant>
 942                 </para>
 943             </listitem>
 944
 945             <listitem>
 946                 <para>
 947                     <constant>Zend_View_Helper_Navigation_Link::RENDER_STYLESHEET</constant>
 948                 </para>
 949             </listitem>
 950
 951             <listitem>
 952                 <para>
 953                     <constant>Zend_View_Helper_Navigation_Link::RENDER_START</constant>
 954                 </para>
 955             </listitem>
 956
 957             <listitem>
 958                 <para>
 959                     <constant>Zend_View_Helper_Navigation_Link::RENDER_NEXT</constant>
 960                 </para>
 961             </listitem>
 962
 963             <listitem>
 964                 <para>
 965                     <constant>Zend_View_Helper_Navigation_Link::RENDER_PREV</constant>
 966                 </para>
 967             </listitem>
 968
 969             <listitem>
 970                 <para>
 971                     <constant>Zend_View_Helper_Navigation_Link::RENDER_CONTENTS</constant>
 972                 </para>
 973             </listitem>
 974
 975             <listitem>
 976                 <para>
 977                     <constant>Zend_View_Helper_Navigation_Link::RENDER_INDEX</constant>
 978                 </para>
 979             </listitem>
 980
 981             <listitem>
 982                 <para>
 983                     <constant>Zend_View_Helper_Navigation_Link::RENDER_GLOSSARY</constant>
 984                 </para>
 985             </listitem>
 986
 987             <listitem>
 988                 <para>
 989                     <constant>Zend_View_Helper_Navigation_Link::RENDER_COPYRIGHT</constant>
 990                 </para>
 991             </listitem>
 992
 993             <listitem>
 994                 <para>
 995                     <constant>Zend_View_Helper_Navigation_Link::RENDER_CHAPTER</constant>
 996                 </para>
 997             </listitem>
 998
 999             <listitem>
1000                 <para>
1001                     <constant>Zend_View_Helper_Navigation_Link::RENDER_SECTION</constant>
1002                 </para>
1003             </listitem>
1004
1005             <listitem>
1006                 <para>
1007                     <constant>Zend_View_Helper_Navigation_Link::RENDER_SUBSECTION</constant>
1008                 </para>
1009             </listitem>
1010
1011             <listitem>
1012                 <para>
1013                     <constant>Zend_View_Helper_Navigation_Link::RENDER_APPENDIX</constant>
1014                 </para>
1015             </listitem>
1016
1017             <listitem>
1018                 <para>
1019                     <constant>Zend_View_Helper_Navigation_Link::RENDER_HELP</constant>
1020                 </para>
1021             </listitem>
1022
1023             <listitem>
1024                 <para>
1025                     <constant>Zend_View_Helper_Navigation_Link::RENDER_BOOKMARK</constant>
1026                 </para>
1027             </listitem>
1028
1029             <listitem>
1030                 <para>
1031                     <constant>Zend_View_Helper_Navigation_Link::RENDER_CUSTOM</constant>
1032                 </para>
1033             </listitem>
1034
1035             <listitem>
1036                 <para>
1037                     <constant>Zend_View_Helper_Navigation_Link::RENDER_ALL</constant>
1038                 </para>
1039             </listitem>
1040         </itemizedlist>
1041
1042         <para>
1043             The constants from <constant>RENDER_ALTERNATE</constant> to
1044             <constant>RENDER_BOOKMARK</constant> denote standard <acronym>HTML</acronym> link types.
1045             <constant>RENDER_CUSTOM</constant> denotes non-standard relations that
1046             specified in pages. <constant>RENDER_ALL</constant> denotes standard and
1047             non-standard relations.
1048         </para>
1049
1050         <para>
1051             Methods in the links helper:
1052         </para>
1053
1054         <itemizedlist>
1055             <listitem>
1056                 <para>
1057                     <code>{get|set}RenderFlag()</code> gets/sets the render
1058                     flag. Default is <constant>RENDER_ALL</constant>. See examples
1059                     below on how to set the render flag.
1060                 </para>
1061             </listitem>
1062
1063             <listitem>
1064                 <para>
1065                     <methodname>findAllRelations()</methodname> finds all relations of
1066                     all types for a given page.
1067                 </para>
1068             </listitem>
1069
1070             <listitem>
1071                 <para>
1072                     <methodname>findRelation()</methodname> finds all relations of a given
1073                     type from a given page.
1074                 </para>
1075             </listitem>
1076
1077             <listitem>
1078                 <para>
1079                     <code>searchRel{Start|Next|Prev|Chapter|Section|Subsection}()</code>
1080                     traverses a container to find forward relations to
1081                     the start page, the next page, the previous page,
1082                     chapters, sections, and subsections.
1083                 </para>
1084             </listitem>
1085
1086             <listitem>
1087                 <para>
1088                     <code>searchRev{Section|Subsection}()</code> traverses
1089                     a container to find reverse relations to sections or
1090                     subsections.
1091                 </para>
1092             </listitem>
1093
1094             <listitem>
1095                 <para>
1096                     <methodname>renderLink()</methodname> renders a single <code>link</code>
1097                     element.
1098                 </para>
1099             </listitem>
1100         </itemizedlist>
1101
1102         <example id="zend.view.helpers.initial.navigation.links.example1">
1103             <title>Specify relations in pages</title>
1104
1105             <para>
1106                 This example shows how to specify relations in pages.
1107             </para>
1108
1109             <programlisting language="php"><![CDATA[
1110 $container = new Zend_Navigation(array(
1111     array(
1112         'label' => 'Relations using strings',
1113         'rel'   => array(
1114             'alternate' => 'http://www.example.org/'
1115         ),
1116         'rev'   => array(
1117             'alternate' => 'http://www.example.net/'
1118         )
1119     ),
1120     array(
1121         'label' => 'Relations using arrays',
1122         'rel'   => array(
1123             'alternate' => array(
1124                 'label' => 'Example.org',
1125                 'uri'   => 'http://www.example.org/'
1126             )
1127         )
1128     ),
1129     array(
1130         'label' => 'Relations using configs',
1131         'rel'   => array(
1132             'alternate' => new Zend_Config(array(
1133                 'label' => 'Example.org',
1134                 'uri'   => 'http://www.example.org/'
1135             ))
1136         )
1137     ),
1138     array(
1139         'label' => 'Relations using pages instance',
1140         'rel'   => array(
1141             'alternate' => Zend_Navigation_Page::factory(array(
1142                 'label' => 'Example.org',
1143                 'uri'   => 'http://www.example.org/'
1144             ))
1145         )
1146     )
1147 ));
1148 ]]></programlisting>
1149         </example>
1150
1151         <example id="zend.view.helpers.initial.navigation.links.example2">
1152             <title>Default rendering of links</title>
1153
1154             <para>
1155                 This example shows how to render a menu from a container
1156                 registered/found in the view helper.
1157             </para>
1158
1159             <programlisting language="php"><![CDATA[
1160 In a view script or layout:
1161 <?php echo $this->view->navigation()->links(); ?>
1162
1163 Output:
1164 <link rel="alternate" href="/products/server/faq/format/xml">
1165 <link rel="start" href="/" title="Home">
1166 <link rel="next" href="/products/server/editions" title="Editions">
1167 <link rel="prev" href="/products/server" title="Foo Server">
1168 <link rel="chapter" href="/products" title="Products">
1169 <link rel="chapter" href="/company/about" title="Company">
1170 <link rel="chapter" href="/community" title="Community">
1171 <link rel="canonical" href="http://www.example.com/?page=server-faq">
1172 <link rev="subsection" href="/products/server" title="Foo Server">
1173 ]]></programlisting>
1174         </example>
1175
1176         <example id="zend.view.helpers.initial.navigation.links.example3">
1177             <title>Specify which relations to render</title>
1178
1179             <para>
1180                 This example shows how to specify which relations to find
1181                 and render.
1182             </para>
1183
1184             <programlisting language="php"><![CDATA[
1185 Render only start, next, and prev:
1186 $helper->setRenderFlag(Zend_View_Helper_Navigation_Links::RENDER_START |
1187                        Zend_View_Helper_Navigation_Links::RENDER_NEXT |
1188                        Zend_View_Helper_Navigation_Links::RENDER_PREV);
1189
1190 Output:
1191 <link rel="start" href="/" title="Home">
1192 <link rel="next" href="/products/server/editions" title="Editions">
1193 <link rel="prev" href="/products/server" title="Foo Server">
1194 ]]></programlisting>
1195
1196             <programlisting language="php"><![CDATA[
1197 Render only native link types:
1198 $helper->setRenderFlag(Zend_View_Helper_Navigation_Links::RENDER_ALL ^
1199                        Zend_View_Helper_Navigation_Links::RENDER_CUSTOM);
1200
1201 Output:
1202 <link rel="alternate" href="/products/server/faq/format/xml">
1203 <link rel="start" href="/" title="Home">
1204 <link rel="next" href="/products/server/editions" title="Editions">
1205 <link rel="prev" href="/products/server" title="Foo Server">
1206 <link rel="chapter" href="/products" title="Products">
1207 <link rel="chapter" href="/company/about" title="Company">
1208 <link rel="chapter" href="/community" title="Community">
1209 <link rev="subsection" href="/products/server" title="Foo Server">
1210 ]]></programlisting>
1211
1212             <programlisting language="php"><![CDATA[
1213 Render all but chapter:
1214 $helper->setRenderFlag(Zend_View_Helper_Navigation_Links::RENDER_ALL ^
1215                        Zend_View_Helper_Navigation_Links::RENDER_CHAPTER);
1216
1217 Output:
1218 <link rel="alternate" href="/products/server/faq/format/xml">
1219 <link rel="start" href="/" title="Home">
1220 <link rel="next" href="/products/server/editions" title="Editions">
1221 <link rel="prev" href="/products/server" title="Foo Server">
1222 <link rel="canonical" href="http://www.example.com/?page=server-faq">
1223 <link rev="subsection" href="/products/server" title="Foo Server">
1224 ]]></programlisting>
1225         </example>
1226     </sect4>
1227
1228     <sect4 id="zend.view.helpers.initial.navigation.menu">
1229         <title>Menu Helper</title>
1230
1231         <para>
1232             The Menu helper is used for rendering menus from navigation
1233             containers. By default, the menu will be rendered using
1234             <acronym>HTML</acronym> <code>UL</code> and <code>LI</code> tags, but the helper also
1235             allows using a partial view script.
1236         </para>
1237
1238         <para>
1239             Methods in the Menu helper:
1240         </para>
1241
1242         <itemizedlist>
1243             <listitem>
1244                 <para>
1245                     <code>{get|set}UlClass()</code> gets/sets the <acronym>CSS</acronym> class
1246                     used in <methodname>renderMenu()</methodname>.
1247                 </para>
1248             </listitem>
1249
1250             <listitem>
1251                 <para>
1252                     <code>{get|set}OnlyActiveBranch()</code> gets/sets a flag
1253                     specifying whether only the active branch of a container
1254                     should be rendered.
1255                 </para>
1256             </listitem>
1257
1258             <listitem>
1259                 <para>
1260                     <code>{get|set}RenderParents()</code> gets/sets a flag
1261                     specifying whether parents should be rendered when only
1262                     rendering active branch of a container. If set to
1263                     <constant>FALSE</constant>, only the deepest active menu will be
1264                     rendered.
1265                 </para>
1266             </listitem>
1267
1268             <listitem>
1269                 <para>
1270                     <code>{get|set}Partial()</code> gets/sets a partial view
1271                     script that should be used for rendering menu.
1272                     If a partial view script is set, the helper's
1273                     <methodname>render()</methodname> method will use the
1274                     <methodname>renderPartial()</methodname> method. If no partial is
1275                     set, the <methodname>renderMenu()</methodname> method is used.
1276                     The helper expects the partial to be a <type>String</type>
1277                     or an <type>Array</type> with two elements. If the partial
1278                     is a <type>String</type>, it denotes the name of the partial
1279                     script to use. If it is an <type>Array</type>, the first
1280                     element will be used as the name of the partial view
1281                     script, and the second element is the module where the
1282                     script is found.
1283                 </para>
1284             </listitem>
1285
1286             <listitem>
1287                 <para>
1288                     <methodname>htmlify()</methodname> overrides the method from the
1289                     abstract class to return <code>span</code> elements
1290                     if the page has no <code>href</code>.
1291                 </para>
1292             </listitem>
1293
1294             <listitem>
1295                 <para>
1296                     <methodname>renderMenu($container = null, $options = array())</methodname>
1297                     is the default render method, and will render a container as
1298                     a <acronym>HTML</acronym> <code>UL</code> list.
1299                 </para>
1300
1301                 <para>
1302                     If <varname>$container</varname> is not given, the container
1303                     registered in the helper will be rendered.
1304                 </para>
1305
1306                 <para>
1307                     <varname>$options</varname> is used for overriding options
1308                     specified temporarily without rsetting the values in the
1309                     helper instance. It is an associative array where each key
1310                     corresponds to an option in the helper.
1311                 </para>
1312
1313                 <para>
1314                     Recognized options:
1315                 </para>
1316
1317                 <itemizedlist>
1318                     <listitem>
1319                         <para>
1320                             <code>indent</code>; indentation. Expects a
1321                             <type>String</type> or an <code>int</code>
1322                             value.
1323                         </para>
1324                     </listitem>
1325
1326                     <listitem>
1327                         <para>
1328                             <code>minDepth</code>; minimum depth. Expcects
1329                             an <code>int</code> or <constant>NULL</constant> (no
1330                             minimum depth).
1331                         </para>
1332                     </listitem>
1333
1334                     <listitem>
1335                         <para>
1336                             <code>maxDepth</code>; maximum depth. Expcects
1337                             an <code>int</code> or <constant>NULL</constant> (no
1338                             maximum depth).
1339                         </para>
1340                     </listitem>
1341
1342                     <listitem>
1343                         <para>
1344                             <code>ulClass</code>; <acronym>CSS</acronym> class for
1345                             <code>ul</code> element. Expects a
1346                             <type>String</type>.
1347                         </para>
1348                     </listitem>
1349
1350                     <listitem>
1351                         <para>
1352                             <code>onlyActiveBranch</code>; whether only
1353                             active branch should be rendered. Expects
1354                             a <type>Boolean</type> value.
1355                         </para>
1356                     </listitem>
1357
1358                     <listitem>
1359                         <para>
1360                             <code>renderParents</code>; whether parents
1361                             should be rendered if only rendering active
1362                             branch. Expects a <type>Boolean</type> value.
1363                         </para>
1364                     </listitem>
1365                 </itemizedlist>
1366
1367                 <para>
1368                     If an option is not given, the value set in the helper
1369                     will be used.
1370                 </para>
1371             </listitem>
1372
1373             <listitem>
1374                 <para>
1375                     <methodname>renderPartial()</methodname> is used for rendering the menu
1376                     using a partial view script.
1377                 </para>
1378             </listitem>
1379
1380             <listitem>
1381                 <para>
1382                     <methodname>renderSubMenu()</methodname> renders the deepest menu level
1383                     of a container's active branch.
1384                 </para>
1385             </listitem>
1386        </itemizedlist>
1387
1388         <example id="zend.view.helpers.initial.navigation.menu.example1">
1389             <title>Rendering a menu</title>
1390
1391             <para>
1392                 This example shows how to render a menu from a container
1393                 registered/found in the view helper. Notice how pages
1394                 are filtered out based on visibility and <acronym>ACL</acronym>.
1395             </para>
1396
1397             <programlisting language="php"><![CDATA[
1398 In a view script or layout:
1399 <?php echo $this->navigation()->menu()->render() ?>
1400
1401 Or simply:
1402 <?php echo $this->navigation()->menu() ?>
1403
1404 Output:
1405 <ul class="navigation">
1406     <li>
1407         <a title="Go Home" href="/">Home</a>
1408     </li>
1409     <li class="active">
1410         <a href="/products">Products</a>
1411         <ul>
1412             <li class="active">
1413                 <a href="/products/server">Foo Server</a>
1414                 <ul>
1415                     <li class="active">
1416                         <a href="/products/server/faq">FAQ</a>
1417                     </li>
1418                     <li>
1419                         <a href="/products/server/editions">Editions</a>
1420                     </li>
1421                     <li>
1422                         <a href="/products/server/requirements">System Requirements</a>
1423                     </li>
1424                 </ul>
1425             </li>
1426             <li>
1427                 <a href="/products/studio">Foo Studio</a>
1428                 <ul>
1429                     <li>
1430                         <a href="/products/studio/customers">Customer Stories</a>
1431                     </li>
1432                     <li>
1433                         <a href="/prodcts/studio/support">Support</a>
1434                     </li>
1435                 </ul>
1436             </li>
1437         </ul>
1438     </li>
1439     <li>
1440         <a title="About us" href="/company/about">Company</a>
1441         <ul>
1442             <li>
1443                 <a href="/company/about/investors">Investor Relations</a>
1444             </li>
1445             <li>
1446                 <a class="rss" href="/company/news">News</a>
1447                 <ul>
1448                     <li>
1449                         <a href="/company/news/press">Press Releases</a>
1450                     </li>
1451                     <li>
1452                         <a href="/archive">Archive</a>
1453                     </li>
1454                 </ul>
1455             </li>
1456         </ul>
1457     </li>
1458     <li>
1459         <a href="/community">Community</a>
1460         <ul>
1461             <li>
1462                 <a href="/community/account">My Account</a>
1463             </li>
1464             <li>
1465                 <a class="external" href="http://forums.example.com/">Forums</a>
1466             </li>
1467         </ul>
1468     </li>
1469 </ul>
1470 ]]></programlisting>
1471         </example>
1472
1473         <example id="zend.view.helpers.initial.navigation.menu.example2">
1474             <title>Calling renderMenu() directly</title>
1475
1476             <para>
1477                 This example shows how to render a menu that is not
1478                 registered in the view helper by calling the
1479                 <methodname>renderMenu()</methodname> directly and specifying a few
1480                 options.
1481             </para>
1482
1483             <programlisting language="php"><![CDATA[
1484 <?php
1485 // render only the 'Community' menu
1486 $community = $this->navigation()->findOneByLabel('Community');
1487 $options = array(
1488     'indent'  => 16,
1489     'ulClass' => 'community'
1490 );
1491 echo $this->navigation()
1492           ->menu()
1493           ->renderMenu($community, $options);
1494 ?>
1495 Output:
1496                 <ul class="community">
1497                     <li>
1498                         <a href="/community/account">My Account</a>
1499                     </li>
1500                     <li>
1501                         <a class="external" href="http://forums.example.com/">Forums</a>
1502                     </li>
1503                 </ul>
1504 ]]></programlisting>
1505         </example>
1506
1507         <example id="zend.view.helpers.initial.navigation.menu.example3">
1508             <title>Rendering the deepest active menu</title>
1509
1510             <para>
1511                 This example shows how the <methodname>renderSubMenu()</methodname>
1512                 will render the deepest sub menu of the active branch.
1513             </para>
1514
1515             <para>
1516                 Calling <methodname>renderSubMenu($container, $ulClass, $indent)</methodname>
1517                 is equivalent to calling <methodname>renderMenu($container, $options)</methodname>
1518                 with the following options:
1519             </para>
1520
1521             <programlisting language="php"><![CDATA[
1522 array(
1523     'ulClass'          => $ulClass,
1524     'indent'           => $indent,
1525     'minDepth'         => null,
1526     'maxDepth'         => null,
1527     'onlyActiveBranch' => true,
1528     'renderParents'    => false
1529 );
1530 ]]></programlisting>
1531
1532             <programlisting language="php"><![CDATA[
1533 <?php
1534 echo $this->navigation()
1535           ->menu()
1536           ->renderSubMenu(null, 'sidebar', 4);
1537 ?>
1538
1539 The output will be the same if 'FAQ' or 'Foo Server' is active:
1540     <ul class="sidebar">
1541         <li class="active">
1542             <a href="/products/server/faq">FAQ</a>
1543         </li>
1544         <li>
1545             <a href="/products/server/editions">Editions</a>
1546         </li>
1547         <li>
1548             <a href="/products/server/requirements">System Requirements</a>
1549         </li>
1550     </ul>
1551 ]]></programlisting>
1552         </example>
1553
1554         <example id="zend.view.helpers.initial.navigation.menu.example4">
1555             <title>Rendering a menu with maximum depth</title>
1556
1557             <programlisting language="php"><![CDATA[
1558 <?php
1559 echo $this->navigation()
1560           ->menu()
1561           ->setMaxDepth(1);
1562 ?>
1563
1564 Output:
1565 <ul class="navigation">
1566     <li>
1567         <a title="Go Home" href="/">Home</a>
1568     </li>
1569     <li class="active">
1570         <a href="/products">Products</a>
1571         <ul>
1572             <li class="active">
1573                 <a href="/products/server">Foo Server</a>
1574             </li>
1575             <li>
1576                 <a href="/products/studio">Foo Studio</a>
1577             </li>
1578         </ul>
1579     </li>
1580     <li>
1581         <a title="About us" href="/company/about">Company</a>
1582         <ul>
1583             <li>
1584                 <a href="/company/about/investors">Investor Relations</a>
1585             </li>
1586             <li>
1587                 <a class="rss" href="/company/news">News</a>
1588             </li>
1589         </ul>
1590     </li>
1591     <li>
1592         <a href="/community">Community</a>
1593         <ul>
1594             <li>
1595                 <a href="/community/account">My Account</a>
1596             </li>
1597             <li>
1598                 <a class="external" href="http://forums.example.com/">Forums</a>
1599             </li>
1600         </ul>
1601     </li>
1602 </ul>
1603 ]]></programlisting>
1604         </example>
1605
1606         <example id="zend.view.helpers.initial.navigation.menu.example5">
1607             <title>Rendering a menu with minimum depth</title>
1608
1609             <programlisting language="php"><![CDATA[
1610 <?php
1611 echo $this->navigation()
1612           ->menu()
1613           ->setMinDepth(1);
1614 ?>
1615
1616 Output:
1617 <ul class="navigation">
1618     <li class="active">
1619         <a href="/products/server">Foo Server</a>
1620         <ul>
1621             <li class="active">
1622                 <a href="/products/server/faq">FAQ</a>
1623             </li>
1624             <li>
1625                 <a href="/products/server/editions">Editions</a>
1626             </li>
1627             <li>
1628                 <a href="/products/server/requirements">System Requirements</a>
1629             </li>
1630         </ul>
1631     </li>
1632     <li>
1633         <a href="/products/studio">Foo Studio</a>
1634         <ul>
1635             <li>
1636                 <a href="/products/studio/customers">Customer Stories</a>
1637             </li>
1638             <li>
1639                 <a href="/prodcts/studio/support">Support</a>
1640             </li>
1641         </ul>
1642     </li>
1643     <li>
1644         <a href="/company/about/investors">Investor Relations</a>
1645     </li>
1646     <li>
1647         <a class="rss" href="/company/news">News</a>
1648         <ul>
1649             <li>
1650                 <a href="/company/news/press">Press Releases</a>
1651             </li>
1652             <li>
1653                 <a href="/archive">Archive</a>
1654             </li>
1655         </ul>
1656     </li>
1657     <li>
1658         <a href="/community/account">My Account</a>
1659     </li>
1660     <li>
1661         <a class="external" href="http://forums.example.com/">Forums</a>
1662     </li>
1663 </ul>
1664 ]]></programlisting>
1665         </example>
1666
1667         <example id="zend.view.helpers.initial.navigation.menu.example6">
1668             <title>Rendering only the active branch of a menu</title>
1669
1670             <programlisting language="php"><![CDATA[
1671 <?php
1672 echo $this->navigation()
1673           ->menu()
1674           ->setOnlyActiveBranch(true);
1675 ?>
1676
1677 Output:
1678 <ul class="navigation">
1679     <li class="active">
1680         <a href="/products">Products</a>
1681         <ul>
1682             <li class="active">
1683                 <a href="/products/server">Foo Server</a>
1684                 <ul>
1685                     <li class="active">
1686                         <a href="/products/server/faq">FAQ</a>
1687                     </li>
1688                     <li>
1689                         <a href="/products/server/editions">Editions</a>
1690                     </li>
1691                     <li>
1692                         <a href="/products/server/requirements">System Requirements</a>
1693                     </li>
1694                 </ul>
1695             </li>
1696         </ul>
1697     </li>
1698 </ul>
1699 ]]></programlisting>
1700         </example>
1701
1702         <example id="zend.view.helpers.initial.navigation.menu.example7">
1703             <title>
1704                 Rendering only the active branch of a menu with minimum depth
1705             </title>
1706
1707             <programlisting language="php"><![CDATA[
1708 <?php
1709 echo $this->navigation()
1710           ->menu()
1711           ->setOnlyActiveBranch(true)
1712           ->setMinDepth(1);
1713 ?>
1714
1715 Output:
1716 <ul class="navigation">
1717     <li class="active">
1718         <a href="/products/server">Foo Server</a>
1719         <ul>
1720             <li class="active">
1721                 <a href="/products/server/faq">FAQ</a>
1722             </li>
1723             <li>
1724                 <a href="/products/server/editions">Editions</a>
1725             </li>
1726             <li>
1727                 <a href="/products/server/requirements">System Requirements</a>
1728             </li>
1729         </ul>
1730     </li>
1731 </ul>
1732 ]]></programlisting>
1733         </example>
1734
1735         <example id="zend.view.helpers.initial.navigation.menu.example8">
1736             <title>
1737                 Rendering only the active branch of a menu with maximum depth
1738             </title>
1739
1740             <programlisting language="php"><![CDATA[
1741 <?php
1742 echo $this->navigation()
1743           ->menu()
1744           ->setOnlyActiveBranch(true)
1745           ->setMaxDepth(1);
1746 ?>
1747
1748 Output:
1749 <ul class="navigation">
1750     <li class="active">
1751         <a href="/products">Products</a>
1752         <ul>
1753             <li class="active">
1754                 <a href="/products/server">Foo Server</a>
1755             </li>
1756             <li>
1757                 <a href="/products/studio">Foo Studio</a>
1758             </li>
1759         </ul>
1760     </li>
1761 </ul>
1762 ]]></programlisting>
1763         </example>
1764
1765         <example id="zend.view.helpers.initial.navigation.menu.example9">
1766             <title>
1767                 Rendering only the active branch of a menu with maximum depth
1768                 and no parents
1769             </title>
1770
1771             <para>
1772             </para>
1773
1774             <programlisting language="php"><![CDATA[
1775 <?php
1776 echo $this->navigation()
1777           ->menu()
1778           ->setOnlyActiveBranch(true)
1779           ->setRenderParents(false)
1780           ->setMaxDepth(1);
1781 ?>
1782
1783 Output:
1784 <ul class="navigation">
1785     <li class="active">
1786         <a href="/products/server">Foo Server</a>
1787     </li>
1788     <li>
1789         <a href="/products/studio">Foo Studio</a>
1790     </li>
1791 </ul>
1792 ]]></programlisting>
1793         </example>
1794
1795         <example id="zend.view.helpers.initial.navigation.menu.example10">
1796             <title>Rendering a custom menu using a partial view script</title>
1797
1798             <para>
1799                 This example shows how to render a custom menu using
1800                 a partial vew script. By calling <methodname>setPartial()</methodname>,
1801                 you can specify a partial view script that will be used
1802                 when calling <methodname>render()</methodname>. When a partial is specified,
1803                 the <methodname>renderPartial()</methodname> method will be called. This
1804                 method will assign the container to the view with the key
1805                 <code>container</code>.
1806             </para>
1807
1808             <para>In a layout:</para>
1809
1810             <programlisting language="php"><![CDATA[
1811 $partial = array('menu.phtml', 'default');
1812 $this->navigation()->menu()->setPartial($partial);
1813 echo $this->navigation()->menu()->render();
1814 ]]></programlisting>
1815
1816             <para>In application/modules/default/views/menu.phtml:</para>
1817
1818             <programlisting language="php"><![CDATA[
1819 foreach ($this->container as $page) {
1820     echo $this->navigation()->menu()->htmlify($page), PHP_EOL;
1821 }
1822 ]]></programlisting>
1823
1824             <para>Output:</para>
1825
1826             <programlisting language="php"><![CDATA[
1827 <a title="Go Home" href="/">Home</a>
1828 <a href="/products">Products</a>
1829 <a title="About us" href="/company/about">Company</a>
1830 <a href="/community">Community</a>
1831 ]]></programlisting>
1832         </example>
1833     </sect4>
1834
1835     <sect4 id="zend.view.helpers.initial.navigation.sitemap">
1836         <title>Sitemap Helper</title>
1837
1838         <para>
1839             The Sitemap helper is used for generating <acronym>XML</acronym> sitemaps, as
1840             defined by the <ulink
1841                 url="http://www.sitemaps.org/protocol.php">Sitemaps <acronym>XML</acronym>
1842                 format</ulink>. Read more about <ulink
1843                 url="http://en.wikipedia.org/wiki/Sitemaps">Sitemaps on Wikpedia</ulink>.
1844         </para>
1845
1846         <para>
1847             By default, the sitemap helper uses
1848             <link linkend="zend.validate.sitemap">sitemap validators</link>
1849             to validate each element that is rendered. This can be disabled by
1850             calling <code>$helper->setUseSitemapValidators(false)</code>.
1851         </para>
1852
1853         <note>
1854             <para>
1855                 If you disable sitemap validators, the custom properties (see table)
1856                 are not validated at all.
1857             </para>
1858         </note>
1859
1860         <para>
1861             The sitemap helper also supports <ulink
1862                 url="http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd">Sitemap XSD
1863                 Schema</ulink> validation of the generated sitemap. This is disabled by default,
1864             since it will require a request to the Schema file. It can be
1865             enabled with
1866             <code>$helper->setUseSchemaValidation(true)</code>.
1867         </para>
1868
1869         <table id="zend.view.helpers.initial.navigation.sitemap.elements">
1870             <title>Sitemap XML elements</title>
1871
1872             <tgroup cols="2">
1873                 <thead>
1874                     <row>
1875                         <entry>Element</entry>
1876                         <entry>Description</entry>
1877                     </row>
1878                 </thead>
1879
1880                 <tbody>
1881                     <row>
1882                         <entry><code>loc</code></entry>
1883
1884                         <entry>
1885                             Absolute <acronym>URL</acronym> to page. An absolute
1886                             <acronym>URL</acronym> will be generated by the helper.
1887                         </entry>
1888                     </row>
1889
1890                     <row>
1891                         <entry><code>lastmod</code></entry>
1892
1893                         <entry>
1894                             <para>
1895                                 The date of last modification of the file, in <ulink
1896                                     url="http://www.w3.org/TR/NOTE-datetime">W3C Datetime</ulink>
1897                                 format. This time portion can be omitted if desired, and only use
1898                                 YYYY-MM-DD.
1899                             </para>
1900
1901                             <para>
1902                                 The helper will try to retrieve the
1903                                 <code>lastmod</code> value from the page's
1904                                 custom property <code>lastmod</code> if it
1905                                 is set in the page. If the value is not a
1906                                 valid date, it is ignored.
1907                             </para>
1908                         </entry>
1909                     </row>
1910
1911                     <row>
1912                         <entry><code>changefreq</code></entry>
1913
1914                         <entry>
1915                             <para>
1916                                 How frequently the page is likely to change.
1917                                 This value provides general information to
1918                                 search engines and may not correlate exactly
1919                                 to how often they crawl the page. Valid
1920                                 values are:
1921                             </para>
1922
1923                             <itemizedlist>
1924                                 <listitem><para>always</para></listitem>
1925                                 <listitem><para>hourly</para></listitem>
1926                                 <listitem><para>daily</para></listitem>
1927                                 <listitem><para>weekly</para></listitem>
1928                                 <listitem><para>monthly</para></listitem>
1929                                 <listitem><para>yearly</para></listitem>
1930                                 <listitem><para>never</para></listitem>
1931                             </itemizedlist>
1932
1933                             <para>
1934                                 The helper will try to retrieve the
1935                                 <code>changefreq</code> value from the page's
1936                                 custom property <code>changefreq</code> if it
1937                                 is set in the page. If the value is not
1938                                 valid, it is ignored.
1939                             </para>
1940                         </entry>
1941                     </row>
1942
1943                     <row>
1944                         <entry><code>priority</code></entry>
1945
1946                         <entry>
1947                             <para>
1948                                 The priority of this <acronym>URL</acronym> relative to other
1949                                 <acronym>URL</acronym>s on your site. Valid values range from
1950                                 0.0 to 1.0.
1951                             </para>
1952
1953                             <para>
1954                                 The helper will try to retrieve the
1955                                 <code>priority</code> value from the page's
1956                                 custom property <code>priority</code> if it
1957                                 is set in the page. If the value is not
1958                                 valid, it is ignored.
1959                             </para>
1960                         </entry>
1961                     </row>
1962                 </tbody>
1963             </tgroup>
1964         </table>
1965
1966         <para>
1967             Methods in the sitemap helper:
1968         </para>
1969
1970         <itemizedlist>
1971            <listitem>
1972                 <para>
1973                     <code>{get|set}FormatOutput()</code> gets/sets a flag
1974                     indicating whether <acronym>XML</acronym> output should be formatted. This
1975                     corresponds to the <code>formatOutput</code> property
1976                     of the native <classname>DOMDocument</classname> class.
1977                     Read more at
1978                     <ulink url="http://php.net/domdocument">PHP: DOMDocument - Manual</ulink>.
1979                     Default is <constant>FALSE</constant>.
1980                 </para>
1981            </listitem>
1982
1983            <listitem>
1984                 <para>
1985                     <code>{get|set}UseXmlDeclaration()</code> gets/sets a
1986                     flag indicating whether the <acronym>XML</acronym> declaration should be
1987                     included when rendering. Default is <constant>TRUE</constant>.
1988                 </para>
1989            </listitem>
1990
1991            <listitem>
1992                 <para>
1993                     <code>{get|set}UseSitemapValidators()</code> gets/sets a
1994                     flag indicating whether sitemap validators should be
1995                     used when generating the DOM sitemap. Default is
1996                     <constant>TRUE</constant>.
1997                 </para>
1998            </listitem>
1999
2000            <listitem>
2001                 <para>
2002                     <code>{get|set}UseSchemaValidation()</code> gets/sets a
2003                     flag indicating whether the helper should use <acronym>XML</acronym> Schema
2004                     validation when generating the DOM sitemap. Default is
2005                     <constant>FALSE</constant>. If <constant>TRUE</constant>.
2006                 </para>
2007            </listitem>
2008
2009            <listitem>
2010                 <para>
2011                     <code>{get|set}ServerUrl()</code> gets/sets server <acronym>URL</acronym>
2012                     that will be prepended to non-absolute <acronym>URL</acronym>s in the
2013                     <methodname>url()</methodname> method. If no server <acronym>URL</acronym> is
2014                     specified, it will be determined by the helper.
2015                 </para>
2016            </listitem>
2017
2018            <listitem>
2019                 <para>
2020                     <methodname>url()</methodname> is used to generate absolute
2021                     <acronym>URL</acronym>s to pages.
2022                 </para>
2023            </listitem>
2024
2025            <listitem>
2026                 <para>
2027                     <methodname>getDomSitemap()</methodname> generates a DOMDocument
2028                     from a given container.
2029                 </para>
2030            </listitem>
2031        </itemizedlist>
2032
2033         <example id="zend.view.helpers.initial.navigation.sitemap.example">
2034             <title>Rendering an XML sitemap</title>
2035
2036             <para>
2037                 This example shows how to render an <acronym>XML</acronym> sitemap based
2038                 on the setup we did further up.
2039             </para>
2040
2041             <programlisting language="php"><![CDATA[
2042 // In a view script or layout:
2043
2044 // format output
2045 $this->navigation()
2046       ->sitemap()
2047       ->setFormatOutput(true); // default is false
2048
2049 // other possible methods:
2050 // ->setUseXmlDeclaration(false); // default is true
2051 // ->setServerUrl('http://my.otherhost.com');
2052 // default is to detect automatically
2053
2054 // print sitemap
2055 echo $this->navigation()->sitemap();
2056 ]]></programlisting>
2057
2058             <para>
2059                 Notice how pages that are invisible or pages with
2060                 <acronym>ACL</acronym> roles incompatible with the view helper are filtered
2061                 out:
2062             </para>
2063
2064             <programlisting language="xml"><![CDATA[
2065 <?xml version="1.0" encoding="UTF-8"?>
2066 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
2067   <url>
2068     <loc>http://www.example.com/</loc>
2069   </url>
2070   <url>
2071     <loc>http://www.example.com/products</loc>
2072   </url>
2073   <url>
2074     <loc>http://www.example.com/products/server</loc>
2075   </url>
2076   <url>
2077     <loc>http://www.example.com/products/server/faq</loc>
2078   </url>
2079   <url>
2080     <loc>http://www.example.com/products/server/editions</loc>
2081   </url>
2082   <url>
2083     <loc>http://www.example.com/products/server/requirements</loc>
2084   </url>
2085   <url>
2086     <loc>http://www.example.com/products/studio</loc>
2087   </url>
2088   <url>
2089     <loc>http://www.example.com/products/studio/customers</loc>
2090   </url>
2091   <url>
2092     <loc>http://www.example.com/prodcts/studio/support</loc>
2093   </url>
2094   <url>
2095     <loc>http://www.example.com/company/about</loc>
2096   </url>
2097   <url>
2098     <loc>http://www.example.com/company/about/investors</loc>
2099   </url>
2100   <url>
2101     <loc>http://www.example.com/company/news</loc>
2102   </url>
2103   <url>
2104     <loc>http://www.example.com/company/news/press</loc>
2105   </url>
2106   <url>
2107     <loc>http://www.example.com/archive</loc>
2108   </url>
2109   <url>
2110     <loc>http://www.example.com/community</loc>
2111   </url>
2112   <url>
2113     <loc>http://www.example.com/community/account</loc>
2114   </url>
2115   <url>
2116     <loc>http://forums.example.com/</loc>
2117   </url>
2118 </urlset>
2119 ]]></programlisting>
2120
2121             <para>
2122                 Render the sitemap using no <acronym>ACL</acronym> role (should filter out
2123                 /community/account):
2124             </para>
2125
2126             <programlisting language="php"><![CDATA[
2127 echo $this->navigation()
2128           ->sitemap()
2129           ->setFormatOutput(true)
2130           ->setRole();
2131 ]]></programlisting>
2132
2133             <programlisting language="xml"><![CDATA[
2134 <?xml version="1.0" encoding="UTF-8"?>
2135 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
2136   <url>
2137     <loc>http://www.example.com/</loc>
2138   </url>
2139   <url>
2140     <loc>http://www.example.com/products</loc>
2141   </url>
2142   <url>
2143     <loc>http://www.example.com/products/server</loc>
2144   </url>
2145   <url>
2146     <loc>http://www.example.com/products/server/faq</loc>
2147   </url>
2148   <url>
2149     <loc>http://www.example.com/products/server/editions</loc>
2150   </url>
2151   <url>
2152     <loc>http://www.example.com/products/server/requirements</loc>
2153   </url>
2154   <url>
2155     <loc>http://www.example.com/products/studio</loc>
2156   </url>
2157   <url>
2158     <loc>http://www.example.com/products/studio/customers</loc>
2159   </url>
2160   <url>
2161     <loc>http://www.example.com/prodcts/studio/support</loc>
2162   </url>
2163   <url>
2164     <loc>http://www.example.com/company/about</loc>
2165   </url>
2166   <url>
2167     <loc>http://www.example.com/company/about/investors</loc>
2168   </url>
2169   <url>
2170     <loc>http://www.example.com/company/news</loc>
2171   </url>
2172   <url>
2173     <loc>http://www.example.com/company/news/press</loc>
2174   </url>
2175   <url>
2176     <loc>http://www.example.com/archive</loc>
2177   </url>
2178   <url>
2179     <loc>http://www.example.com/community</loc>
2180   </url>
2181   <url>
2182     <loc>http://forums.example.com/</loc>
2183   </url>
2184 </urlset>
2185 ]]></programlisting>
2186
2187             <para>
2188                 Render the sitemap using a maximum depth of 1.
2189             </para>
2190
2191             <programlisting language="php"><![CDATA[
2192 echo $this->navigation()
2193           ->sitemap()
2194           ->setFormatOutput(true)
2195           ->setMaxDepth(1);
2196 ]]></programlisting>
2197
2198             <programlisting language="xml"><![CDATA[
2199 <?xml version="1.0" encoding="UTF-8"?>
2200 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
2201   <url>
2202     <loc>http://www.example.com/</loc>
2203   </url>
2204   <url>
2205     <loc>http://www.example.com/products</loc>
2206   </url>
2207   <url>
2208     <loc>http://www.example.com/products/server</loc>
2209   </url>
2210   <url>
2211     <loc>http://www.example.com/products/studio</loc>
2212   </url>
2213   <url>
2214     <loc>http://www.example.com/company/about</loc>
2215   </url>
2216   <url>
2217     <loc>http://www.example.com/company/about/investors</loc>
2218   </url>
2219   <url>
2220     <loc>http://www.example.com/company/news</loc>
2221   </url>
2222   <url>
2223     <loc>http://www.example.com/community</loc>
2224   </url>
2225   <url>
2226     <loc>http://www.example.com/community/account</loc>
2227   </url>
2228   <url>
2229     <loc>http://forums.example.com/</loc>
2230   </url>
2231 </urlset>
2232 ]]></programlisting>
2233         </example>
2234
2235         <note>
2236             <title>UTF-8 encoding used by default</title>
2237
2238             <para>
2239                 By default, Zend Framework uses <acronym>UTF-8</acronym> as its default encoding,
2240                 and, specific to this case, <classname>Zend_View</classname> does as well. Character
2241                 encoding can be set differently on the view object itself using the
2242                 <methodname>setEncoding()</methodname> method (or the the
2243                 <varname>encoding</varname> instantiation parameter). However, since
2244                 <classname>Zend_View_Interface</classname> does not define accessors for encoding,
2245                 it's possible that if you are using a custom view implementation with the Dojo view
2246                 helper, you will not have a <methodname>getEncoding()</methodname> method, which is
2247                 what the view helper uses internally for determining the character set in which to
2248                 encode.
2249             </para>
2250
2251             <para>
2252                 If you do not want to utilize <acronym>UTF-8</acronym> in such a situation, you will
2253                 need to implement a <methodname>getEncoding()</methodname> method in your custom
2254                 view implementation.
2255             </para>
2256         </note>
2257     </sect4>
2258
2259     <sect4 id="zend.view.helpers.initial.navigation.navigation">
2260         <title>Navigation Helper</title>
2261
2262         <para>
2263             The Navigation helper is a proxy helper
2264             that relays calls to other navigational helpers. It can be
2265             considered an entry point to all navigation-related view tasks.
2266             The aforementioned navigational helpers are in the namespace
2267             <classname>Zend_View_Helper_Navigation</classname>, and would thus require
2268             the path <code>Zend/View/Helper/Navigation</code> to be added as
2269             a helper path to the view. With the proxy helper residing in the
2270             <classname>Zend_View_Helper</classname> namespace, it will always be
2271             available, without the need to add any helper paths to the view.
2272         </para>
2273
2274         <para>
2275             The Navigation helper finds other helpers that implement the
2276             <classname>Zend_View_Helper_Navigation_Helper</classname>
2277             interface, which means custom view helpers can also be proxied.
2278             This would, however, require that the custom helper path is added
2279             to the view.
2280         </para>
2281
2282         <para>
2283             When proxying to other helpers, the Navigation helper can inject
2284             its container, <acronym>ACL</acronym>/role, and translator. This means that you
2285             won't have to explicitly set all three in all navigational
2286             helpers, nor resort to injecting by means of
2287             <classname>Zend_Registry</classname> or static methods.
2288         </para>
2289
2290         <itemizedlist>
2291            <listitem>
2292                <para>
2293                    <methodname>findHelper()</methodname> finds the given helper,
2294                    verifies that it is a navigational helper, and injects
2295                    container, <acronym>ACL</acronym>/role and translator.
2296                </para>
2297            </listitem>
2298
2299            <listitem>
2300                <para>
2301                    <code>{get|set}InjectContainer()</code> gets/sets a flag
2302                    indicating whether the container should be injected to
2303                    proxied helpers. Default is <constant>TRUE</constant>.
2304                </para>
2305            </listitem>
2306
2307            <listitem>
2308                <para>
2309                    <code>{get|set}InjectAcl()</code> gets/sets a flag
2310                    indicating whether the <acronym>ACL</acronym>/role should be injected to
2311                    proxied helpers. Default is <constant>TRUE</constant>.
2312                </para>
2313            </listitem>
2314
2315            <listitem>
2316                <para>
2317                    <code>{get|set}InjectTranslator()</code> gets/sets a flag
2318                    indicating whether the translator should be injected to
2319                    proxied helpers. Default is <constant>TRUE</constant>.
2320                </para>
2321            </listitem>
2322
2323            <listitem>
2324                <para>
2325                    <code>{get|set}DefaultProxy()</code> gets/sets the default
2326                    proxy. Default is <code>'menu'</code>.
2327                </para>
2328            </listitem>
2329
2330            <listitem>
2331                <para>
2332                    <methodname>render()</methodname> proxies to the render method of
2333                    the default proxy.
2334                </para>
2335            </listitem>
2336        </itemizedlist>
2337     </sect4>
2338 </sect3>