Plone 4: Overriding a class viewlet

I am a newbie Plone Developer. Recently, I needed to override a viewlet in Plone that had a python class in its definition instead of a simple template. This is what I did to customize the viewlet.

The steps for overriding a class viewlet does not differ much from overriding a simple template. So, I'll just cover the practical points of our use case.

Introduction
I suppose you are already familiar with how to find the viewlet you want to override, using @@manage-viewlets view. For this particular example let'e override plone.path_bar viewlet that is managed by plone.portaltop viewlet manager. It's the viewlet that renders a path bar (better known as the breadcrumbs) below the global navigation. In this example we will get rid of "You are here:" text in plone.path_bar viewlet.

1. Code that renders the viewlet
Let's have a look at how this viewlet is declared in configure.zcml inside the plone.app.layout.viewlets package:

    <!-- The breadcrumbs -->
    <browser:viewlet
        name="plone.path_bar"
        manager=".interfaces.IAboveContent"
        class=".common.PathBarViewlet"
        permission="zope2.View"
        />

As you can see this viewlet is rendered by a Zope 3 view, defined in common.PathBarViewlet class inside the plone.app.layout.viewlets package.

Here is how this class looks like:

class PathBarViewlet(ViewletBase):
    render = ViewPageTemplateFile('path_bar.pt')

    def update(self):
        portal_state = getMultiAdapter((self.context, self.request),
                                            name=u'plone_portal_state')

        self.navigation_root_url = portal_state.navigation_root_url()

        self.is_rtl = portal_state.is_rtl()

        breadcrumbs_view = getMultiAdapter((self.context, self.request),
                                           name='breadcrumbs_view')
        self.breadcrumbs = breadcrumbs_view.breadcrumbs()

We are not going to edit standard behavior of the viewlet in this example. The only thing we want is getting rid of "You are here:" text. Thus render = ViewPageTemplateFile('path_bar.pt') is exactly what we are interested in.

2. Customize the viewlet's template
render = ViewPageTemplateFile('path_bar.pt') line defines the page template for plone.path_bar viewlet. You can find path_bar.pt template inside the plone.app.layout.viewlets package. Let's make a copy of this template in the browser/ directory of MyTheme. No need to give it a different name.

Edit the template to remove the text we do not need:

<div id="portal-breadcrumbs"
     i18n:domain="plone">

    <!-- We use a comment to show what part we remove
    <span i18n:translate="you_are_here" id="breadcrumbs-you-are-here">
        You are here:
    </span>
    -->

    <a i18n:translate="tabs_home" tal:attributes="href
    view/navigation_root_url">Home</a>
    <span tal:condition="view/breadcrumbs" class="breadcrumbSeparator">
        <tal:ltr condition="not: view/is_rtl">→</tal:ltr>
        <tal:rtl condition="view/is_rtl">»</tal:rtl>
    </span>
    <span tal:repeat="crumb view/breadcrumbs"
        ...
    </span>

</div>

Now we need to make the plone.path_bar viewlet use this template for rendering.

3. Overriding a class that renders the template
Since ZCML declaration for plone.path_bar in lib/python/plone/app/layout/viewlets/configure.zcml uses a class instead of a simple template the core of customization is overriding that class also. For doing this we will simply subclass the default viewlet's class and apply our changes, so that they could override default ones. You have seen the default class used for this viewlet above in this page.

So, to subclass PathBarViewlet class we should add a new viewlets.py into MyTheme/browser/. This will be the place where you override classes, used for viewlets. Add the following to your viewlets.py:

from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile

from plone.app.layout.viewlets import common

class PathBarViewlet(common.PathBarViewlet):
    """A custom version of the path bar class
    """

    render = ViewPageTemplateFile('path_bar.pt')

As you can see we create a new class PathBarViewlet, that is a subclass of common.PathBarViewlet default class for the plone.path_bar viewlet. The only thing we need to override is the template used for rendering the viewlet. We already have customized path_bar.pt inside MyTheme/browser/, thus our new class reffers to our customized template.

3.1. Theme compatibility between different 3.x versions of Plone
Version 1.1.3 of the plone.app.layout egg was released in July of 2008. As of this version, the viewlet template is controlled via the 'index' attribute rather than 'render', because 'index' can be overridden by using the ZCML template attribute, removing the need for a special viewlet subclass. If you need to make a subclass anyway, you can continue to use the render directive as mentioned above if you want to, or you can use "index" instead, like this:

from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile

from plone.app.layout.viewlets import common

class PathBarViewlet(common.PathBarViewlet):
    """A custom version of the path bar class
    """

    index = ViewPageTemplateFile('path_bar.pt')

If you're going to distribute your theme and need to maintain backwards compatibility with the Plone 3.0.x series, additional code needs to be included. You should add the following lines that make the render method defer to the 'index' attribute. (This is done in ViewletBase in Plone 3.1.x, but not in Plone 3.0.x.):

from plone.app.layout.viewlets import common

class PathBarViewlet(common.PathBarViewlet):
    """A custom version of the path bar class
    """

    def render(self):
        # defer to index method, because that's what gets overridden by the template ZCML attribute
        return self.index()

    index = ViewPageTemplateFile('path_bar.pt')

Otherwise, themes created with newer versions of plone.app.layout will not be compatible with older versions of Plone.

That's it with the class. In case you need to customize not only the template, but viewlet's behavior, this is the right place to do so.

So far so good - we have the customized class, that uses the customized template. Now we need to register these customizations with MyTheme/browser/configure.zcml.

4. Register the custom viewlet in configure.zcml
In order to register the customized class with the plone.path_bar viewlet, we simply copy the portion of ZCML code that we found in lib/python/plone/app/layout/viewlets/configure.zcml (see above in this page) into MyTheme/browser/configure.zcml, and edit it to make sure it uses the right class and right interfaces for the manager and the Zope 3 skin layer:

<!-- The customized breadcrumbs -->
<browser:viewlet
    name="plone.path_bar"
    manager="plone.app.layout.viewlets.interfaces.IPortalTop"
    class=".viewlets.PathBarViewlet"
    layer=".interfaces.IThemeSpecific"
    permission="zope2.View"
    />

name and permission remain the same as in the default viewlet declaration. Although you could change name to make it clear that this is not a standard viewlet. You could use something like "MyTheme.path_bar" as the name here.

For manager we use the full dotted path to IPortalTop interface, implemented by plone.portaltop viewlet manager.

And the core part of our customization - we switch class to our customized class from MyTheme/browser/viewlets.py.

5. Additional step (Only if you have changed name for viewlet in ZCML)
If you have renamed your custom viewlet to "MyTheme.path_bar", you have created a new viewlet that has to be registered in your Generic Setup profile. To not have 2 path bars in your site, you should also hide the default plone.path_bar viewlet.

6. Done
Now you can restart your Zope. If you have your theme installed already, you need to reinstall it from Site Setup > Add-on Products.

Many thanks to this article.