Plone 3 has switched to use Zope 3 viewlet components instead of the old macro include approach.

This tutorial intends to teach you what viewlets and viewlet managers are, and how you can play with them in the context of adding a new theme to a Plone 3.0 site.

Even if it is or will be possible to go through all the steps that will be demonstrated in this tutorial from a Through The Web interface, the purpose here is to show how it is possible to achieve the given goals programmatically, from a Python product that lives on the filesystem.

So let's dig right into the code and have a look at the main_template template of Plone, which is the template that aggregates the page regions that are rendered around the content region of a Plone page (i.e. the header, the footer, and the two side columns):

In main_template.pt, which resides in $INSTANCE_HOME/Products/CMFPlone/skins/plone_templates/, we can see that the content of the <div /> region with id portal-top contains three lines of code. In versions of Plone previous to 3.0, it used to contain a whole list of macro calls for rendering the site wide actions, the quick search box, the logo, the global sections, the personal bar and breadcrumbs, etc..

For the example that I want to show, the old portion of the main_template.pt file used to look like this (in CMFPlone prior to 3.0):

<div id="portal-top" i18n:domain="plone">

<div id="portal-header">
  <p class="hiddenStructure">
    <a accesskey="2"
       tal:attributes="href string:${current_page_url}#documentContent"
       i18n:translate="label_skiptocontent">Skip to content.</a> |

    <a accesskey="6"
       tal:attributes="href string:${current_page_url}#portlet-navigation-tree"
       i18n:translate="label_skiptonavigation">Skip to navigation</a>
  </p>

     <div metal:use-macro="here/global_siteactions/macros/site_actions">
       Site-wide actions (Contact, Sitemap, Help, Style Switcher etc)
     </div>

     <div metal:use-macro="here/global_searchbox/macros/quick_search">
       The quicksearch box, normally placed at the top right
     </div>

     <a metal:use-macro="here/global_logo/macros/portal_logo">
       The portal logo, linked to the portal root
     </a>

     <div metal:use-macro="here/global_skinswitcher/macros/skin_tabs">
       The skin switcher tabs. Based on which role you have, you
       get a selection of skins that you can switch between.
     </div>

     <div metal:use-macro="here/global_sections/macros/portal_tabs">
       The global sections tabs. (Welcome, News etc)
     </div>
  </div>

  <div metal:use-macro="here/global_personalbar/macros/personal_bar">
     The personal bar. (log in, logout etc...)
   </div>

   <div metal:use-macro="here/global_pathbar/macros/path_bar">
     The breadcrumb navigation ("you are here")
   </div>
</div>

Where it now looks like this:

<div id="portal-top" i18n:domain="plone">
    <div tal:replace="structure provider:plone.portaltop" />
</div>

The provider TAL expression is a Zope 3 expression which looks up a content provider from a page template.

In the Zope 3 world (since Zope 3.2), a content provider is a component that generates a portion of an HTML page.

Like Zope 3 views, content providers are multi adapters that adapt the context and the request. Content providers additionally adapt the view they are looked up from.

Viewlets are content providers, they are small components of a page that render a small piece of HTML code.

In Plone templates, viewlets are not looked up directly though. In order to be able to organize viewlets with a maximum of flexibility, they are aggregated in viewlet managers.

A viewlet manager is also a Zope 3 content provider, which renders a set of viewlets that are registered for it.

In the further chapters of this tutorial, I will do my best to teach you more about what viewlets and viewlet managers are, what you can do with them and what are the advantages of this approach. If you still feel that you need more input on the subject, you should read the dedicated section of Philipp's book (Web Component Development with Zope 3 - 2d. edition, chapter 10.4).

I also found this .. _very good blog entry: http://griddlenoise.blogspot.com/2005/12/glance-at-zope-32-content-providers.html where Jeff Shell gives a more extensive description of content providers and viewlets in the context of developing a pure Zope 3 application.