#203: Manage portlet assignments with GenericSetup

It should be easy to create an initial set of portlets using a GenericSetup extension or base profile. This makes it easier to create extension profiles to set up a site with a standard set of portlets.

Any portlet that is to be importable in this manner needs to have a no-arg constructor, and an interface that uses zope.schema fields to specify the configurable aspects of the portlet. 

Provide a GenericSetup syntax for assigning and configuring portlets, as well as for blacklisting (blocking) categories of portlets in specific locations.

Portlets assignments have several dimensions:

1. The assignment type - this is a class, described by an interface, responsible for persisting portlet settings
2. The attributes set on the assignment
3. The portlet manager (column) where the assignment is made - typically plone.leftcolumn or plone.rightcolumn, though the dashboard has other columns and custom templates can use other portlet managers.
   
4. The category under which the assignment is made - either "context", "user" (dashboard), "group" or "content type"
5. The key within that category where the assignment is made - this is a path for contextual portlets, a user id for dashboard portlets, a group id for group portlets and a content type id for content type portlets

We already have GenericSetup syntax for creating new portlet managers and registering new portlet types.

To create assignments using GenericSetup, the following syntax would be used:

<assignment
    type="plone.portlets.recent"
    manager="plone.leftcolumn"
    category="context"
    key="/Members"
    name="my.recent.portlet"
    insert-before="*"
    >

    <property name="limit">5</property>

</assignment>

The assignment directive has the following attributes:

type (required)

The name of the portlet assignment type. This would correspond to the "name" attribute of a <portlet /> directive in this or another portlets.xml file.

manager (required)

 The name of a portlet manager (column) to use. Portlet managers are registered in a portlets.xml file using the <portletManager /> directive.

category (required)

 The category to use - one of "context", "content_type", "group" or "user" (the latter is probably only useful for the dashboard portlet managers)

key (required)

The key under which the portlet is assigned. The meaning of this attribute depends on which category is being used. For the "context" category, the key is a path relative to the portal root, e.g. "/" to assign to the root or "/news" to assign to the news folder inside the root of the portal; for the "content_type" category, it is the portal_type id of the content type; for the "group" category, it is the id of a group; for the "user" category, it is a user id.

name (optional)

The name  of the assignment. If this is not given, a unique name will be chosen. If it's given and a portlet assignment with this name already exists under the given key, in the given category, in the given portlet manager, the existing portlet will be updated.

insert-before (optional)

This parameter can be used to control the relative order of the new portlet in the given key/category/manager mapping. If the value is "*" (an asterisk), the portlet will be placed first in the mapping. If the value is a name of another portlet in the same mapping, the new portlet will be placed before the specified one. If the attribute is omitted, the portlet will be placed last (portlets are processed and inserted in the order that they appear in the portlets.xml file). If a portlet name is specified, but does not exist, the new portlet will be inserted last.

Blacklisting

In the portlets management user interface, an administrator can blacklist (block) categories of portlets. To achieve the same with a GenericSetup, use the following syntax in the portlets.xml file:

    <blacklist
        manager="test.testcolumn"
        category="context"
        location="/news"
        status="block"
        />

This takes the following options:

manager (required)

The name of the portlet manager (column) to apply the blacklisting to.

category (required)

The category to blacklist. This should be one of "context" (parent portlets), "group" (group portlets) or "content_type" (content type portlets)

location (required)

A path relative to the portal root that determines the folder in which the block should be applied. If this cannot be found, no action will be taken.

status (required)

The status of the blacklisting for this category in this location. This can be one of "block" (do not show the given category), "show" (explicitly show the given category) or "acquire" (use whatever settings apply in the parent folder).

Special cases

The standard importer uses the portlet assignment's schema interface and the metadata contained in zope.schema fields to initialize the newly created assignment. For more complex cases, the portlet author can provide a custom adapter to the interface  plone.app.portlets.exportimport.interfaces.IPortletAssignmentExportImportHandler. It will often be useful to subclass the default implementation, which provides the necessary logic to deal with zope.schema interfaces.

Export and purge

When exporting and purging portlet assignments, only assignments in global categories (user, group or content type) will be included, in addition to those contextual portlets assigned to the portal root. Portlets assigned to subfolders are not exported, because it would be very difficult to do so in a performant way.

• PLIP submitted for Plone 3.1
• Importing with full support for the <assignment /> directive implemented and tested
• Blacklisting with the <blacklist /> directive implemented and tested
• Export and purge implemented