Portlets

The portlets.xml file lets you register portlets and portlet managers. For more info about the portlets infrastructure, check the Portlets chapter of the Developer Manual.

Let's see an excerpt of the Plone portlets.xml file:

<?xml version="1.0"?>
<portlets
    xmlns:i18n="http://xml.zope.org/namespaces/i18n"
    i18n:domain="plone">
 ...
 <portletmanager 
   name="plone.leftcolumn" 
   type="plone.app.portlets.interfaces.ILeftColumn"
   />
 ...
 <portlet 
   addview="portlets.News"
   title="News"
   description="A portlet which can render a listing of recent news"
   i18n:attributes="title;
                    description"
   >
   <for interface="plone.app.portlets.interfaces.IColumn" /> 
   <for interface="plone.app.portlets.interfaces.IDashboard" />  
 </portlet>
</portlets>

The <portletmanager /> node registers a portlet manager. The available attributes are:

name

The name of the utility providing the IPortletManager interface which will be instantiated.

type

A marker interface that can be used to install particular portlets only for particular types of portlet managers later.

The <portlet> node registers a portlet. The available attributes are:

addview

Somewhat confusing, should match the portlet name as registered in ZCML.

title and description

Human friendly text to be shown in the Plone user interface.

The <for /> nodes inside the <portlet> one specify the interfaces of the type of portlet managers that this portlet is suitable for.

The

<portlet addview="portlets.BBB" 

         title="Foo" 

         description="Foo" 

         for="plone.app.portlets.interfaces.IColumn" />

syntax to specify the allowed portlet manager interfaces was deprecated in Plone 3.1 and won't work in Plone 4.

Assigning portlets

You can assign portlets to certain parts of the site upon product installation using Generic Setup too. For example:

 <assignment
     manager="plone.rightcolumn"
     category="context"
     key="/"
     type="portlets.News"
     name="news"
     visible="1"
     />

The visible attribute was introduced in Plone 4. If not present or equal to "1", the portlet will be shown. If it's equal to "0", it will be hidden.

You can use the insert-after and insert-before attributes matching an existing assignment or all them with "*". For example:

 <assignment
     insert-before="events"
     manager="plone.rightcolumn"
     category="context"
     key="/"
     type="portlets.News"
     name="news"
     />

will insert the news portlet just before the events one.

You can also remove a certain assignment:

 <assignment
     remove="True"
     manager="plone.rightcolumn"
     category="context"
     key="/"
     type="portlets.News"
     name="news"
     />

Or remove (purge)all the assignments from a certain manager:

 <assignment
     purge="True"
     manager="plone.rightcolumn"
     category="context"
     key="/"
     />

The key attribute matches "/" for site-wide portlets and an absolute Zope path for context-wide ones. For example, if you want to remove all assignments from Plone/news, use:

 <assignment
     purge="True"
     manager="plone.rightcolumn"
     category="context"
     key="/Plone/news"
     />