#218: Increase Restrictions, and Ability to Change, Addable Portlet Types by Interface

Contents

1. Motivation
2. Assumptions
3. Proposal
4. Implementation
5. Deliverables
6. Risks
7. Progress log

Proposed by

George Lee

Proposal type

Architecture

Assigned to release

• Plone 3.1

Repository branch

plip218-addable-portlets-restrictions-and-changes

State

completed

Motivation

Currently, some portlet types (Calendar, Classic, News, Events, Recent, Review, RSS, and Search) can be added to any portlet manager -- for the left column, right column, and dashboard, but also any new portlet manager that is registered. This is because each of these portlet types has an attribute for_ set to None, and the portlet manager code interprets this as allowing it to be added to any portlet manager.

This means that any new portlet manager a developer adds to the site will have all these types addable, without it being easy to change this behavior.

In addition, when a portlet type is registered with a GenericSetup profile for a certain portlet manager interface, it is hard to change or extend this registration. For example, if a portlet type is registered with IColumn and IDashboard but we wish to instead register it for IOtherColumn -- or also register it for IOtherColumn -- there is no clear way to do this.

Assumptions

1. PLIP #205 is implemented.
2. Few people have created third-party products that register new portlet managers expecting Calendar, etc. or custom portlets to be available.
   

Proposal

1. Assuming that PLIP #205 is implemented, register the Calendar, Classic, News, Events, Recent, Review, RSS, and Search portlets for IColumn and IDashboard.
2. Modify the GenericSetup import handler to allow a "purge = False" or "extends" attribute which would allow an existing registered portlet type to be associated with more interfaces. "purge = True" would replace the existing portlet type instead of modifying it in place.  (I am unsure if this is the best approach -- feedback is welcome!)
   

Implementation

Documentation for the PLIP follows.

Upgrading Third-Party Products

If a third-party product has already created a new portlet manager that expects a default portlet (such as Calendar, RSS, etc.) to be addable, then this remains the case only if that portlet manager provides IColumn or IDashboard. If not, the product needs to either:

1. Have the portlet manager provide IColumn or IDashboard in its GenericSetup profile, and migrate the portlet managers on any existing sites to do so; or
2. Choose an interface ICustomColumn that the portlet manager provides, or provide a new one. In a GenericSetup profile, the way this is done remains the same as from before the PLIP -- ina portlets.xml, include a node like:

   <portletmanager name="plone.foo_column" type="foo.portlets.interfaces.ICustomColumn" />
   

   Then extend an existing portlet type to be addable for portlet managers with that interface. In a GenericSetup profile, include a portlets.xml with a node like:

   <portlet addview="portlets.Calendar" extend="">
     <for interface="foo.portlets.interfaces.ICustomColumn" />
   </portlet>
   

   Migrate existing sites by running this step as well.

Using portlets.xml

Example XML from portlets.xml using the new implementation:

Register a portlet type which can be added to exactly those portlet managers that implement IColumn or IDashboard:

<portlet addview="portlets.New" title="Foo" description="Foo">
  <for interface="plone.app.portlets.interfaces.IColumn" />
  <for interface="plone.app.portlets.interfaces.IDashboard" />
</portlet>

Register a portlet type which can be added to any portlet manager (techncially, any portlet manager that implements zope.interface.Interface):

<portlet addview="portlets.New" title="Foo" description="Foo" />

Register a portlet type which can be added to exactly those portlet managers that implement IColumn. Then modify that portlet type so that it can be added to exactly those portlet managers that implement IDashboard, and no longer those that only implement IColumn.

<portlet addview="portlets.ExtendMe" title="Foo" description="Foo">
  <for interface="plone.app.portlets.interfaces.IColumn" />
</portlet>
<portlet addview="portlets.ExtendMe" extend="">
  <for interface="plone.app.portlets.interfaces.IColumn" remove="" />
  <for interface="plone.app.portlets.interfaces.IDashboard" />
</portlet>

Register a portlet type. Then purge it -- remove it, but replace it with a portlet type with the same name but a different title, description, and associated portlet manager interfaces.

<portlet addview="portlets.PurgeMe" title="Foo" description="Foo">
  <for interface="plone.app.portlets.interfaces.IDashboard" />
</portlet>
<portlet addview="portlets.PurgeMe" purge="" title="Bar" description="Bar">
  <for interface="plone.app.portlets.interfaces.IColumn" />
</portlet>

Register a portlet type. Then remove it.

<portlet addview="portlets.PurgeMe" title="Foo" description="Foo"/>
<portlet addview="portlets.PurgeMe" remove="" />

Deliverables

1. Migration to re-register existing portlets for IColumn and IDashboard if they currently are registered for None.
   
2. Modify the import handler for portlets to support the purge or extends attributes.
3. Modify the export handler for portlets to expect at least one interface for for_ rather than None.
4. Test coverage
   

Risks

People may have already created third-party products that register new portlet managers expecting Calendar, etc. (or custom portlet types) to appear. We would have to explain how to migrate these portlet types manually by creating a new profile for migration.

Update: See documentation in the Implementation section.

Progress log

Code completed!