How to Create and Set A Custom Homepage Template Using Generic Setup

by Jeremy Stark — last modified Jun 23, 2009 03:49 PM

Have a custom template you want to use as the default home page for Plone? Follow these simple steps.

Purpose

Plone allows for selectable display templates for most content types including the portal root itself. Getting an item into the portals "display" menu requires touching several configuration files. Actually setting it to be the default template for a newly created Plone site requires touching one more.

Luckily it is all pretty straight forward using GenericSetup. Follow the steps below and everything should work out.

Prerequisites

It's assumed you have a development buildout for Plone and want to add a default home page to it. If you do not have a Plone buildout yet and a theme product you'll need to set one up for these instructions to make any sense. It's also assumed you used "paster" to create your theme product or know what your doing and can translate these instructions to your setup.

Check the Managing projects with Buildout tutorial for further info about buildout, and the Create new eggs and packages quickly with paster howto to learn how to use paster. GenericSetup basics can be learnt from Understanding and using GenericSetup in Plone.

Making the Configuration Changes

Let's quickly create an example home page template. Inside the "browser" directory of your theme create a page template file called homepage.pt:

<html metal:use-macro="here/main_template/macros/master">
  <div metal:fill-slot="body">
    <h1>My Home Page</h1>
  </div>
</html>

Now we need to modify browser/configure.zcml. First, add this include near the top:

<include package="plone.app.contentmenu" />

This imports the plone_displayviews menu (the dropdown that appears when you click the "display" link above the content) which we will need below when we create a menu item for our page template.

Next, register a new browser view that uses our page template:

<browser:page
      for="Products.CMFCore.interfaces.ISiteRoot"
      name="homepage"
      template="homepage.pt"
      layer=".interfaces.IThemeSpecific"
      permission="zope2.View"
/>

This will allow the page to be accessed from http://url-path-to-plonesite/homepage.

Now add a menuItem just below the page definition:

<browser:menuItem
  for="Products.CMFCore.interfaces.ISiteRoot"
  menu="plone_displayviews"
  title="my home page"
  action="homepage"
  description="My home page template"
/>

These configurations tell Plone that we have a new template and menu item that can only be applied to objects that implement the ISiteRoot interface, like Plone sites for example.

Next we need to add homepage as an available display template for "Plone Site" objects. You can go into the portal_types tool and add it yourself by selecting the "Plone Site" type and adding it to the "Available view methods" property. But we want it to be automatically added and selected as the default view.

Create the file profiles/default/types/Plone_Site.xml (notice the capital P and S) and add the following:

<?xml version="1.0"?>
<object name="Plone Site"
        meta_type="Factory-based Type Information with dynamic views"
        i18n:domain="plone" xmlns:i18n="http://xml.zope.org/namespaces/i18n">
  <property name="view_methods">
    <element value="homepage" />
    <element value="folder_tabular_view" />
  </property>
  <property name="default_view">homepage</property>
</object>

Note the view_methods property where homepage was added as an option. We also removed a bunch of the other default ones but left folder_tabular_view because it's helpful for development. Also note default_view is set to homepage. These settings override those defined in parts/plone/CMFPlone/profiles/default/types/Plone_Site.xml.

Next, create the file profiles/default/properties.xml and add the following:

<?xml version="1.0"?>
<site>
  <property name="default_page" type="string">homepage</property>
</site>

These settings override those found in parts/plone/CMFPlone/profiles/default/properties.xml. There, now you are done! Restart Zope and add a new Plone site using your theme. The "homepage" template should be set as the default home page.