How to Create a Plone 3 Theme Product on the Filesystem
Jumpstart Your Theme Development Using Paster
The quickest and most efficient way to get started is not to create your theme product folders and associated files from scratch, but to take advantage of a product generator which will automatically create the framework for a theme product based on your responses to a few interactive questions.
Using Paster Through the Web
New users may feel more comfortable using a through the web tool that allows them to generate a theme product. One such tool can be found at http://paster.joelburton.com/. You may wish to reference some of the information below for more information on what is actually happening as you fill out these questions.
Using Paster on Your Local Machine
For users more comfortable using the command line, you are more likely to use a tool called ZopeSkel and the paster templates it contains. ZopeSkel is a collection of PasteScript templates which can be used to quickly generate Zope and Plone projects like buildouts, archetypes products and, most pertinently for us, Plone themes.
To determine whether you have paster and ZopeSkel installed, try "paster create --list-templates" at the command line. If "plone3_theme" is not in the list of available templates, you may have to install paster and/or ZopeSkel, as explained by Daniel Nouri.
If you have paster and ZopeSkel installed, navigate to the directory where you'd like to create your product and run from the command line:
$ paster create -t plone3_theme plonetheme.mytheme
This will initiate a series of questions by the paster script. The defaults are largely appropriate for your first theme, so in many cases you can simply hit return. Here is example output from the interactive session.
Selected and implied templates:
ZopeSkel#basic_namespace A project with a namespace package
ZopeSkel#plone A Plone project
ZopeSkel#plone3_theme A Theme for Plone 3.0
Enter namespace_package (Namespace package (like plonetheme)) ['plonetheme']:
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
Enter skinbase (Name of the skin selection from which the new one will be copied) ['Plone Default']:
Enter empty_styles (Override default public stylesheets with empty ones?) [True]:
Enter include_doc (Include in-line documentation in generated code?) [False]:True
Enter zope2product (Are you creating a Zope 2 Product?) [True]:
Enter version (Version) ['1.0']:
Enter description (One-line description of the package) ['An installable theme for Plone 3.0']:
Enter long_description (Multi-line description (in reST)) ['']:
Enter author (Author name) ['Plone Collective']:
Enter author_email (Author email) ['firstname.lastname@example.org']:
Enter keywords (Space-separated keywords/tags) ['web zope plone theme']:
Enter url (URL of homepage) ['http://svn.plone.org/svn/collective/']:
Enter license_name (License name) ['GPL']:
Enter zip_safe (True/False: if the package can be distributed as a .zip file) [False]:
You cannot use 'delete' to correct a typo during the interactive session. If you make a mistake, ctrl-c to stop the script and start over.
Some of these questions warrant further explanation:
- Enter namespace_package
- It is good practice to use the 'plonetheme' namespace for your theme. You can use other namespaces, of course ('products' might be another), but unless you have a compelling reason to do otherwise, use 'plonetheme'.
- Enter package
- The 'package' is simply the lowercase name of your theme product, sans spaces or underscores.
- Enter skinname
- The 'skinname' is the human-readable name for your theme. Spaces and capitalization are appropriate.
- Enter skinbase
- In nearly all cases, you'll want to leave this as 'Plone Default'.
- Enter empty_styles
- Answering 'True' will cause empty stylesheets to be added to your product which will override the default base.css, public.css, and portlets.css included in any Plone site using the 'Plone Default' skin. 'False' will not add empty stylesheets.
- Enter include_doc
- Answering 'True' will cause inline documentation to be added to the files created by ZopeSkel. It is worth doing this at least once, as some of the documentation is quite useful.
- Enter zope2product
- Answering 'True' means that the package will be useable as an egg, it will be listed in the ZMI, skin folders will be registered as layers with the Skins Tool ('portal_skins'), and the Generic Setup profile for the product can be loaded via the Setup Tool ('portal_setup'). We'll explore some of this further; for now, suffice to say that you'll always want to enter 'True' here when generating a Plone theme.
- Enter zip_safe
- Stick with the default here.
- Creating new eggs and packages quickly with paster
- How to use the paster command to create new packages with proper setuptools- and egg-compliant filesystem layout quickly and easily.
Background: Python Eggs, Generic Setup and Zope 3
Products, in Plone's parlance, are analogous to modules or extensions for other applications. In the move from Plone 2.5 to Plone 3, several important changes were made in the way Plone handles products. First, some products began to be packaged as Python eggs, which made them easier to manage, distribute and install. Second, products began to use GenericSetup as a means for installation. And third, products increasingly incorporated Zope 3 (Z3) technologies like browser views.
A python egg is simply a bundle of files and directories which constitute a python package. Eggs can either be compressed, in which case they appear as a single *.egg file, or uncompressed. Eggs are similar in concept and function to Java's JAR files.
Eggs are installed via the setuptools framework, a side project of the Python Enterprise Application Kit (PEAK), which provides for package (and dependendency) management and distribution.
If you're using version control, you'll want to add *.egg-info and *.pyc to the ignore patterns for your setup so that the egg metadata and compiled python files aren't added to your repository.
GenericSetup (GS) is a tool for managing site configuration in Plone using xml files. GS makes it possible to export customizations from one Plone site and import them into another. And to some extent, GS replaces the Portal QuickInstaller (QI) post-Plone 2.5 in that GS can be used to install products. In products which rely on GS, we find xml configuration files; in products which use the older, venerable QI for installation, by comparison, we find install methods written in python.
Keep in mind that GenericSetup does not currently allow you to undo the profile applied during installation. You can uninstall your theme using the QuickInstaller, however, assuming that an uninstall method is present.
Because our skeleton theme product utilizes GenericSetup to install itself, we will shortly be configuring several xml files needed by GS.
- Understanding and Using GenericSetup in Plone
- Now a bit dated, Rob Miller's tutorial on GS remains a useful resource for background on GS.
- GenericSetup Improvements
- More information about GS from Rob Miller.
- Benefit NOW from Using GenericSetup and Z3 Technologies
- Impress your colleagues by using GenericSetup and Zope 3 views efficiently and with minimal effort! This tutorial shows you how to add a new view, how to use it, how to add a new content type and how to hook it all up.
Zope 3 Technology
Despite any version number-induced miasma, remember that Plone 3 runs on Zope 2. Zope 3 is a dramatic rewrite of Zope 2 and some Zope 3 functionality has been backported to work under Zope 2. (And yes, Plone 3.) For a full explanation of the Zope 3 technologies involved, consult this tutorial:
- Customization for developers
- An overview of Plone 3 customization by Martin Aspeli.
Anatomy of a Plone Theme Product
Assuming that you've created your theme product successfully, you should have a directory structure that looks roughly like this:
Things may seem a little complicated at this point, but not to worry. Let's take closer look at the main files and directories according to their respective functions.
- The docs directory contains installation instructions (INSTALL.txt), license files, and the development log (HISTORY.txt).
- The top-level text file contains the one-line description of the product you entered during the interactive session with ZopeSkel. Other README files exist throughout the product.
- This is a namespace package, which serves to group other packages.
- This is the actual name of your theme, usually the name of the client or project you are working on.
- Python tests for our package go here. Typically themes don't have much python code, and so don't have much in the way of testing.
- The version of our product. This information is also contained in /profiles/default/metadata.xml.
- The egg metadata is stored here.
- This configuration file contains information used to create egg-info files.
- If we wanted setuptools to handle the installation of the package and dependencies we could install via "python setup.py install" (for now, we don't).
- Register appropriate GenericSetup profiles.
- This is the ZCML slug which must be placed in the etc/package-includes if the theme is installed as a python package (ours won't be).
- Register skin layers (images, styles, templates) as filesystem directory views.
Stylesheets, Templates and More
Once you've got your theme product in place, the next step is to modify the pieces that Plone gives us, specifically templates, stylesheets, and viewlets.
- Plone templates, specifically the main_template that controls the layout of a Plone site, can be grabbed from the parts/plone/CMFPlone/skins/plone_templates directory. Most of the templates that were contained here in 2.5 have been moved to eggs and are controlled by viewlets. To modify a template from this directory, copy it to your theme product, into your theme's skins/templates folder and make your modifications there.
- Plone's default stylesheets can be found in your buildout/parts/plone/CMFPlone/skins/plone_styles directory. It's usually advisable to create a stylesheet specific to your theme product, e.g. "mytheme.css" (where "mytheme" is the name of your theme product), and then take any relevant styles from CMFPlone's stylesheets and customize them in your own theme product, rather than overriding entire CMFPlone stylesheets. The one exception here may be IEFixes.css, which you likely want to keep intact as a single file, since it is called in explicitly from the main_template.
- It is a great oversimplification to state that most often you will be overriding viewlets from eggs commonly known as plone.app.layout, plone.app.portlets, and plone.app.content. Those viewlets, can be found in your buildout/eggs/ in packages named "plone.app.layout[xx]," "plone.app.portlets[xx]," and "plone.app.content[xx]," where [xx] is a version number. When modified, these viewlets and their related code belong in your theme product's browser/ directory. For more information on how to work with viewlets, read this tutorial.
If modifying page templates, you won't need to restart Zope in order to see your changes take effect. Changes to python, XML or ZCML, however, will require a restart.
- Customization for developers
- An overview of Plone 3 customization by Martin Aspeli.
- Find the best theme of iphone 4s deals handset
- For more information, go here: http://plone.org/documentation/how-to/how-to-install-a-3-x-theme-using-buildout
Installing Your Theme Product