Quick Guide: Creating a Plone 3 theme product on the file system / by Mike Takahashi

Plone logo
Plone logo

Creating a Plone 3 theme product on the file system can be notoriously daunting for beginners. A lot of documentation exists, but it is somewhat fragmented and can be confusing. I've been designing and skinning themes for Plone for quite sometime now and thought it would be nice to have a quick guide on how to create Plone 3 theme products on the file system.

There are essentially 3 things that you need to do which involve:

  1. Moving viewlets
  2. Modifying viewlets
  3. Adding theme files

To start, you should first create your theme through the web in the ZMI and place all of the files in the /custom folder. Once your design is finalized, you can then move everything into your product on the file system. I like to use FSDump to dump files from the ZMI into the file system.

Through the web

1. Moving viewlets

Plone’s default layout is composed of viewlets such as the globalnav (top navigation) that are controlled by viewlet managers. These viewlets can be re-arranged by re-ordering the viewlets through the web by appending @@manage-viewlets to the end of your site URL: http://[your_plone_site]/@@manage-viewlets.

For a quick reference on what each viewlet is, check out Where is What in Plone 3.

2. Modifying viewlets

To modify the templates for each viewlet, you’ll need to go into the ZMI to /portal_view_customizations.

3. Adding theme files

Files such as images and CSS should be placed in the /custom folder within the ZMI

The file system

Once your design is finalized, you need to transfer all of the files and layout changes from the web to the file system to create a Plone 3 theme product.

You should use Paster to generate the initial framework and files for your Plone 3 theme product on the file system. For more information on how to use Paster, check out How to Create a Plone 3 Theme Product on the Filesystem.

1. Moving viewlets

Re-ordering viewlets through the web is quite easy using the @@manage-viewlets option. However, when creating a product on the file system, you’ll need to re-order these by calling specific rules within profiles/default/viewlets.xml, which is created by Paster.

Let’s say you moved the personal_bar to the top of the layout. You need to locate the viewlet manager that contains the viewlet using @@manage-viewlets.

Screenshot of manage viewlet screen

By default, plone.personal_bar is managed by the plone.portaltop viewlet manager. A rule needs to be applied that re-orders the plone.personal_bar viewlet within the plone.portaltop viewlet manager.

Here is the rule within viewlets.xml:

... 
<order manager="plone.portaltop" skinname="[YOUR_PLONE_THEME]" 
       based-on="Plone Default"> 
       <viewlet name="plone.personal_bar" insert-before="*"/> 
</order> 
...

This rule says to place plone.personal_bar before all other viewlets that are managed by the plone.portaltop viewlet manager.

For more detailed information on moving viewlets, check out Move Viewlets Between Viewlet Managers.

2. Modifying viewlets

Any viewlets that you customized in /portal_view_customizations through the ZMI goes into the browser/ folder of your theme that was created by Paster.

Let’s say you customized the footer and global_sections. You’ll need to add the footer.pt and sections.pt templates in the browser/ folder and then reference them in browser/configure.zcml:

... 
<browser:viewlet 
    name="plone.footer" 
    for="*" 
    manager="plone.app.layout.viewlets.interfaces.IPortalFooter"  
    layer=".interfaces.IThemeSpecific" 
    template="footer.pt" 
    permission="zope.Public" 
/> 
<browser:viewlet 
    name="plone.global_sections" 
    for="*" 
    manager="plone.app.layout.viewlets.interfaces.IPortalHeader"           
    class=”plone.app.layout.viewlets.common.GlobalSectionsViewlet”
    layer=".interfaces.IThemeSpecific" 
    template="sections.pt" 
    permission="zope2.View" 
/> 
...

One important thing to note is the class="plone.app.layout.viewlets.common.GlobalSectionsViewlet" attribute in global_sections.

global_sections creates content dynamically and therefore references a special class. If you forget to include it, you’ll get an error. The footer on the other hand is only static text by default, so it doesn’t need the class attribute.

The manager=" " attribute can also be found in @@manage-viewlets.

Screenshot of manage viewlet screen

3. Adding theme files

You’ll need to place your theme files such as images and CSS in the skins/ folder, which is broken up into three sections:

skins/plonetheme_[your_product_name]_custom_images
skins/plonetheme_[your_product_name]_custom_templates
skins/plonetheme_[your_product_name]_styles

Any custom CSS files also need to be be registered within portal_css. To do this, you’ll need to reference them in profiles/default/cssregistry.xml. Paster should have created them for you.

Note, you have two options for your image and CSS files. You can either place them in the skins/ folder or in the browser/ folder. However, if you’ll be using any custom DTML calls in your CSS such as &dtml-portal_url; to generate your URL dynamically, you’ll need to keep them in the skins/ folder. Only static CSS files can go into the browser/ folder.

As best practice, you should also create an uninstall profile. If you don’t, when your theme is uninstalled it may not reset your Plone site back to its default layout.

Now that you have your product, install it!