(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:

1. Portlets can only be added to portlet managers. They can’t be added into the body content of your pages.
2. 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.

Add-on 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.

Adding portlets

There are three ways to add portlets to your site:

1. Add portlets to specific locations on your site.
2. Add portlets that are associated with specific content types—for example, a portlet that shows on all News Items.
3. 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.