The DIYPloneStyle way

cd path_to_zope_instance_home_folder/Products/
DIYPloneStyle/bin/generator.py --productname=MyOwnPloneSkin --skinname="My Theme"

cd c:\Plone\Data\Products
c:\Plone\Python\python.exe DIYPloneStyle\bin\generator.py --productname=MyOwnPloneSkin --skinname="My Theme"

python.exe DIYPloneStyle\bin\generator.py --productname=MyOwnPloneSkin --skinname="My Theme"

The ZopeSkel way

ZopeSkel extends the Paste Script utility, a command line tool for generating skeleton Python packages and eggs which is based on a set of templates. Paste Script installs a command line utility called paster. paster is called with the create command for generating new code structures on the file system (see further in this chapter for usage example).

ZopeSkel is an extension set of templates for the paster create utility that can generate packages for Zope and Plone (for Plone 2.1 up to Plone 3.0), including theme packages.

First, install paster and ZopeSkel, as explained in Daniel Nouri's how-to about creating eggs and packages.

Don't be scared about having to install several components, installing ZopeSkel is very easy and can be done in no more than three command lines thanks to the 'easy_install' python tool:

wget http://peak.telecommunity.com/dist/ez_setup.py
sudo python ez_setup.py
easy_install ZopeSkel

Now that you have ZopeSkel installed, run in a terminal:

paster create -t plone3_theme plonetheme.mytheme

Depending on the Plone version you want to develop a theme for, you can make use of the 'plone2.5_theme' or the 'plone3_theme' template in the command for creating your product. Differences between those two skeletons will be detailed in further sections of this document.

This tutorial does not cover the use of the 'plone2_theme' template, which is an adaptation of DIYPloneStyle 2.1. If you need to, you can learn how to build a theme for Plone 2.1 from the former DIYPloneStyle documentation.

As we need to be able to have the Generic Setup profile of our theme to be recognized by Plone, and the directories listed in skins/ to be registered with the Skins Tool, our package has to be loadable by Zope 2. For achieving this, always answer 'True' (which is the default value) to the question "Enter zope2product (Are you creating a Zope 2 Product?)" during code generation process. Note that there is an ambiguity here: giving the value 'True' to the zope2product parameter does not mean that ZopeSkel will create a Zope Product that can be put in the Products/ folder of a Zope instance. It means that the package that ZopeSkel creates will be loaded by Zope 2: it will be listed in the ZMI, in the Control_Panel > Products page, its skins/ folders will be recognizable by the Skins Tools ('portal_skins'), and its Generic Setup profile can be loaded in the Setup Tool ('portal_setup'). It is still a package though, in the sense that it has to be put somewhere in the python path (usually in the lib/python/ directory of a Zope instance). Its ZCML configuration file needs to be declared somewhere (from a ZCML slug in package-includes or from an include package ZCML declaration in the configure.zcml file of another package). In addition, this package is structured by ZopeSkel to be useable as an egg.

The preferred way

Now the big question: Which is the best way to generate my new theme project base code?

I personally prefer the ZopeSkel/paster approach for several reasons:

• ZopeSkel is fully cross platform. Although DIYPloneStyle is written in Python, some users experienced problems on Windows with DIYPloneStyle generated theme products. I am working on these issues but I still don't see why it is perfectly working on Linux/Unix systems while giving people headaches on Windows.

• ZopeSkel generates python packages that can be installed anywhere in the python path, while DIYPloneStyle generates Zope Products that have to be put in the Products/ folder of a Zope instance. I know that some people still prefer to work with Zope Products because they don't have to take care of the zcml slug for having Zope to load the package. This is a personal choice. Personally, I prefer to work as close as possible to the pure Python (and Zope 3) way of managing python packages, which implies generating a package with ZopeSkel.

• ZopeSkel generates python eggs that can be installed with easy_install. Main benefit of Python eggs is that they manage their own dependencies. I also like working with eggs in a buildout, I find it practical and easy.

• Oh, and I forgot to mention that, even if ZopeSkel focuses on building beautiful eggs, it is still possible to generate a pure Zope 2 product with ZopeSkel and its Plone3_theme template.

  By giving "Products" as value to the namespace_package variable during the interactive prompt session, we ensure to have, at the package level, a product that complies with the Zope 2 products common layout.

  With this command for instance:

  paster create -t plone3_theme Products.MyTheme
  Enter namespace_package (Namespace package (like plonetheme)) ['plonetheme']: Products
  Enter package (The package contained namespace package (like example)) ['example']: MyTheme
  Enter skinname (The skin selection to be added to 'portal_skins' (like 'My Theme')) ['']: My Theme
  ...
  

  Important

  When generating your theme product that way, you should not reside (current dir in the shell) in the Products/ directory of your Zope instance, but somewhere else, for instance in a directory created specifically for development purposes inside that Zope instance folder.

  Once you have your package generated, copy or symlink the Products.MyTheme/Products/MyTheme package in your Zope instance Products/ directory, and restart Zope.

  The result of the plone3_theme template when calling the namespace package "Products" complies with the way the subversion repository of Plone itself is organized nowadays: What used to be stored as CMFPlone and be a Zope 2 product, has been moved to Products.CMFPlone. It is now organized as an egg, but the code of the package itself is strictly identical as what it used to be when known as CMFPlone.

• ZopeSkel can create on the fly a subversion repository structure for the generated project, just before applying the template. Simply use the --svn-repository option while calling the paster create command, for instance:

  paster create -t plone3_theme --svn-repository=https://svn.plone.org/svn/collective plonetheme.mytheme
  

  With this command, paster will create plonetheme.mytheme/branches/, plonetheme.mytheme/tags/ and plonetheme.mytheme/trunk/ in the specified subversion repository, and add the generated files to trunk. All what you'll have to do after the package was generated is to commit to svn. Handy, isn't it?

  One small advise if you plan to ask paster to generate your subversion structure: add *.egg-info and *.pyc to the global-ignores patterns in your subversion configuration file (usually ~/.subversion/config). That way, paster will not add the unwanted plonetheme.mytheme.egg-info folder and setup.pyc compiled python file to your repos, and you won't have to remove them manually.

• It is relatively easy for a programmer or an integrator to develop the paster templates that suit her/his development needs. Creating a set of specific templates for a company or in the context of a specific project is made possible thanks to the Paste Script.

• The Paste Script is much more than a template based code generator, read more about it.

All this doesn't mean that you should not use DIYPloneStyle at all anymore. If you are used to working with it and don't want to make you head around a new way to generate your new projects, just keep using DIYPloneStyle. Again, it is just a question of personal choice.

At least as long as DIYPloneStyle outputs valid code for Plone...

ZopeSkel will slowly become the standard way

DIYPloneStyle will not be realeased in a new major version, so ZopeSkel will become _THE_ way to generate new theme projects for Plone starting from Plone 4 (or any Plone version that would make DIYPloneStyle 3.0 obsolete). Although, DIYPloneStyle 3.x will be maintained with bug fixes, and minor releases will be out as bugs are found/fixed.