Formatting portlets

by Reinout van Rees — last modified May 17, 2009 09:51 AM

How to format your portlets with the right HTML tags and the right CSS classes.

The formatting of portlets has changed somewhat overtime. In plone 2.0 and earlier it used <h5> tags with a <div> around it, for instance. It's important to use well-formed HTML when creating new portlets.

HTML tags

Plone 2.1 and up use a much more structural approach: a definition list, like this:

  <dl> <!-- definition list -->
    <dt>Definition term</dt>
    <dd>Definition description 1</dd>
    <dd>Definition description 2</dd>
    <dd>Definition description 3</dd>
  </dl>

This makes it more understandable for both Google and for visually impaired people's screenreaders. The <dt> serves as the portlet's header ("Recent news"), the following <dd> elements are, in this case, the recent news items.

Main CSS classes

Regarding formatting, the previous mess with lots of classes has been cleaned up. There are four main classes:

portlet: The <dl> should be tagged with the portlet class.
portletHeader: The <dt> gets marked as the header.
portletItem: All the regular <dd> items get marked as portlet items.
portletFooter: This one is optional, but you can use it on the last <dd> if you want to turn it into a "more news..."-like box as happens on plone.org's news portlet.

Additional CSS classes

The main CSS classes are absolutely necessary to get your portlet displayed as a portlet. To improve the display, you can make use of additional classes. If possible, you should add them so that your portlet works great with everybody's styles.

The additional class is added to the main class, space separated. So something like <dd class="portletItem odd">.

odd/even: If you have a list of items, mark them alternatingly with odd and even so that they can be formatted in, for instance, a different background color.
lastItem: Mark the last item in your portlet with lastItem so that everybody can add some margin or a border below the last item. This is not needed if you already have a portletFooter.
If you have only one portletItem, mark that with lastItem, too. (This replaces the deprecated portletItemSingle class).

Final examples

You can also format the code by adding some extra CSS tags. So you'll get the code example and you can immediately see that it works. I added an extra style="width: 200px;" to the formatted examples to keep their width in check, though.

Just a list of items:

  <dl class="portlet">
    <dt class="portletHeader">Recent items</dt>
    <dd class="portletItem odd">Annie</dd>
    <dd class="portletItem even">Rianne</dd>
    <dd class="portletItem odd lastItem">Floris</dd>
  </dl>

  <dl class="portlet" style="width: 200px;">
   <dt class="portletHeader">Recent items</dt>
   <dd class="portletItem odd">Annie</dd>
   <dd class="portletItem even">Rianne</dd>
   <dd class="portletItem odd lastItem">Floris</dd>
  </dl>

The same, with a portlet footer:

  <dl class="portlet">
    <dt class="portletHeader">Recent items</dt>
    <dd class="portletItem odd">Annie</dd>
    <dd class="portletItem even">Rianne</dd>
    <dd class="portletItem odd">Floris</dd>
    <dd class="portletFooter">Add more items...</dd>
    <!-- Use &hellip; instead of those ... above. -->
  </dl>

Recent items: Annie; Rianne; Floris; Add more items...

Just one single item:

  <dl class="portlet">
    <dt class="portletHeader">Random logo</dt>
    <dd class="portletItem lastItem">
      <div><img src="logo.jpg" alt="random logo"/></div>
      <div>Caption of the logo</div>
    </dd>
  </dl>

Random logo: Caption of the logo