(For more resources on Plone, see here.)

Plone makes it easy to create new types of portlets that include custom programming logic for your site. There are several ways to create custom portlets, but the simplest way to get started is to use the add-on product collective.portlet.tal which provides a new type of portlet, called a TAL Portlet. This portlet allows you to write simple bits of code using Zope’s TAL templating language.

Let’s walk through a quick example of building a custom TAL portlet, which will show a randomly-selected news item from your site.

Installing collective.portlet.tal

Before you can add a TAL portlet, you must download the product from Plone.org/products and install the add-on product collective.portlet.tal on your site. The best way to do this is to modify your buildout.cfg file.

Add collective.portlet.tal to the eggs and zcml sections of your buildout. Here’s a code snippet with the changes made to it:

[buildout]
   ...
   eggs =
      ...
      collective.portlet.tal
   [instance]
   recipe = plone.recipe.zope2instance
   ...
   zcml =
      collective.portlet.tal

Once you’ve made these changes, re-run buildout by issuing the following command:

$ ./bin/buildout

Once you’ve added the product to your buildout, visit Site Setup and choose Add/Remove Products, to install collective.portlet.tal in your site.

Finally, add a few news items to your site so that we have something for our new TAL portlet to find.

Adding a simple TAL portlet

With the collective.portlet.tal product in place, the following can happen:

1. Navigate to your Plone site.
2. Choose Manage Portlets in the right column.
3. From the Add portlet… drop-down list, choose TAL Portlet.

   

4. You’ll see an empty text box in which you can enter a title. We will specify Featured News Item as our title. We’ll soon see the code needed to feature a random one of our site’s published news items.
5. In addition to the Title text box, you’ll also see an HTML text area titled TAL code. Conveniently, this comes pre-populated with some boilerplate HTML and TAL code. Skim this, so that you get a feel for how this looks and what the common HTML structure is like, for a portlet in Plone.

As an immediate experiment, we will find the following snippet of code:

<dd class="portletItem odd">
   Body text
</dd>

We will modify this, slightly, to:

<dd class="portletItem odd">
   Is this thing on?
</dd>

Click on Save and navigate through the site, and you should see your first TAL portlet in action. Of course, there’s nothing in this example that couldn’t be accomplished with a static text portlet. So let’s navigate back to the Featured News Item portlet and make it a bit more interesting and dynamic.

Update the code in your TAL Portlet to include the following:

<dl class="portlet portlet${portlet_type_name}"
      tal_define="newsitems python:context.portal_catalog
               (portal_type='News Item', review_state='published');"
      tal_condition="newsitems">
      <dt class="portletHeader">
         <span class="portletTopLeft"></span>
         <span>
            Featured News Item
         </span>
         <span class="portletTopRight"></span>
      </dt>
      <dd class="portletItem odd"
         tal_define="random_newsitem python:random.choice(newsitems)">
         <a tal_content="random_newsitem/Title"
            href="[replaced by random news item link]"
            title="[replaced by random news item title]"
            tal_attributes="href random_newsitem/getURL;
               title random_newsitem/Title">[replaced by random news
                                                   item title]</a>
      </dd>
      <dd class="portletFooter">
         <span class="portletBotomLeft"></span>
         <span>
            <a href="http://example.com/news">More news...</a>
         </span>
         <span class="portletBottomRight"></span>
      </dd>
   </dl>

Now, let’s go into more detail on a few of these sections, so that you understand what’s happening. If at any point you need more context, try reading the excellent ZPT reference manual at http://plone.org/documentation/tutorial/zpt.