What is a Portlet?
Portlets are areas you create to add and display content. Portlets can be added to the left and right of the center body area and can contain myriad content ranging from news, events, calendars, RSS feeds, collections, plain text, and more. Also, you can set properties and policies for showing the portlets.
Think of a portlet like a bucket!
Why Use a Portlet?
- You have content you want to have special focus, like news.
- You need to specify the configuration data for an item. - i.e. number of entries to show.
- You want to give the content editors a choice about when and where to display content.
- You'd like to show it only to some groups or users.
When managing portlets sitewide, keep in mind that they are inherited:
- Portlets set up at the Site Root propagate down through the entire site.
- Portlets set up at the Folder level propagate down through that entire Folder.
- Portlets set up on a single noncontainer Content Item do not propagate.
Blocking Parent Portlets
- If you want a different set of portlets or order of portlets for a particular section, you must use the Block/unblock portlets controls, to "block" the parent portlets. When you block Portlets, you must explicitly add all the Portlets that you wish to see on the child page.
Here is an example of Plone's portlet hierarchy:
You can see that the Navigation portlet propagates down through the entire site. Recent Items is visible through the first and second level, but has been blocked in the third. Documentation has added a Collection portlet, and Tutorials and Videos have added Search.
To start creating and editing portlets, you must click on the Manage Portlets link. Usually, this is found at the bottom of the left and/or right columns. Under Manage Portlets, you can create new portlets, remove portlets, rename, and rearrange portlets.
Once you click the link, you'll see:
Plone's Portlet Control Panel
Adding a Portlet
Click on the Add Portlet drop down box and choose the type of portlet you would like to add. We discuss the different options available in a moment.
Understand that you have the ability to work with portlets on both the right and left side of the page. This is because there are left and right columns. Portlets will only appear on the side(s) that you add them.
Also, there is no limit to how many times you can use a certain type of portlet or an individual portlet, or a limit to how many total portlets can be on a page.
Portlet Types shipped with Plone
- RSS Feeds
- Recent Items
- Review List
- Static Text
This simple, non-customizable portlet displays a small calendar of any events on the site.
A Classic Portlet is...
- In the manner of older versions of Plone
- Created by your site administrator using a page template in the Zope Management Interface (ZMI)
- Handy when you want a simple custom portlet that can be used anywhere on the site
- For example, the Need Help Now? portlet at weblion.psu.edu/documentation
A Collection Portlet displays a Plone collection. Collection portlets can be used for jobs such as:
- Displaying topic-related news or events in different sections of your site
- Creating custom navigation
- Creating those below-the-footer displays of links, features, etc. Like at agsci.psu.edu
Portlet Header and Target Collection
Give your Collection Portlet the title of your choice in the portlet header field. Then search for and select the Target collection—that's the collection whose results you want displayed in your portlet.
Limit, Randomization, Link, and Dates
In the Limit field, you can specify how many items you want displayed in the collection portlet—if you do decide to limit the display, you may want to check the box next to Show more... link so that users can get to the rest of the items in the collection.
You can randomize the display by checking the box next to Select random items.
If you want the publication dates of items to be visible, check the box next to Show dates.
Collection Portlet Display
When you save your changes and click Return, you should see your collection portlet display. If you do not see your portlet, check your portlet settings, and check the original collection to make sure it is displaying items.
An Events Portlet displays upcoming events. You can control how many are displayed as well as which workflow state to show. For instance, if you choose Published, only published Events will show up in the portlet. If you want only certain events to show up, use a Collection Portlet instead.
Selecting this adds a non-configurable Login Portlet. Don't be confused if you do not see the login portlet once you add it. Only anonymous users can view the portlet.
The Navigation Portlet provides a structured navigation tree of the site or folder.
You can title the navigation portlet to reflect its location, or simply call it Navigation.
Next, indicate the Root Node, or folder on the site that you want the portlet to navigate. If you want it to map out the entire site, leave the root node field blank.
If you select Include Top node, your navigation portlet will list the Title of the site or folder at the top of the navigation tree.
Current Folder, Start Level, Depth
You can indicate whether you want your navigation portlet to list only the items in the current folder.
When setting up site-wide navigation, you can indicate the Start level, that is, the number of folder levels below the site where you want the navigation to begin displaying. If you indicate 0 as the Start level, the navigation will appear at the top of the site and everywhere below. 1 means it will not appear at the top of the site. And so on...
You can also control when the navigation tree should stop. A navigation tree depth of 0 means that there is no limit. A navigation tree depth of 1 indicates only the root folder, and so on.
You can edit your navigation portlet as many times as you need to until you get the navigation just right.
Navigation Portlet Display
The News Portlet is much like the events portlet. You can chose the Number of items to display and the Workflow state. If you want to display only specific News Items, use a Collection Portlet.
With RSS Portlets, it's simple to collect RSS feeds and display them on your site.This is a great way to post material from blogs, news portals, social media, and the like.
Choose a Title for the feed, the Number of items to display, provide the URL of RSS feed, and in the Feed reload timeout field, specify how frequently you want the feed to refresh on your site.
RSS Portlet Display
You get a More... link for free, which leads to the full content of the item.
Recent Items Portlet
The Recent Items Portlet displays a list of items on your site with recent modification dates.
You can specify how many items to display in the Recent Items Portlet. An All recent changes... link leads to the full list.
Search Portlet Display
The Search Portlet will search titles, descriptions, and body text of your site's content.
Static Text Portlet
The Static Text Portlet allows you to add content just as you would on a page. Along with a Title (Portlet header) and Body Text, you get an optional Border, Footer, and Details Link.
Static Text Portlet Display
Use Static Text Portlets for content that you cannot provide using the other portlet types. Static Text Portlets also are best for content that does not change frequently and content that doesn't get reused in various places on the site.
Editing an Existing Portlet
To Edit, Reorder, Hide, or Show portlets, be sure you are at the site level where the portlets actually were added.
To edit the properties of an existing portlet, click on the name of the portlet. Each type of portlet will have different configuration options available to it.
To rearrange your portlets, simply click the blue up or down arrow. This will affect the order your portlets are displayed on the page.
To remove a portlet, click the "X" next to its name.
In Plone 4, you can show/hide portlets using the associated show/hide links present.
Showing a Portlet
When you're ready to use the portlet again, click Show.
Beware the Default View
When you set about creating Portlets that you want to propagate, be careful to that you are creating the Portlet at the Site Root or Folder and not at the Default View:
- my-site.edu/front-page is not the Site Root. my-site.edu/ is.
- my-site/cheeses/cheese-home is not the Folder Level. my-site/cheeses/ is.
Check the URL
When setting up Portlets that you want to propagate through an entire folder, look at the URL after following the Manage Portlets link. If the default view is visible in the URL, remove it before adding the portlets. In the example below, tasty-suet-cakes is the Default View for the Folder /feeding/. Simply shave /tasty-suet-cakes off the URL, and you're good to go.
- You're at the Default View: http://chickadees.org/feeding/tasty-suet-cakes/@@manage-portlets
- You're at the Folder: http://chickadees.org/feeding/@@manage-portlets
Blocking and Unblocking Portlets
Your content inherits Portlet Settings from the Parent container—the Folder that the content lives in, not folders farther upstream.
You can Block these portlet settings:
In Plone 4, users can now see what's being blocked and what's being inherited.
Blocked Items are Grayed Out
A blocked portlet will be grayed out on on the portlet management screen:
Which Portlets to Block
When blocking and unblocking portlets, understand what those three different pulldown menus are about:
- Affects all portlets, including Group and Content Type Portlets.
- But, settings for Group and Content Type Portlets can override for these two portlet types.
- Created by your Site Manager for Groups of Users.
- Block and Do not block override parent settings.
Content Type Portlets
- Assigned in the Plone Control Panel to specific Content Types by your Site Manager .
- Block and Do not block override parent settings.
ContentWellPortlets is a very handy add-on Plone product that allows you to place portlets above the main content, below the main content, and in the footer area.
You can add up to six portlets in these areas.