Portlet Manager

« Return to page index

Plone Theme Reference

1. Moving or Removing a Portlet Manager

Tips on how to move or remove portlet managers.

Portlet managers are called by main_template. Moving or removing them is simply a case of customizing the template.

Through the Web

  • Site Setup > Zope Management Interface > portal_skins > plone_templates > main_template
  • Customize this, and look for 
    <div tal:replace="structure provider:[portlet manager name]" />

  • (use the Elements key to identify exactly which manager you're interested in)

In your own product

  • Put your own version of main_template in

    [your theme product]/skins.

2. Hiding a Portlet Manager

There are several methods for hiding a portlet manager.

A portlet manager won't display if there are no portlets assigned to it to display or if the assigned portlets have no data.

In the case of the portlet columns, if the portlet manager is empty, then it is also useful to have the surrounding block elements disappear too, so that you don't get a wide blank margin on your page. For this reason, the columns containing the portlet managers in the main_template are wrapped around with slots. Hiding the portlet managers is, therefore, a matter or manipulating these slots. There are various techniques:

Defining an empty slot
Use the following in a content view template to ensure that the right hand column is removed:
  • <metal:column_one fill-slot="column_one_slot" />
Using the sl and sr global variables
These are set as conditions on the slots; they check the respective portlet managers for content and, if they are empty, evaluate to false. You can override these in the template itself.
Using show_portlets option
show_portlets=false can be passed as an option to a template to set both sl and sr to false. To see this in action, have a look at
  • CMFPlone/skins/plone_templates/standard_error_message.py and
  • CMFPlone/browser/ploneview.py

3. Creating a New Portlet Manager

How to create a new portlet manager.

A practical example of creating a new portlet manager can be found here

Here's a quick checklist of what you need to do.

Quick Cheat Sheet

Through the Web

You cannot create a new portlet manager through the web.

In your own product

You will need to provide the name of

Your theme-specific interface
This is optional but ensures that your portlet manager is available for your theme only. If you used the plone3_theme paster template, then the name will probably be IThemeSpecific.

You will need to create the following (you should be able to locate the originals to copy by looking them up in the elements section):

Interface
This will go in [your theme package]/browser/interfaces.py. You can give it any name you like, but by convention, it should be prefaced with "I".
configuration directive
[your theme package]/profiles/default/portlets.xml
browser:page directive (for the management view)
[your theme package]/browser/configure.zcml
page template (for the management view)
[your theme package]/browser/[your template].pt

Sample interface

from plone.portlets.interfaces import IPortletManager

class [your portlet manager interface](IPortletManager):
 """A description goes here    """

Sample portlets.xml

<?xml version="1.0"?>
<portlets>
 <portletmanager
    name="[your namespace].[your portlet manager]"
    type="[your namespace].[your theme name].browser.interfaces.[your portlet manager interface]"
 />
</portlets>

Sample configure.zcml directive (for the management view)

<browser:page
 for="plone.portlets.interfaces.ILocalPortletAssignable"
 class="plone.app.portlets.browser.manage.ManageContextualPortlets"
 name="[your view name]"
 template="[your template name].pt"
 permission="plone.app.portlets.ManagePortlets"
/>

4. Practical

Practical

4.1. Adding Portlet Managers

You need portlets at an additional place in your Plone. In this example we put contextual portlets above the content (contributed by Jens Klein)

This is about adding Portlet MANAGERS, hint: PortletManager != Portlet. A PortletManager is a kind of container for the portlets, like the ViewletManager is for Viewlets. So, after reducing the momentum of misunderstanding, lets start:

Prerequsites

I assume you're familar with GenericSetup based setups for Plone 3. Take a look at DIYPloneStyle and related tutorials if not.

You need Plone 3 installed and a Product NEWTHEME for your own skin (based on DIYPloneStyle works fine).

Strategy

In my example I don't want to customize the main-template. So the idea is to add a viewlet to the plone.app.layout.viewlets.interfaces.IContentViews viewletmanager. So the steps need to be done is

  1. Add a viewlet to the viewlet-manager
  2. Add a portlet-manager
  3. Add a management view for the portlet-manager.

Step One: Add a viewlet

in Products.NEWTHEME add a file abovecontentportlets.pt containing: 
<tal:block replace="structure provider:my.abovecontentportlets" />

Here we call the portlet manager, we create it in step two.
But first lets register our new viewlet for the viewletmanager.
Edit your Products/NEWTHEME/configure.zcml and add:

<browser:viewlet
    name="my.abovecontentportlets"
    manager="plone.app.layout.viewlets.interfaces.IContentViews"
    template="abovecontentportlets.pt"
    permission="zope2.View" 
/>

Step Two: Add a portlet manager

Create a marking interface for the manager and add or edit Products/NEWTHEME/interfaces.py

from plone.portlets.interfaces import IPortletManager

class IMyAboveContent(IPortletManager):
    """we need our own portlet manager above the content area.
    """

Add (or edit) your Products/NEWTHEME/profiles/default/portlets.xml and register a portlet manager:

<?xml version="1.0"?>
<portlets> 
 <portletmanager 
   name="my.abovecontentportlets"
   type="Products.NEWTHEME.interfaces.IMyAboveContent"
 />
</portlets>

Thats all you need if you don't want to manage the portlets through the web. Oh, you want to? So you need a third step:

Step Three: Add a management view for the portlet manager

The management view is rendered for the left and right slots directly on the main-template. But we use a viewlet and in here we have a different view. so we need to call explicitly our view and call the our manager within its context.

 

We need to register a new browser view for an own page template directly calling our manager. Again add some lines to your configure.zcml: 
<browser:page
    for="plone.portlets.interfaces.ILocalPortletAssignable"
    class="plone.app.portlets.browser.manage.ManageContextualPortlets"
    name="manage-myabove"
    template="templates/managemyabove.pt"
    permission="plone.app.portlets.ManagePortlets"
/>
And finally we need the template, so add an file managemyabove.pt and edit it:

 

<html xmlns="http://www.w3.org/1999/xhtml"
      xmlns:metal="http://xml.zope.org/namespaces/metal"
      xmlns:tal="http://xml.zope.org/namespaces/tal"
      xmlns:i18n="http://xml.zope.org/namespaces/i18n"
      metal:use-macro="context/main_template/macros/master"
      i18n:domain="plone">
<head>
    <div metal:fill-slot="javascript_head_slot" tal:omit-tag="">
        <link type="text/css" rel="kinetic-stylesheet"
            tal:attributes="href string:${context/absolute_url}/++resource++manage-portlets.kss"/>
    </div>
</head>
<body>
<div metal:fill-slot="main">
  <h1 class="documentFirstHeading">Manage My Portlets</h1>
  <span tal:replace="structure provider:my.abovecontentportlets" />
</div>
</body>
</html>
That's it. After restarting your zope you can call http://DOMAIN.TLD/plone/path/to/some/context/@@manage-myabove

and assign portlets over your content.