(For more resources on Plone, see here.)

Introduction

One of the major changes from Plone 2.5 to Plone 3.0 was the complete refactoring of its portlets engine. In Plone 2.5, left and right side portlets were managed from Zope Management Interface (ZMI) by setting two special properties: left_slots and right_slots.

This was not so hard but was cumbersome. Any TALES path expression—ZPT macros typically—could be manually inserted in the above two properties and would be displayed as a bit of HTML to the final user.

The major drawback for site managers with the old-style approach was not just the uncomfortable way of setting which portlets to display, but the lack of any configuration options for them. For example, if we wanted to present the latest published news items, we wouldn’t have any means of telling how many of them to show, unless the portlet itself were intelligent enough to get that value from some other contextual property. But again, we were still stuck in the ZMI.

Fortunately, this has changed enormously in Plone 3.x:

• Portlets can now be configured and their settings are mantained in ZODB.
• Portlets are now managed via a user-friendly, Plone-like interface. Just click on the Manage portlets link below each of the portlets columns (see the following screenshot).

In the above screen, if we click on the News portlet link, we are presented with a special configuration form to choose the Number of items to display and the Workflow state(s) we want to consider when showing news items.

If you have read previous chapters, you might be correctly guessing that Zope 3 components (zope.formlib mainly) are behind the portlets configuration forms.

In the next sections, we’ll look again at the customer’s requirements:

• Advertisement banners will be located in several areas of every page
• Advertisement banners may vary according to the section of the website

Creating a portlet package

Once again, paster comes to the rescue. As in Creating a product package structure and Creating an Archetypes product with paster, we will use the paster command here to create all the necessary boilerplate (and even more) to get a fully working portlet.

Getting ready

As we are still at the development stage, we should run the following commands in our buildout’s src folder:

cd ./src

How to do it…

1. Run the paster command: We are going to create a new egg called pox.portlet.banner. The pox prefix is from PloneOpenX (the website we are working on) and it will be the namespace of our product.

   Portlets eggs usually have a nested portlet namespace as in plone.portlet.collection or plone.portlet.static. We have chosen the pox main namespace as in the previous eggs we have created, and the banner suffix corresponds to the portlet name. For more information about eggs and packages names read http://www.martinaspeli.net/articles/the-naming-ofthings-package-names-and-namespaces.
   If you want to add portlets to an existing package instead of creating a new one, the steps covered in this chapter should tell you all you need to know (the use of paster addcontent portlet local command will be of great help).

   In your src folder, run the following command:

   paster create -t plone3_portlet

   This paster command creates a product using the plone3_portlet template. When run, it will output some informative text, and then a short wizard will be started to select options for the package:

   Option	Value
   Enter project name	pox.portlet.banner
   Expert Mode?	easy
   Version	1.0
   Description	Portlet to show banners
   Portlet Name	Banner portlet
   Portlet Type	BannerPortlet

   After selecting the last option, you’ll get an output like this (a little longer actually):

   Creating directory ./pox.portlet.banner
    ...
    Recursing into +namespace_package+
     Recursing into +namespace_package2+
      Recursing into +package+
       Recursing into profiles
        Creating ./pox.portlet.banner/pox/portlet/banner/profiles/
        Recursing into default
         Creating ./pox.portlet.banner/pox/portlet/banner/profiles/default/
         Copying metadata.xml_tmpl to ./pox.portlet.banner/pox/portlet/banner/profiles/default/metadata.xml
         Copying portlets.xml_tmpl to ./pox.portlet.banner/pox/portlet/banner/profiles/default/portlets.xml

   This tells us that even the GenericSetup extension profile has also been created by paster. This means that we can install the new Banner portlet product (as entered in the portlet_name option above).

2. Install the product: To tell our Zope instance about the new product, we must update the buildout.cfg file as follows:

   [buildout]
   ...
   eggs =
   ...
      pox.portlet.banner
   ...
   develop =
    src/pox.portlet.banner

   We can automatically install the product during buildout. Add a pox.portlet.banner line inside the products parameter of the [plonesite] part:

   [plonesite]
   recipe = collective.recipe.plonesite
   ...
   products =
   ...
    pox.portlet.banner

3. Build your instance and, if you want to, launch it to see the new empty Banner portlet:

   ./bin/buildout
   ./bin/instance fg

4. Check the new portlet: After implementing the changes above, if you click on the Manage portlets link in the site’s home page (or anywhere in the Plone site), you will see a new Banner portlet option in the drop-down menu. A new box in the portlet column will then be shown.

The Header/Body text/Footer box shown above matches the template definition in the bannerportlet.pt file the way paster created it.