Ordering

If all you need is to reorder the viewlets in the Plone Default skin, you can simply copy the original viewlets.xml from CMFPlone/profiles/default/ into MyTheme/profiles/default/, and edit the copied file to make it reflect your needs.

But you may want to order viewlets with more flexibility. Be happy: there are handy parameters for each node in viewlets.xml.

Let's see how would look a viewlets.xml file for a 3rd party theme product:

<?xml version="1.0"?>

<object>

  <order manager="plone.portalheader" skinname="My Theme"
         based-on="Plone Default">
    <viewlet name="plone.logo" insert-before="*"/>
  </order>
  <order manager="plone.portaltop" skinname="*">
    <viewlet name="plone.app.i18n.locales.languageselector"
             insert-after="plone.path_bar"/>
  </order>

</object>

The above code contains two <order /> declarations: The first one creates a new skin named My Theme which is based on the Plone Default one. This means that the new skin inherits from the viewlets ordering of the skin it is based on. In our example, the plone.logo is moved at the first position in the plone.portalheader viewlet manager. The second declaration moves plone.app.i18n.locales.languageselector right after plone.path_bar in the plone.portaltop viewlet manager for all skins (notice the skinname="*" statement).

Note

Both DIYPloneStyle and ZopeSkel add a viewlets.xml file when generating a blank theme product (use --add-viewlet-example with the DIYPloneStyle generator script).

For your convenience, you can find inline documentation about the parameters that can be used in the generated file (It is an option with ZopeSkel, answer 'True' when it asks for it).

Hiding

Hiding a viewlet is also done from the viewlets.xml with the <hidden /> node which is at same level as <order />, and is done per skin selection.

For instance, if you need to remove the global sections for your skin, you'd have to add some declaration like the following one to viewlets.xml:

<hidden manager="plone.portalheader" skinname="My Theme">
  <viewlet name="plone.global_sections" />
</hidden>

Unhiding

If, for any reason, you need to unhide one or more viewlets for a given viewlet manager, you can make use of the purge and remove node parameters in your <hidden /> declaration in viewlets.xml.

To unhide all hidden viewlets for a given viewlet manager:

<?xml version="1.0"?>
<object>
  <hidden manager="plone.portalheader" skinname="Plone Default"
          purge="True" />
</object>

To unhide specific viewlet(s):

<?xml version="1.0"?>
<object>
  <hidden manager="plone.portalheader" skinname="Plone Default">
    <viewlet name="plone.global_sections" remove="True" />
  </hidden>
</object>

Note

The purge and remove node parameters are also supported inside the <order /> declaration.

Nothing that difficult here ;-)

Example

First, lets have a look at one of the examples that are shipped with DIYPloneStyle (version 3.0 is out, still beta but useable) in order to have a better understanding of the machinery: The credits_viewlet product that is located in DIYPloneStyle/example/ adds a new viewlet to the portal footer region.

In the credits_viewlet code, in its browser/ folder, we have a set of files:

- browser/
    - __init__.py
    - configure.zcml
    - interfaces.py
    - logo.pt
    - viewlets.py

__init__.py

This is an empty file, that is here simply to make browser a python package.

configure.zcml

The file where all Zope 3 configuration is defined for browser.

interfaces.py

We'll need this file a bit later, I leave it where it is for now.

logo.pt

The template that will replace the original HTML code in the main template.

viewlets.py

The file that stores viewlet Python classes.

In the same DIYPloneStyle/example/credits_viewlet subfolder, we find the profiles/ repository that stores the Generic Setup configuration files: skins.xml and viewlets.xml.

Practice

Let's get back to our own MyTheme product and reproduce the example we just had a look at.

from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile
from plone.app.layout.viewlets.common import ViewletBase

DESIGNER = 'John Doe'

class CreditsViewlet(ViewletBase):
    render = ViewPageTemplateFile('credits.pt')

    def update(self):
        # set here the values that you need to grab from the template.
        # stupid example:
        self.designer = DESIGNER

<div id="design-credits"
     i18n:domain="custom_i18n_domain">

    <span i18n:translate="design_by">Design by:
        <span tal:omit-tag="python:True"
              tal:content="view/designer"
              i18n:name="designer">Terry Gilliam</span>.</span>

</div>

<configure
    xmlns="http://namespaces.zope.org/zope"
    xmlns:browser="http://namespaces.zope.org/browser"
    i18n_domain="custom_i18n_domain">

    <browser:viewlet
        name="example.credits"
        manager="plone.app.layout.viewlets.interfaces.IPortalFooter"
        class=".viewlets.CreditsViewlet"
        permission="zope2.View"
        />

</configure>

<configure
   xmlns="http://namespaces.zope.org/zope"
   xmlns:browser="http://namespaces.zope.org/browser">

   <include file="profiles.zcml" />

   <include package=".browser" />

</configure>

<?xml version="1.0"?>
<object>
  <order manager="plone.portalfooter" skinname="Credits Viewlet Theme"
         based-on="Plone Default">
    <viewlet name="example.credits" insert-before="plone.colophon" />
  </order>
</object>

<?xml version="1.0"?>
<object name="portal_skins">

    <skin-path name="Credits Viewlet Theme" based-on="Plone Default" />

</object>

Theory

The key concept here is the use of a Zope 3 skin layer.

We saw in the previous chapter how to make use of a Zope 3 skin layer to make sure that the viewlet we added to our theme would not render in any other one. In this chapter we will make use of the same skin layer to override a default Plone viewlet with a custom one.

Principle is this:

In our product (or package), we declare in configure.zcml a viewlet that has the same name as one of the Plone default viewlets, but with a different constructor class or template than the original one (We can use a template even if the original declares a class and vice and versa).

By using the layer attribute in the custom viewlet zcml declaration, we register the viewlet for a Zope 3 skin layer. That skin layer has the same name as the name of the theme that is added to the portal_skins tool.

Zope 3 skin layers are bound to skin selections in portal_skins (themes) thanks to the plone.theme package. Which means that a skin layer is applied if its name matches the name of the selected skin in portal_skins.

A viewlets that is registered for a skin layer is rendered when that layer is applied, and overrides any other viewlet that has the same name but which is not registered for that layer.

Practice

Let's see how we can apply this viewlet overriding within MyTheme, the product that we started to develop in the previous chapters.

Our goal here is to have the footer rendering a different text than the default Plone one in our theme.

2. Identifying which viewlet to override

We have to identify which viewlet we want to override, and for which viewlet manager it is registered.

Plone ships with a basic user interface for reordering and hiding/showing viewlets inside their viewlet managers. To access that configuration page, point your browser to the URL http://localhost:8080/portal/@@manage-viewlets (or equivalent based on your Zope/Plone installation).

The viewlets management page should look like this one (rendered with the Plone Default theme):

By the end of that page, we can identify the footer region, and note that it is rendered by a viewlet manager called plone.portalfooter. We can also see that two viewlets are registered with plone.portalfooter: plone.footer and plone.colophon. plone.footer is our target: it is the one that we want to see rendered differently in our theme.

<!-- Footer -->
<browser:viewlet
   name="plone.footer"
   for="*"
   manager=".interfaces.IPortalFooter"
   template="footer.pt"
   permission="zope.Public"
   />

<div id="portal-footer" i18n:domain="plone">
  <p>
    <span i18n:translate="design_author" tal:omit-tag="">
      Design by
      <span i18n:name="author" tal:omit-tag="">
        <a href="http://mypage.org">John Doe</a>
      </span>.
    </span>
  </p>
</div>

<!-- The customized footer -->
<browser:viewlet
   name="plone.footer"
   for="*"
   manager="plone.app.layout.viewlets.interfaces.IPortalFooter"
   layer=".interfaces.IThemeSpecific"
   template="footer.pt"
   permission="zope.Public"
   />

Other example

Another example of viewlet overriding can be found in DIYPloneStyle/example/custom_footer/. It is quite easy to understand and should be self explanatory now that you read most of this chapter.

This example is slightly different than the one we just covered though: the new viewlet uses a Zope 3 browser view for its rendering. Principles are the same anyway.

The product layout on the file system is also a bit different than the one typically found in a product generated by DIYPloneStyle or ZopeSkel. All viewlet code is kept at first level package in a browser.py module. There is no browser sub-package (folder). This is for showing that there is more than one only possible layout for organizing a plone theme package/product.

• In browser.py, we find IThemeSpecific, the interface of the Zope 3 skin layer, and FooterViewlet, the viewlet class that overrides the default plone one.
• footer.pt is the template rendered by FooterViewlet.
• profiles/default/ is the usual Generic Setup profile for the product.
• The interface, the viewlet and the product Generic Setup profile are all declared in a single configure.zcml.

And now… happy customizing!

Introduction

We suppose you are already familiar with how to find the viewlet you want to override, using @@manage-viewlets view from the previous chapter. For this particular example let's 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.IPortalTop"
    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 id="breadcrumbs-you-are-here" i18n:translate="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">&rarr;</tal:ltr>
        <tal:rtl condition="view/is_rtl">&raquo;</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 in p.1 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.

Actually 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 p.1 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" 
    />

Use of layer=".interfaces.IThemeSpecific" has been explained in the previous chapter.

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. To remember how to hide existing viewlet and register the new one, please refer to page 3 of this tutorial.

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.

After all these steps you should not see "You are here:" text any more in your breadcrumbs.