You are here: Home / Blog / posts / Pixelworkers of CAES DO / Collector's Item

Collector's Item

by pgang — published Nov 16, 2010 01:55 PM, last modified Jan 28, 2014 02:54 PM
Collection portlets are a handy tool — they let you display a certain number of items from a collection in a portlet. We use them for things like specific news item feeds, Faculty Staff Directory profiles, etc. Here's a bit on how to customize them!

First off! If you're not sure what a Collection is, maybe you should read up over here?

Warning! Not to discourage you, reader, but you should know up front that editing the template for the collection portlet affects all of your collection portlets, not surprisingly! What this means is, if on your website you want one that shows event dates only for collections that show events, and thumbnails only on collections that show profiles — the template is the same. Luckily you can CSS your way around most of these issues. I think you can even clone the portlet to make other custom portlets but that's for another day. Anyway, read on!

The Template

So this magic template lives in the ZMI in portal_view_customizations. Go on over and find it at the bottom area, For you lazy folks, here's what the original looks like a la Plone 3.3.5:

<dl class="portlet portletCollection"
    tal:define="collection_url view/collection_url;
                plone_view context/@@plone;
                toLocalizedTime nocall:plone_view/toLocalizedTime;
                getIcon nocall:plone_view/getIcon;">

    <dt class="portletHeader">
        <span class="portletTopLeft"></span>
        <a tal:attributes="href collection_url" tal:omit-tag="not:view/data/show_more">
            <span tal:content="view/data/header" />
        <span class="portletTopRight"></span>
    <tal:events tal:repeat="obj view/results">
    <dd class="portletItem"
        tal:define="oddrow repeat/obj/odd;
                    item_icon python:getIcon(obj);"
        tal:attributes="class python:oddrow and 'portletItem even' or 'portletItem odd'">
        <a href="#"
           tal:attributes="href obj/getURL;
                           title obj/Description">
            <img tal:replace="structure item_icon/html_tag" />
            <span tal:replace="obj/pretty_title_or_id">
            <span class="portletItemDetails"
    <dd class="portletFooter" tal:condition="view/data/show_more">
        <span class="portletBottomLeft"></span>
        <a tal:attributes="href collection_url" i18n:translate="more_url">
        <span class="portletBottomRight"></span>


The meat of it (between <tal:events>) is just taking each item from whichever Collection you associate the portlet with, and spitting out its title with a link, associated image if there is one, and the details like its effective date. Here's one way we've used the Collection Portlet:

News items

Why yes, Plone does have its own News Portlet to display News Items. But what if you only want to display News Items tagged with certain categories? That's where Collections come in! 

For our purposes, we have two types of News Items on the front of our College website — Web News and Spotlight articles. We set this up before we knew of the wonder that is ContentWellPortlets, so it's a little hacky but the principle is the same. There are two Collections set up to look for News Items, one that looks for those with the first tag, and one with the second tag. Then we have one Collection portlet in the left column set to show three items, and one Collection portlet in the right column showing only one item. You set which items show up (i.e. the three most recent) in the Collection criteria, but you can have the portlet choose random items as well.

The main customization we did with these was to have the Description field show up as a little blurb, and to make the "More..." link in the footer point to the correct archive. 

For adding the Description or any additional field in, it's just a matter of finding the correct query string and kind of modeling the syntax after an existing line (coming from me, a non-programmer). Here's the code I put in:

<tal:events tal:repeat="obj view/results">
<!-- all the normal stuff, and then... -->
   <p class="documentDescription" tal:content="obj/Description">Blah</p>

The key piece there is the tal statement that is swapping the content of the p tag with the object's description. 

For the "More..." link, we did a hacky kind of thing where there's a <span class="webnews">More...</span> and a <span class="spotlight">More...</span>, and then a .portal-column-one .portletFooter .spotlight, .portal-column-two .portletFooter .webnews {display: none;} to hide them in the other portlet.

That's the general idea though! Let me know if you have questions or are looking to do something more specific. Hooray for Collection Portlets!