The problem

I wanted the home page of my web site to show my blog entries and also be a little more dynamic by displaying other related content.

The default index_html page for my blog software, Quills, does display the current entries, but from what I read online there was no great solution to get its default page to show at the root.

Plan B was to replace my generic index_html page with one which would query the Quills weblog object for all of its entries and then display them one at a time. I wanted to use one of Plone's built-in user-addable types for the script but as far as I can tell they are only used to display formatted text and won't execute any code. I finally used the Zope Management Interface (ZMI) to add a single Zope Page Template (ZPT) called index_html.

Understanding how Plone draws a page

I read several chapters in the book The Definitive Guide to Plone to figure out how to proceed, but the one which gave the most pertinent information was *Chapter 7 - Customizing the Main Template*.

In short, Plone has a special Zope Page Template (ZPT) (`/your_plone_site_folder/portal_skins/plone_templates/main_template`) which contains the HTML and special markup used to render the basic structure of each page in the site. Among other things, the markup defines regions within the page called `define-slots`. These slots are *filled in* by an object as it is being rendered for view in the browser. Using a master template like this assures that the site has a consistent page layout.

Within this master template there are slots defined for different sections of the HTML like `head_slot`, `css_slot`, `column_one_slot`, and `content`. Some examples of these slot definitions follow. Notice that they can be within different types of tags.::

<metal:block define-slot="content">
  This content will be replaced.
</metal:block>

<td metal:define-slot="main">...</td>


When you are rendering your ZPT, you define the areas which will 'fill' these slots and place the pertinent content within them. These areas are appropriately called fill-slots. Here are some examples:

<metal:block fill-slot="head_slot">
  your stuff here
</metal:block>

<div metal:fill-slot="main">
  your stuff here
</div>

There are other things to know about how a page gets rendered, but this is the basic idea.

Creating the page

With define-slots and fill-slots in mind, I created my ZPT at the root of my Plone site called index_html so I could start hacking. For my purposes I was only interested in changing the fill-slot main so I defined my fill-slot like above and put some bogus content in it to make sure I was on the right track. I filled out the rest of the code with guidance from examples in the book, other code in the Plone portal_skins area as well as in the Quills product directory.

Getting the entries

The Quills file /Zope/Products/Quills/WeblogArchive.py had two methods defined which return a list of blog entries - getEntries() and getLazyEntries(). The difference being that the latter only returns the catalog search objects, so it's fast but the data which can be displayed is limited to the metadata definitions in the portal_catalog. I was hoping to get the full text of the entry so initially used getEntries(), but it turned out to be too slow.

Keeping with the site look

Next I wanted to use as much of the site style sheet as possible too keep the look consistent. Most of the important entries are in the main style sheet which is found at /your_plone_site_folder/portal_skins/plone_styles/plone.css.

Extras

I added this page to the site RAM Cache since this is the front page and the entries don't change very often. ZMI > Cache Tab > Cache Object Using RAM Cache > Save Changes. Easy.

I also hacked together an RSS icon and feed in the h1 title.

Things to update

My page works, but I should tidy up some of the CSS and change the design to be a little more interesting. I also have hard-coded the name of my weblog object instead of using the `portal_catalog` to find it for me.

You can download the final page template here.