Navigation (since pimcore 1.4.0)

Basics

Since version 1.3.3 pimcore comes with a standard navigation implementation in the form of a view helper, which utilizes Zend_Navigation. The Pimcore_View_Helper_PimcoreNavigation gets registered by default with the other pimcore view helpers. It builds a Zend_Navigation container based on the existing document structure and needs to be set up as follows in your view script or layout script:

Only documents are included in this structure, directories are ignored, regardless of their navigation properties.

<?php
    
    // get root node if there is no document defined (for pages which are routed directly through static route)
    if(!$this->document instanceof Document_Page) {
        $this->document = Document::getById(1);
    }

    // get the document which should be used to start in navigation | default home
    $navStartNode = $this->document->getProperty("navigationRoot");
    if(!$navStartNode instanceof Document_Page) {
        $navStartNode = Document::getById(1);
    }

    //this is used as id prefix for the html menu element
    $htmlIdPrefix = "mainNav_";

    $navigation = $this->pimcoreNavigation()->getNavigation($this->document, $navStartNode, $htmlIdPrefix);
    $this->navigation()->menu()->setUseTranslator(false); // to deactivate the translator provided by the view helper
    $this->navigation($navigation);

?>

Having set up the navigation view helper as shown above, you can easily use the Zend Navigation Helpers to render a navigation tree, or breadcrumbs:

<!-- META NAVIGATION - ONLY 1st LEVEL -->
<?php
    echo $this->navigation()->menu()->renderMenu($navigation, array("maxDepth" => 0));
?>

...

<!-- BREADCRUMBS -->
<div>
    <a href="/">Home</a> &gt;
    <?php echo $this->navigation()->breadcrumbs()->setMinDepth(null); ?>
</div>

...

<!-- SIDEBAR NAVIGATION -->
<div id="sidebar">
    <div id="navigation">
        <?php echo  $this->navigation()->menu()->renderMenu($navigation); ?>
    </div>
</div>

<!-- SIDEBAR NAVIGATION WITH A DIFFERENT HTML PREFIX --!>
<div id="sidebar">
    <div id="navigation">
        <?php
        $htmlIdPrefix = "subnav_";
        //generate container with different html prefix
        $navigation = $this->pimcoreNavigation()->getNavigation($this->document, $this->navStartNode,$htmlIdPrefix);
        echo $this->navigation()->menu()->renderMenu($navigation);
        ?>
    </div>
</div>

The renderMenu() method renders the menu to the deepest available level. Levels trees which are not within the active tree, and levels below the latest active page must be hidden using css. The example css below shows how to do that (includes 3 Levels)

#navigation ul li ul {
    display:none;
}

#navigation ul li.active ul {
    display:block;
}

#navigation ul li.active ul li ul {
    display:none;
}

#navigation ul li.active ul li.active ul {
    display:block;
}

#navigation ul li.active ul li.active ul li ul {
    display:none;
}

#navigation ul li.active ul li.active ul li.active ul{
    display:block;
}

Setting a Document's Navigation Properties in pimcore

Pages and links have "Navigation Settings" in their system properties as shown in the screen above. These navigation settings include the following properties:

Name: Document's name used in the navigation (Label)

Title: Document's title used in the navigation - the HTML Attribute title

Target: Link Target (_blank, _self, _top, _parent)

Exclude from Navigation: Property to quickly exclude a Page from Navigation

getProperty("navigation_exclude")

Class: HTML class of the navigation element

Anchor: Anchor appended to the document's URL

Parameters: Parameters appended to the document's URL

Relation: Only available in custom navigation script. Supposedly the HTML rel attribute to open the link in a sort of Lightbox / Clearbox

Accesskey: Only available in custom navigation script

Tab-Index: Only available in custom navigation script

Individual (Partial) Navigation View Script

If the standard HTML output of the render() method is not suitable for a project, there is the possibility to provide a custom script for the menu HTML. This can be achieved using the renderPartial() method of theZend Menu Helper.

Additional Navigation Properties of a Document_Link (Tabindex, Accesskey, Relation)

A Document_Link has 3 properties which are not covered by Zend_Navigation by default. These are tabindex, accesskey and relation. Since the Zend_Navigation container contains instances of Pimcore_Navigation_Page_Uri, which extend Zend_Navigation_Page_Uri, these additional properties are available and accessible through their according getters. Consequently, they can be regarded in an individual (partial) view script for the navigation, but will be ignored by the default render() methods.

Using the Navigation Helper with (Sub-) Sites (since 1.4.3)

For example: 

$navStartNode = $this->document->getProperty("navigationRoot");
if(!$navStartNode instanceof Document_Page) {
    if(Site::isSiteRequest()) {
        $site = Site::getCurrentSite();
        $navStartNode = $site->getRootDocument();
    } else {
        $navStartNode = Document::getById(1);
    }
}

$navigation = $this->pimcoreNavigation()->getNavigation($this->document, $navStartNode);
$this->navigation($navigation);

FAQ

A document does not show up in the navigation. Why?

Please make sure, that the documents and it's parent documents are published and that the document it self as well as all it's parents have a navigation name set. Neither the document itself nor one of it's parent documents may have activated "Exclude From Navigation" in their properties. (Document properties -> system property)

Why does the navigation does not appear?

See the above question. If none of the documents have a navigation title set the render function will simply return nothing.