How to Install a 3.x Theme Using Buildout
Purpose
If you wish to install a theme product that is available on PyPI, or as a Python package on Plone.org — and you don't need to customize it — you may just add it to the "eggs =" section of your buildout. However, if you plan to customize or develop the product, you'll need to copy it into a workspace directory. Which directory depends on the type of packaging: Python package (egg) or old-style.
In this document, we will look at how to install for customization a Plone theme that you have downloaded from Plone.org/products, PyPi, etc., or that you have created on your own. There are two kinds of theme products: newer egg-based products, and older theme products that are in the "magical Products namespace". The type of theme product you are working with determines the steps you must take to install your theme. We'll now see how to tell the difference between the two.
Is Your Theme Product Egg-Based or an old-style Zope Product?
If your theme is in an archive, like a .tar.gz, .tgz or .zip file, unpack it. Look at the contents.
First, we need to understand what egg-based means. Eggs are Python packages. If your theme is named plonetheme.whatever, or you generate a new theme using the Paster recipe, then your theme product is egg-based. On an even simpler note, if the root folder contains setup.py, it's an egg. In a typical egg-based theme product, setup.py would look something like this, where the highlighted text is the name of the egg.
from setuptools import setup, find_packages version = '1.1' setup(name='webcouturier.icompany.theme', [...]
If your product looks like was created using DIYPloneStyle 3.x (now outdated), it is an old-style Zope product. You can also tell because there is no setup.py file in the root.
Installing an Egg-Based Theme Product
In this section, we will look at how to install egg-based themes using buildout. As of Plone 3.1.2, all of the Plone installers create a buildout that contains your Plone instance. When installing or developing themes, buildout is highly recommended.
To install an egg-based theme product, first unpack your theme product (if in a .tgz, .tar.gz or zip archive). Copy the package to the src/ folder of your buildout. Then, edit your buildout.cfg and add the following information into the buildout, instance, and zcml sections. The actual buildout.cfg file will be much longer than the snippets below:
[buildout]
...
develop =
src/plonetheme.yourtheme (where yourtheme is the name of the theme you downloaded)
[instance]
eggs =
...
plonetheme.yourtheme
zcml =
...
plonetheme.yourtheme
The last line tells buildout to generate a ZCML snippet (slug) that tells Zope to recognize your theme product, prefixed by the namespace (plonetheme is the default). The dots [...] indicate that you may have additional lines of ZCML code here. If another package depends on the theme egg or includes its ZCML directly, you do not need to specify anything in the buildout configuration; buildout will detect this automatically. This is considered a more advanced topic.
After updating the configuration you need to run the ''bin/buildout'', which will refresh your buildout.
Then, restart your site and go to the 'Site Setup' page in the Plone interface and click on the 'Add/Remove Products' link. The 'Site Setup' area is also known as plone_control_panel, as this is the URL used to get to 'Site Setup'.
Choose the product by selecting the checkbox next to it and click the 'Install' button.
Note: You may have to empty your browser cache to see the effects of the product installation.
Installing Your Product if it is an old-style Zope Product
Assuming your theme product is an older 3.x theme, all you have to do is place your (unpacked if necessary) theme product in your buildout's "products/" directory and restart your Zope instance. There is no need to rerun your buildout, because we have not changed any ZCML code.
Then, after your Zope has restarted, go to the 'Site Setup' page in the Plone interface and click on the 'Add/Remove Products' link. The 'Site Setup' area is also known as plone_control_panel, as this is the URL used to get to 'Site Setup'.
Choose the product by selecting the checkbox next to it and click the 'Install' button.
Older style themes may show up twice in the portal_quickinstaller, but this is a bug that is fixed in a more recent version of ZopeSkel. You can either ignore the bug or resolve it by removing this line from your theme product's configure.zcml file and restarting your Zope instance:
<five:registerPackage package="." initialize=".initialize" />
Note: You may have to empty your browser cache to see the effects of the product installation.
Uninstalling a Theme Product
Uninstalling can be done from the 'Site Setup' / 'Add/Remove Products' page, but only if you installed it from the 'Add/Remove Products' screen. Not all themes uninstall cleanly, but reinstalling the Default Plone product generally cures any issues here.
Next Steps
Assuming that you want to customize your theme (or you want to create your own theme from scratch), you should read the following documents as next steps:
http://plone.org/documentation/how-to/how-to-make-your-css-changes-take-effect-instantly
http://plone.org/documentation/how-to/how-to-create-a-plone-3-theme-product-on-the-filesystem
http://plone.org/documentation/tutorial/customizing-main-template-viewlets
Visit our