customizing navigation in Plone3

things not to do

Clinging to the old ways is a dead-end time sink. Doing a locate portlet_navigation.pt turns up a portlet template in parts/plone/CMFPlone/skins/plone_deprecated. But this one is truly deprecated. It's not active in a default Plone3 installation.

The actual live templates live in eggs/plone.app.portlets-1.1.3-py2.4.egg/plone/app/portlets/portlets or something like that with a different version number. The relevant files are:

navigation.py

the python module that powers the navigation portlet

navigation.pt

the wrapper template for portlet border, header and footer

navigation_recurse.pt

the renderer for the actual navigation tree

You can customize navigation.pt by putting it into your theme browser layer and activating it with zcml. But that doesn't help you much if you want to customize the actual navigation entries.

Customizing navigation_recurse.pt cannot be done via a mere zcml declaration. You'll have to customize the Renderer class in the navigation module as well. Here's how it's done. After that, I'll explain the why.

how to customize the navigation portlet

Copy the navigation*pt templates from eggs/plone.app.portlets-1.1.3-py2.4.egg/plone/app/portlets/portlets/navigation*pt into your theme's browser/templates directory. Don't copy navigation.py!

In your theme's browser directory, create your own navigation.py. It needs only the following measly five lines of code:

from plone.app.portlets.portlets.navigation import Renderer

from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile

class MyNavRenderer(Renderer):
    
     _template = ViewPageTemplateFile('templates/navigation.pt')
     recurse = ViewPageTemplateFile('templates/navigation_recurse.pt')

In your browser/configure.zcml put the following lines:

<!-- Customize the navigation portlet -->
       <plone:portletRenderer
       portlet="plone.app.portlets.portlets.navigation.INavigationPortlet"
       layer=".interfaces.IThemeSpecific"
       class=".navigation.MyNavRenderer"
       />

That's all, you can now customize both the outer and the recursing navigation templates in your theme's browser/templates as you wish.

understanding the component architecture

This all looks very simple, and it is, if you know the how. To remember the how, and be able to apply it in similar contexts, it helps to really understand what's going on.

Templates aren't "just called" from some skin layer anymore. Configuration files determine, which views are activated. Views are usually implemented as python classes, with TAL templates as helpers. This has important security and performance benefits, and also makes it very easy to implement python logic in your views.

Here's a simplified activity diagram for the way in which the navigation portlet is rendered:

The navigation.py module in plone.app.portlets contains a Renderer class. Renderer.render() is called to render the porlet. Makes sense, innit?

The render() method activates the navigation.pt template. So far, so good, we're back in TAL. BUT: the navigation.pt template makes a call back to the python module: Renderer.createNavTree().

Via recurse(), this activates the navigation_recurse.pt template. That template also calls the Renderer.recurse() method, which activates a new navigation_recurse.pt template, and so on, until we've looped over all levels in our site.

The results are then stitched together and returned.

summary

We achieve our customizations by

appointing our own rendering class in our local browser zcml

       class=".navigation.MyNavRenderer"

appointing our own local templates from the rendering class

     _template = ViewPageTemplateFile('templates/navigation.pt')
     recurse = ViewPageTemplateFile('templates/navigation_recurse.pt')

Because MyNavRenderer subclasses the default Renderer, the rest of the logic is still handled from plone.app.portlets.