(For more resources on Plone, see here.)
What's a portlet, anyway?
A portlet is a chunk of information that can be shown outside of the main content area of a page. In the following screenshot of Plone's default home page, the Log in box and the calendar are portlets.
Plone's default theme has two portlet managers that control the assignment of portlets on the right and left sidebars of the page. You can place portlets into these slots on the page. It's also possible to add portlet manager slots to a custom theme so that you can display portlets in other areas of the page, but that's beyond the scope of this book. For more information, refer to: http://plone.org/documentation/how-to/adding-portlet-managers.
There are two things that we need to know about portlets before we dive into adding them:
- Portlets can only be added to portlet managers. They can't be added into the body content of your pages.
- Portlets can be assigned to folders, content types, or user groups, and will cascade down through the site hierarchy unless you explicitly block inheritance.
Plone's built-in portlets
Plone ships with a generous assortment of basic portlets. Here's a quick list of Plone's default portlet offerings:
- Login: Shows Plone's login box to anonymous users; is hidden if a user is already logged in
- Collection portlet: Shows the results of a Collection
- Review list: Visible only to the users with the Reviewer role; this portlet shows a list of items that users have submitted for review before publishing
- RSS feed: Shows a list of items in an RSS feed
- Classic portlet: A wrapper for Zope 2 style portlets, which may have been developed prior to the advent of Plone 3 and its new portlet system
- Calendar portlet: Shows a simple calendar that highlights the dates of upcoming events for your site
- Search: Shows Plone's search box useful if you have chosen to disable the standard search box, and want to show it in a sidebar instead
- Recent items: Shows the most recently-published content items on your site
- Static text portlet: Shows a chunk of static, editable HTML content; this is one of Plone's most versatile and useful portlets
- Navigation: Shows the navigation tree
- Events: Shows upcoming published events on your site
You're likely only to use Classic portlets if you are using an add-on product that hasn't fully embraced the new style of building portlets, or if you are building your own custom portlets.
Many add-on products for Plone will supply one or more relevant portlets when the product is installed.
There are also additional standalone portlets available as separate add-on products. Among the most useful standalone add-on portlets are:
- TAL Portlet: A portlet that allows you to write your own simple portlets in Plone's templating language, TAL. Optionally, you could just write a Classic portlet.
- Feedmixer: A portlet that allows you to aggregate multiple RSS feeds into a single portlet.
These products can be found in the Products section of Plone.org.
There are three ways to add portlets to your site:
- Add portlets to specific locations on your site.
- Add portlets that are associated with specific content types—for example, a portlet that shows on all News Items.
- Add portlets that are shown only to specific groups of users in your site.
Adding portlets to specific sections of your site
We'll start with adding portlets to a specific section of your site, as this is the most common and the simplest thing to do.
Log in to your site (via the Log in portlet) and look at the bottom of the rightmost sidebar for the Manage portlets link.
This will take you to the Manage portlets screen.
Managing Portlets Peacefully
Because you were on the front page of your site, when you clicked on the Manage portlets link, you are now managing the portlets for your entire site. If you only want to manage portlets for a single section of your site, first navigate to that section, and then click on the Manage portlets link. The header of the Manage Portlets screen will tell you which section of the site you are in.
The Manage Portlets screen tells you that certain portlets are already assigned to all of the pages of your site. In the example above, the left sidebar portlet manager has the Navigation portlet and the Log in portlet. The right sidebar portlet manager has the Review List, News, Events and Calendar portlets.
Moving and Removing Portlets
You can move existing portlets around within a portlet manager by clicking on the up and down arrows within the portlet. You can remove a portlet from the portlet manager by clicking on the red X.
To add a portlet to your site, select the Add portlet... drop-down menu at the top of either the right or left sidebar, and choose a portlet type to be added. For practice, let's try adding a static content portlet to the right sidebar.
This screen contains the familiar Kupu-powered rich text editing widget, along with:
- A Portlet header (title) field.
- A Portlet footer field.
- A optional hyperlink field, which will be clickable from the portlet header and footer.
- An Omit portlet border checkbox. If selected, this hides the portlet header, footer, and border. This is very useful if you only want to place an image or some fl oating text in your sidebar.
Enter some text into your new portlet, click on the Save button at the bottom of the screen, and then click on the Home tab to return to your site's homepage. You should now see your new static text portlet. If you click around the site, you'll continue to see the portlet on all of the pages of your site.
(For more resources on Plone, see here.)
Adding portlets to specific content types
You can also assign portlets to specific content types on your web site. These portlets will be shown any time you are viewing that type of object.
Content type portlets are assigned via the Types control panel. You can access this by navigating to Site Setup and then choosing the Types option. Choose a content type (we'll use News Item in this example) from the drop-down list to see the configuration options for the content type, as shown in the following screenshot:
Then, click on Manage portlets assigned to this content type. You'll be taken to the following Manage portlets screen:
You can use the drop-down lists in the right and left sidebars to assign portlets to either column, as you've done previously.
A good test is to create a Static text portlet and assign it to News Items, and view a News Item to see if the portlet does indeed display.
Adding portlets to specific groups of users
The third and final way of assigning portlets in Plone is to assign them to specific groups of users. For example, you may wish to show some information only to site administrators.
Group-specific portlets are managed via the Users and Groups control panel. You can access this by navigating to Site Setup and then choosing the Users and Groups option.
Click on the Groups tab, then on the name of a group (we'll use Administrators in this example), and then on the Group Portlets tab, as shown in the following screenshot:
How does Plone know in what order to show different kinds of portlets?
If you are viewing a page, then Plone will display sets of portlets in the following order:
Hiding portlets for specific content objects
Thanks to the magic of Zope acquisition, portlets that you assign at the top levels of your site will cascade down the site hierarchy and will appear on all of the objects at lower levels. In other words, if you assign a portlet to a folder, it will appear for all of the objects and subfolders inside that folder—unless you explicitly hide them by using Plone's portlet blocking system.
The key idea of portlet blocking is that, at any given location in your site, you can hide the portlets that would otherwise be inherited from parent locations, user groups, or content types. This provides you with great flexibility in how and where portlets should appear on your site.
Portlets are blocked from the Manage portlets screen for an object. We'll now walk through a simple scenario in which we block portlets from being inherited by a specific News Item.
If you've worked through the preceding examples for adding portlets, you will have assigned portlets to the root level of your site, to News Items, and to the Administrators group. Now let's try using portlet blocking to hide all of these portlets for one specific News Item.
Before you start, make sure that you:
- Have at least one News Item on your site
- Have assigned portlets to the root of your site, to the News Item content type, and to the Administrators group (we'll use simple static text portlets in this example)
- Are logged in as a user who is a member of the Administrators group
As we start, the view of your news item should look like this:
Click on the Manage portlets link in either column. You'll be taken to the familiar Manage portlets screen:
Note the Block/unblock portlets drop-down fields. These allow us to choose whether or not we want to block portlets from being acquired by this object. By default, an object will:
- Show the portlets assigned to its parent objects
- Inherit its parent object's settings for content type portlets
- Inherit its parent object's settings for group portlets
To block all of the portlets in the right-hand sidebar from being acquired by this particular News Item, set the Parent portlets, Group portlets, and Content type portlets drop-downs in the right-hand sidebar to Block.
Click on Save settings, and then click on Return to return to the view of your News Item, which should now look like this:
As you can see, you've blocked all of the right sidebar portlets that your News Item was acquiring by virtue of being underneath the root of your site, by being News Item, and by you being a member of the Administrators group.
Unblocking portlets that have been blocked
If you've blocked the content type or group portlets in a folder, you can unblock those portlets for individual objects inside that folder by selecting Do not block from the Group portlets and/or Content type portlets drop-down menus.
Can I unblock location-based portlets?
You can't unblock location based portlets; but you can re-add portlets to individual objects.
The combination of location, user group, and content type portlets, plus portlet blocking and unblocking is very powerful, but can't cover very complex rules for portlet inheritance. You will have to do some custom portlet programming in order to implement more complex schemes.
In this article, we have learned:
- How to assign portlets to objects, content types, and groups of users
- How to re-order and remove portlets
- How to block portlets from being inherited
- Find and Install Add-Ons that Expand Plone Functionality
- Structure the Content on your Plone Site
- Safely Manage Different Versions of Content with plone