--- title: Theming Plone 4 - Part 1 date: 2010-05-19 description: 'Step-by-step guide to prepare a Plone 4 theming environment on Ubuntu Lucid: install zopeskel, create the buildout, scaffold a plone3_theme product and fine-tune it before running buildout.' tags: - plone - theming - buildout - zopeskel extra: deprecated: true deprecated_reason: Plone 4 theming via plone3_theme product is deprecated; Plone 5+ uses Diazo/Mosaic --- Lately I've been doing themes for Plone 4. I forget things, so these notes serve as documentation for some tricks I usually do for theming. There might be better ways to do some of them, so your comments are greatly appreciated. The audience is anyone who has previous experience with buildout, Plone, Plone theming and related technologies like JavaScript, HTML, CSS and so on. **UPDATE:** Part 2 is now available. This is Part 1. ## Setting up the environment I will use `pastescript` and buildout on Linux. On a clean install of Ubuntu Lucid Lynx, I did: ```console $ sudo aptitude install build-essential python-dev python-pip python-pastescript python-setuptools $ sudo pip install zopeskel ``` ## Create the buildout ```console $ paster create -t plone3_buildout Selected and implied templates: ZopeSkel#plone3_buildout A buildout for Plone 3 installation Enter project name: plone4b3 Variables: egg: plone4b3 package: plone4b3 project: plone4b3 ************************************************************************** ** *** NOTE: You probably don't want to use this template! ** Since Plone 3.1, the preferred way to get a buildout-based setup ** for Plone is to use the standard installer for your operating ** system (the Windows installer, the Mac installer, or the Unified ** Installer for Linux/Unix/BSD). These give you a best-practice, ** widely-used setup with an isolated Python and a well-documented ** buildout. This template is here for older versions of Plone and ** for experts who explicitly want a raw, non-installer-based ** installation. ** (This message is particularly aimed at people following out-of- ** date books/documentation that suggest this is the right way to get ** a Plone-based buildout. This is no longer the case.) ************************************************************************** Expert Mode? (What question mode would you like? (easy/expert/all)?) ['easy']: easy Plone Version (Plone version # to install) ['3.3.4']: 4.0b3 Zope2 Install Path (Path to Zope2 installation; leave blank to fetch one!) ['']: Plone Products Directory (Path to Plone products; leave blank to fetch [Plone 3.0/3.1 only]) ['']: Initial Zope Username (Username for Zope root admin user) ['admin']: Initial User Password (Password for Zope root admin user) ['']: secret HTTP Port (Port that Zope will use for serving HTTP) ['8080']: Debug Mode (Should debug mode be "on" or "off"?) ['off']: Verbose Security? (Should verbose security be "on" or "off"?) ['off']: Creating template plone3_buildout Creating directory ./plone4b3 Copying README.txt to ./plone4b3/README.txt Copying bootstrap.py to ./plone4b3/bootstrap.py Copying buildout.cfg_tmpl to ./plone4b3/buildout.cfg Recursing into products Creating ./plone4b3/products/ Copying README.txt to ./plone4b3/products/README.txt Recursing into src Creating ./plone4b3/src/ Copying README.txt to ./plone4b3/src/README.txt Recursing into var Creating ./plone4b3/var/ Copying README.txt to ./plone4b3/var/README.txt ************************************************************************** ** Generation finished. ** You probably want to run python bootstrap.py and then edit ** buildout.cfg before running bin/buildout -v". ** See README.txt for details. ************************************************************************** And finally, let's run bootstrap and buildout to download Plone 3. tzicatl@tzicatl-lynx:~/plone4b3$ python bootstrap.py Creating directory '/home/tzicatl/plone4b3/bin'. Creating directory '/home/tzicatl/plone4b3/parts'. Creating directory '/home/tzicatl/plone4b3/eggs'. Creating directory '/home/tzicatl/plone4b3/develop-eggs'. Generated script '/home/tzicatl/plone4b3/bin/buildout'. tzicatl@tzicatl-lynx:~/plone4b3$ bin/buildout ..... $ ``` ## Create theme product and add it to the buildout Now, let's create the theme. We are going to base our design on [this template](http://www.freecsstemplates.org/preview/hanging/) from FreeCSSTemplates.org: ```console $ cd plone4b3/src $ paster create -t plone3_theme Selected and implied templates: ZopeSkel#basic_namespace A basic Python project with a namespace package ZopeSkel#plone A project for Plone products ZopeSkel#plone3_theme A theme for Plone 3 Enter project name: plonetheme.hanging Variables: egg: plonetheme.hanging package: plonethemehanging project: plonetheme.hanging Expert Mode? (What question mode would you like? (easy/expert/all)?) ['easy']: easy Skin Name (Name of the theme (human facing, added to portal_skins)) ['']: FreeCSSTemplates.org Hanging Empty Styles? (Override default public stylesheets with empty ones?) [False]: Include Documentation? (Include in-line documentation in generated code?) [True]: False Version (Version number for project) ['1.0']: Description (One-line description of the project) ['An installable theme for Plone 3']: An installable theme for Plone 4 Creating template basic_namespace Creating directory ./plonetheme.hanging .... ``` Now it's time to modify `buildout.cfg` in order to add the newly created theme product. So it's also time to do some extra modifications; these include: * Remove all comments. * Move `eggs` and `zcml` declarations from the `[instance]` section to the `[buildout]` section. * Add PIL and `plonetheme.hanging` to the eggs section. * Add ZCML slug for `plonetheme.hanging`. ## Fine-tune the theme package Before running buildout, we are going to "fine-tune" the theme package. Let's start with `src/plonetheme.hanging/setup.py`: * Add author and author e-mail. * Change url from to . * Change license from "GPL" to "Creative Commons Attribution 3.0 Unported" (I'm not a lawyer, so I don't know if I'm doing it right). * Modify `README` to include credits and description. * Rename `docs/LICENSE.GPL` to `LICENSE.CC` and paste the CC license contents. * Edit `src/plonetheme.hanging/plonetheme/hanging/configure.zcml` and delete the line ``. This is because we are not doing locales on this theme, but we can. * I don't like the long names that paster creates for the folders inside the skins directory, so I usually change them to something shorter. In order to do that: - Rename the directory, for example: rename from `plonetheme_hanging_custom_images` to `hangingtheme_images`. - Change the corresponding name in `skins.zcml` and `profiles/default/skins.xml` (working from `src/plonetheme.hanging/plonetheme/hanging`). - Note 1: Using your editor's "Search & Replace" is a good idea. - Note 2: You can add another extra skin layer by adding directories and editing the two files above. * Change the base theme from "Plone Default" to "Sunburst Theme" by editing `profiles/default/skins.xml`. - Open the file and look for this line: `` - Change the `based-on` parameter from "Plone Default" to "Sunburst Theme". - This step is important in order to get all the new Plone 4 look & feel and change it to suit our needs. Now, we are ready to run the buildout process. First, run `bootstrap.py` if you haven't already done so: ``` $ python bootstrap.py ``` The buildout process will take some minutes depending on the speed of your computer and mainly your network bandwidth: ``` $ bin/buildout ``` You might see some warnings but you should not see any error. ## Start the Plone instance If the buildout process was successful, now you will be able to start your Plone instance in foreground mode: ```console tzicatl@tzicatl-lynx:~/plone4b3$ bin/instance fg 2010-05-19 18:02:43 INFO ZServer HTTP server started at Wed May 19 18:02:43 2010 Hostname: 0.0.0.0 Port: 8080 2010-05-19 18:02:53 WARNING ZODB.FileStorage Ignoring index for /home/tzicatl/plone4b3/var/filestorage/Data.fs 2010-05-19 18:02:53 WARNING ZODB.blob (10127) Blob dir /home/tzicatl/plone4b3/var/blobstorage/ has insecure mode setting 2010-05-19 18:03:12 INFO Zope Ready to handle requests ``` Create a site and install the newly created theme. You should see a site equal to Plone 4's SunBurst Theme: ![Our Plone theme](/static/images/posts/theming-plone-4-part-1/plone4-theming1.png) ## Wrap up On this installment we learned (or I hope so) to prepare our system for buildout and Zope; we learned to create a Plone 4 instance from scratch and also learned to create and prepare a Plone product for the new theme we are going to make. That's all for now. Wait for Part 2.