Collection Portlets

In Plone 3+ you have the ability to display the results of a Collection in a configurable portlet. This is a very useful way of adding dynamic content to your website, and to highlight certain content.

Before we even begin to create the Collection Portlet, we must have first created a Collection. For this How-to we have already created a mocked up Collection. If you need help creating one, read the Collection Tutorial in the Plone 3 Manual.

Create the Collection

For an example site, we have several pages and events that center around our campaign on Climate Actions. We want a way to highlight the information we have and make it very accessible to users. An easy way to do this is to use a Collection Portlet.

First off, we created a Collection that searches for the word Climate on all objects in our site and returns the results. We are doing this by using the Search Text Criterion.

Create a Collection Portlet

Now that we have the Collection the next thing we must do before we create the Portlet is to decide where we want the Portlet to show. Since we are trying to showcase this information we are going to display it on the homepage so that this portlet will propagate down to all subsections of the site.

Now that we know where we want the portlet to appear, we simply navigate to the homepage and click the Manage Portlets link.

From the Manage Portlet Screen, we must choose what side we want our Portlet to appear on. For our example we are going to place it on the left side of the page. To do this we will click the drop down box labeled Add Portlet and select Collection Portlet.

By selecting the Collection Portlet it will take us to the Portlet Configuration Screen. Here we will have the chance to specify the details of our Portlet.

Our first order of business is to enter a Portlet Header. This header will display at the top of the portlet and allows us to give our Portlet a name of our choosing. For our example we will name ours Climate Action.

The next step is the most crucial.

Tie the Portlet to the Target Collection

For our Collection Portlet we must tell it which Collection to look at for information. We do this by selecting a Target Collection. In most cases the Collection you want will be display already under the Search Results section. If this is the case simply select the radio button next to its name.

If your Collection does not show up in the results section, enter its name in the search box and click search.

Finally, we have the ability to set a few properties to determine how our Portlet will display the results.

Configuration Options

The Limit field determines how many of the results will display in our Portlet. Left blank, the Collection Portlet will display all the results of the Collection. Be careful about showing too many results because your portlet will become too long and possibly push other portlets far down the page. The purpose of a Collection portlet is to show a few results, usually things like the most recent News, Events, Blog posts, etc. . .

The order that these limited results display in are determined by the Sort Order settings on the target Collection.

Checking the box next to Select Random Items will order the Portlet to select results randomly from the Collection instead of following the Collections Sort Order.

If you have more items in your Collection that you are showing in your Portlet, it is a good idea to include the "Show More..." link. This will add a link at the bottom of your Portlet that links to the target Collection.

The final option is Show Dates. By selecting this all of the results will show the Effective Date of the object below its Title.

The last but very important step is to click Save. When this is all done we can go to our homepage and view our new Portlet.