feature/tutorials.navigations.rst

docs/languages/en/index.rst

@@ -24,6 +24,7 @@
    modules/zendtool.introduction
    tutorials/quickstart.di
    tutorials/unittesting
+   tutoirals/tutorials.navigation
    modules/zend.authentication.intro
    modules/zend.authentication.adapter.dbtable
    modules/zend.authentication.adapter.digest
@@ -286,6 +287,7 @@
 
     * :doc:`tutorials/quickstart.di`
     * :doc:`tutorials/unittesting`
+    * :doc:`tutorials/tutorials.navigation`
 
 |ZendFrameworkReference|
 ------------------------

docs/languages/en/tutorials/tutorial.navigation.rst

@@ -0,0 +1,236 @@
+Using Zend Navigation in your Album module
+==========================================
+
+In this tutorial we will use ``Zend\Navigation`` to add a navigation
+menu to the black bar at the top of the screen, and add breadcrumbs
+above the main site content.
+
+Preparation
+-----------
+
+In order to have more than one area of the tutorial application, let's
+undo some work we did earlier. Currently, navigating to the root of your
+app (/) routes you to the ``AlbumController``'s default action. Let's
+undo this route change so we have two discrete entry points to the app,
+a home page, and an albums area.
+
+``module/Application/config/module.config.php``
+
+::
+
+    'home' => array(
+       'type' => 'Zend\Mvc\Router\Http\Literal',
+        'options' => array(
+            'route'    => '/',
+            'defaults' => array(
+                'controller' => 'Application\Controller\Album', // <-- change back here
+                'action'     => 'index',
+            ),
+        ),
+    ),
+
+This change means that if you go to the home page of your application
+(http://zf2-tutorial.localhost/), you see the default skeleton
+application introduction. Your list of albums is still available at the
+/album route.
+
+Setting Up Zend
+---------------
+
+Firstly, we need to tell our application which ``NavigationFactory`` to
+use when using the bundled navigation view helpers. Thankfully, ZF2
+comes with a default factory that will suit our needs just fine. To tell
+ZF2 to use this default factory, we simply add a ``navigation`` key to
+the service manager. It's best to do this in the ``Application`` module,
+because, like the translation data this is specific to the entire
+application, and not just to our album pages:
+
+``module/Application/config/module.config.php``
+
+::
+
+    'service_manager' => array(
+        'factories' => array(
+            'translator' => 'Zend\I18n\Translator\TranslatorServiceFactory',
+            'navigation' => 'Zend\Navigation\Service\DefaultNavigationFactory', \\ <-- add this
+        ),
+    ),
+
+Configuring our Site Map
+------------------------
+
+Next up, we need ``Zend\Navigation`` to understand the hierarchy of our
+site. Thankfully, if we add a ``navigation`` key to our merged config,
+the navigation factory will automagically create the container and pages
+needed to use the view helpers. Let's do this in the ``Application``
+module:
+
+``module/Application/config/module.config.php``
+
+::
+
+    return array(
+    ...
+    'navigation' => array(
+        'default' => array(
+            array(
+                'label' => 'Home',
+                'route' => 'home',
+            ),
+            array(
+                'label' => 'Album',
+                'route' => 'album',
+                'pages' => array(
+                    array(
+                        'label' => 'Add',
+                        'route' => 'album',
+                        'action' => 'add',
+                    ),
+                    array(
+                        'label' => 'Edit',
+                        'route' => 'album',
+                        'action' => 'edit',
+                    ),
+                    array(
+                        'label' => 'Delete',
+                        'route' => 'album',
+                        'action' => 'delete',
+                    ),
+                ),
+            ),
+        ),
+    ),
+    ...
+    );
+
+This configuration maps out the pages we've defined in our controller,
+with labels linking to the given route names. You can define highly
+complex heirachical sites here with pages and sub-pages linking to route
+names, controller/action pairs or external uris. For more information
+see the docs
+`here <http://framework.zend.com/manual/2.1/en/modules/zend.navigation.quick-start.html>`__.
+
+Adding the Menu View Helper
+---------------------------
+
+Now that we have the navigation helper configured by our service manager
+and merged config, we can easily add the menu to the title bar to our
+layout by using the ``menu`` view helper:
+
+``module/Application/view/layout/layout.phtml``
+
+::
+
+    ...
+    <a class="brand"
+           href="<?php echo $this->url('home') ?>"><?php echo $this->translate('Skeleton Application') ?></a>
+    <?php // <-- Add this !!
+    echo $this->navigation()->menu('navigation');
+    ?>
+    ...
+
+The navigation helper is built in to Zend Framework 2, and uses the
+service manager configuration we've already defined to configure itself
+automatically. Refreshing your application you will see a working (but
+ugly) menu, with just a few tweaks however, we can make it look awesome:
+
+``module/Application/view/layout/layout.phtml``
+
+::
+
+    <a class="brand"
+       href="<?php echo $this->url('home') ?>"><?php echo $this->translate('Skeleton Application') ?></a>
+    <?php // <-- Update this !!
+    echo $this->navigation()
+        ->menu('navigation')
+        ->setMinDepth(0)
+        ->setMaxDepth(0)
+        ->setUlClass('nav')
+        ->render();
+    ?>
+
+Here we tell the renderer to give the root UL the class of 'nav' so that
+Twitter Bootstrap styles the menu correctly, and only render the first
+level of any given page. If you view your application in your browser,
+you will now see a nicely styled menu appear in the title bar. The great
+thing about ``Zend\Navigation`` is that it integrates with ZF2's route
+so can tell which page you are currently viewing. Because of this, it
+set's the active page to have a class of ``active`` in the menu. Twitter
+Bootstrap uses this to highlight your current page accordingly.
+
+Adding Breadcrumbs
+------------------
+
+Adding breadcrumbs is initially just as simple. In our ``layout.phtml``
+we want to add breadcrumbs above the main content pane, so our foolish
+user knows exactly where they are in our complex website. Inside the
+container div, before we output the content from the view, let's add a
+simple breadcrumb:
+
+``module/Application/view/layout/layout.phtml``
+
+::
+
+    ...
+    <div class="container">
+        <?php echo $this->navigation()->breadcrumbs('navigation')->setMinDepth(0); // <-- Add this!! ?>   
+        <?php echo $this->content; ?>
+    </div>
+    ...
+
+This adds a simple but functional breadcrumb to every page (we simply
+tell it to render from a depth of 0 so we see all level of pages) but we
+can do better than that! Because Bootstrap has a styled breadcrumb as
+part of it's base CSS, so let's add a partial that output's the UL in
+bootstrap happy CSS. We'll create it in the ``view`` directory of the
+``Application`` module (this partial is application wide, rather than
+album specific):
+
+``module/Application/view/partial/breadcrumb.phtml``
+
+::
+
+    <ul class="breadcrumb">
+        <?php
+        // iterate through the pages
+        foreach ($this->pages as $key => $page):
+            ?>
+            <li>
+                <?php
+                // if this isn't the last page, add a link and the seperator
+                if ($key < count($this->pages) - 1):
+                    ?>
+                    <a href="<?php echo $page->getHref(); ?>"><?php echo $page->getLabel(); ?></a>
+                    <span class="divider">/</span>
+                    <?php // otherwise, just output the name
+                    else:
+                    ?>
+                    <?php echo $page->getLabel(); ?>
+                    <?php endif; ?>
+            </li>
+            <?php endforeach; ?>
+    </ul>
+
+Notice how the partial is passed a Zendinstance with the ``pages``
+property set to an array of pages to render. Now all we have to do is
+tell the breadcrumb helper to use the partial we have just written:
+
+``module/Application/view/layout/layout.phtml``
+
+::
+
+    ...
+    <div class="container">
+        <?php echo $this->navigation() // <-- Update this!!
+        ->breadcrumbs('navigation')
+        ->setMinDepth(0)
+        ->setPartial(array('partial/breadcrumb.phtml', 'Album'));
+        ?>
+        <?php echo $this->content; ?>
+    </div>
+    ...
+
+Refreshing the page now gives us a lovely styled set of breadcrumbs on
+each page.
+
+FIN