h3. 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@.
h3. 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) at @/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.
This content will be replaced.
... |
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:
your stuff here
your stuff here
There are other things to know about how a page gets rendered, but this is the basic idea.
h3. 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.
h3. 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.
h3. 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@.
h3. 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.
h3. 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 click here to download the template.