How and where are Portlet Assignments stored?¶
When you choose a portlet to be displayed somewhere, for example, using the interface that appears when you hit the Manage Portlets button, what you're doing is storing a persistent instance of the Portlet Assignment class into your site, together with all its associated configuration data.
Portlet Assignments are stored in what's called an Assignment Mapping. This is an ordered container with a dict-like interface. The keys are unique string names, and the values are instances of the assignment class.
Assignment mappings can be stored in two different kinds of locations depending on their type: site-wide or contextual.
Site-wide assigned portlets are shown in the whole site,
unless blocked. They're stored in Portlet Managers.
Portlet Managers define a column or other area that can be
filled with portlets, and are analogous to the viewlet
manager for viewlets. They are named persistent local
utilites providing the
You can look up a portlet manager like this:
manager = getUtility(IPortletManager, name=u"plone.leftcolumn")
By default, there are two standard portlet managers,
plone.rightcolumn, as well as four portlet managers for the four columns
on the dashboard, from
plone.dashboard4. You can create your own in
<portletmanager name="my.package.myportletmanager" type="my.package.interfaces.IMyPortletManagerType" />
The "type" is a marker interface that can be
used to install particular portlets only for particular
types of portlet managers, as explained above. Example:
Portlets in global categories (site-wide) are stored
directly inside the
utility, under a particular category - e.g.
"group" - a category-specific key - e.g. the
group id - and finally a unique portlet id. Putting this
together, we could access a particular portlet assignment
from plone.portlets.constants import GROUP_CATEGORY manager = getUtility(IPortletManager, name=u"plone.leftcolumn") recent_assignment = manager[GROUP_CATEGORY][u"Administrators"][u"recent"]
Here we look up the left column portlet manager and get the portlet assignment named recent assigned to the Administrators group.
Each of the lookups here has a dict interface, so you can
and so on. You can store assignments under any string as
category, but the default portlet retriever is only aware
of the three site-wide assignment categories defined as
constants in plone.portlet.constants,
CONTENT_TYPE_CATEGORY, which should be enough for most use-cases. More on
portlet retrievers later.
Location-specific portlet assignments are stored on
annotations on objects providing the
To get hold of the assignment in this case, we multi-adapt
the content object and the manager instance to the
interface, like so:
manager = getUtility(IPortletManager, name=u"plone.leftcolumn") assignment_mapping = getMultiAdapter((context, manager), IPortletAssignmentMapping) news_portlet = assignment_mapping[u"news"]
There are two functions in plone.app.portlets.utils to
make it easier to find the appropriate mapping for a
portlet, or to get a portlet assignment directly:
We can use GenericSetup to assign portlets to particular portlet managers upon the installation of a product. Read the Theme Reference Manual for info about how to do that. Read the Generic Setup tutorial for further info about what's GenericSetup and how it works.