Since version 2.1 Plone ships with "ResourceRegistries":/products/resourceregistries, a component that provides tools for managing stylesheet and javascript files linked to plone pages (templates). These tools - *portal_css* and *portal_javascripts* - let you register CSS and JS files in a way close to how actions are registered with *portal_actions* (for instance you can put a condition on them). Thanks to ResourceRegistries, we can now customize Plone look in a much cleaner and more powerful way. One of the common ways to customize components of a Plone site is to do it TTW (from the ZMI), making use of the 'custom' layer in the *Skins Tool*. Although it works, this approach only suits small customer side changes, made by people who don't have access to the filesystem. If this is all you need to do, you'd probably be happy enough with reading the "chapter 7":http://docs.neuroinf.de/PloneBook/ch7.rst of the Plone 2.0 book. But if you think of building a full graphical environment for Plone, the best practice is to write a python code product on the filesystem. In this tutorial, we will use "DIYPloneStyle":/products/diyplonestyle - a simple example/skeleton of a skin product for Plone 2.1 - as a base for discovering how the stylesheet and javascript registries work, and start building a new product that installs a custom style in any Plone portal. DIYPloneStyle is based on two complementary products: - Martin Aspeli's "MySkin":/products/myskin, a skeleton product for Plone that installs a skin selection with its own layers, but does not make use of the Resource Registries. - "SimplePloneStyle":/products/simpleplonestyle (which I wrote), another skeleton product that makes use of the Resource Registries but does not create a new skin selection. Those two products are not dead though. For instance, you may want to use SimplePloneStyle for starting a new project which has to register some stylesheets for all Plone skin selections. You also may want to base on MySkin a new product that mustn't do more than adding to Plone a skin selection with a few layers. This tutorial covers the use of the current version of DIYPloneStyle, which is version 2.1.1.

Installing the product First, download the last version of "DIYPloneStyle":/products/diyplonestyle/releases (this tutorial covers version 2.1.x), expand it, and follow the installation instructions that are in the 'README.txt' (it is a classic installation procedure for a Plone product). Your portal should now look like this:
Basic Example The code of the example resides in the files contained in the folders which name starts with 'diystyle_example' in the 'DIYPloneStyle/skins/' directory (on the filesystem). We can see that there aren't many files in those folders: * **Some images** They are kept in the folder 'diystyle_example_images'.
You can add to this folder the images that will override the ones shipped with Plone (mainly action and content type icons). It is better to keep them in a separate folder for having tidy folder listings in the 'portal_skins' tool. * **A custom base_properties.props file** From this file, you can learn how to replace the portal logo by another one, and how to simply change portal style properties.
This file is not used by the example, but is provided by the skeleton theme created by the "generator script":/documentation/tutorial/creating-custom-style/automated-setup for your convenience. note -- Customizing 'base_properties.props' is the easiest way to modify the style attributes of Plone UI elements, but it has its caveat as you will see "further in this tutorial":base-properties. * **A custom stylesheet (diystylesheet.css.dtml)** The most interesting thing about that stylesheet is probably that its name is not (and must not be) 'ploneCustom.css.dtml'. You will learn in a "further chapter":stylesheets of this tutorial how to register stylesheets with the new *portal_css* tool introduced in Plone 2.1 instead of using the old 'ploneCustom.css' implementation. Stylesheets and 'base_properties.props' are stored in the 'DIYPloneStyle/skins/diystyle_example_styles' folder. * **A set of empty stylesheets** Their names are 'public.css.dtml', 'base.css.dtml', 'generated.css.dtml', and 'portlets.css.dtml'. They are used to disable equivalent Plone stylesheets by overriding them with empty CSS files (see chapter about "skin layers":skin-layers). * **Some templates** As Alexander Limi states, it is ok to customize Plone templates as long as it is only for small structural changes. The templates that are customized in the example are kept in 'DIYPloneStyle/skins/diystyle_example_templates'.

1 **Uninstall the product** (with the Portal *Quick Installer*) before modifying anything. 1 **Rename the product** to something other than 'DIYPloneStyle' (1). This must be done on the filesystem, not in the ZMI (don't laugh, it happened). 1 **Rename** 'skins/diystyle_base_styles/diystylesheet.css.dtml' to something that suits better your product name.
This file is where you will add your own CSS rules. 1 **Rename all the folders** which name starts with 'diystyle_base' in the 'skins/' directory to something that suits better your product name (2). 1 **In config.py,** change the name of your skin selection by modifying the 'name' value of the first entry in 'SKINSELECTIONS' (3). If your product won't provide more than one skin selection, you can remove the 'layers' key from that entry (make sure 'SKINSELECTIONS' match folder names in your skins directory).
Change 'DEFAULTSKIN' to make it use the name of your skin selection.
In the 'STYLESHEETS' declaration, replace 'diystylesheet.css' by the name you chose for that template, omitting the '.dtml' suffix. 1 **In Extensions/Install.py,** edit the relevant lines in the import declarations (see '# CHANGE' comments). 1 **In tests/testStyleInstallation.py,** replace all occurences of 'DIYPloneStyle' by the name of your product (see '# CHANGE' comment). 1 **Edit README.txt,** give it another description, remove the usage and credits paragraphs, and replace author names and email addresses.
If you plan to distribute your work, please leave a note stating that it is based on DIYPloneStyle. 1 **Clear HISTORY.txt** from its DIYPloneStyle related content. 1 **Remove the basic example** - **Remove all the files** which name starts with 'diystyle_example' in the 'skins/' directory. - **In config.py,** in the 'SKINSELECTIONS' declaration, remove the lines declaring the 'DIY Style Example' skin. 1 **Remove the bin/ folder** as the script it contains only works on a clean, left unmolested version of DIYPloneStyle. **That's it!**
Now you can test the initial state of your visual theme by restarting the Zope server and installing it from the *Site Setup > Add/Remove Products page* (as manager, in the Plone interface). Your Plone Site should now look like this:
**Now have fun with your new project!** Troubleshooting -- This part of the tutorial is likely to be the one that will put you into some trouble.
See the "Troubleshooting":troubleshooting section of this tutorial if you feel that you are in a desperate situation.

(1) It is safer to work with a copy of the product so that it's easy to compare with the original version if you feel like in trouble. back

(2) Unless you configured it otherwise in the 'config.py' module, any folder located in the 'skins/' directory of your product will be registered as an *FSDirectoryView* with the portal skins tool. Because *FSDirectoryViews* must have a unique name/id in the skins tool, good practice is to include your product name into folder names to ensure these don't clash - particularly when using a name that might be commonly used. back

(3) In versions prior to 1.0.3, the name of the skin selection is setup using the 'SKINNAME' variable. back

You learned from the "first part of this chapter":getting-started how to
manually setup DIYPloneStyle for making it a ready to go skin skeleton
product.

There is a much faster way to get a clean product that can become a new style
for Plone, by making use of the included generator script.

In the DIYPloneStyle product folder on the filesystem, there is a 'bin/'
directory where you will find a python script called 'generator.py'.
This script can be used for applying all the manual modifications that are
listed in the previous part of this chapter.

Download and Expand DIYPloneStyle

* Place the expanded DIYPloneStyle product folder in the 'Products/'
directory of your Zope instance.

* **Uninstall DIYPloneStyle** if you already installed it
(in Plone, as manager, go to *Site Setup > Add/Remove Products*).

Run the script

On Unix/Linux/OSX

From a bash shell (from the Terminal), use a command which should look like
this one::

/path_to_zope_instance_home_folder/Products/DIYPloneStyle/bin/generator.py --productname MyOwnPloneSkin


On Windows

* Choose *run* from the Windows *Start menu* and type 'cmd'. Press *OK*

* Run the script with a command which should look like this one::

python c:\instance_home_folder\Products\DIYPloneStyle\bin\generator.py --productname MyOwnPloneSkin


On Unix like systems, you can call the script from any directory.<br />
On Windows you can't: your current working directory must be outside the
product.

I've heard about permission problems on Windows when using the script from a
subversion checkout of DIYPloneStyle.<br />
If you need to work with the latest *svn trunk* version of the product under
Windows, take the time to remove all its '.svn' folders before running the
script.

Start Building

You now have a fresh Plone skin product in the 'Products/' directory of
your Zope instance.<br />
All you have to do when you want it to be installable in Plone is to restart
the Zope server.

Note --
If you want to learn more about the possible script arguments, you can either
see the script output when called without args (or with the '--help' option)
or read its fairly easy to understand code.

To better understand how the *Skins Tool* and its layers traversal work, I invite you to read the paragraphs about "Using Layers Within a Skin":http://docs.neuroinf.de/PloneBook/ch7.rst#using-layers-within-a-skin and "Managing Skins with the portal_skins Tool":http://docs.neuroinf.de/PloneBook/ch7.rst#managing-skins-with-the-portal-skins-tool in the "chapter 7":http://docs.neuroinf.de/PloneBook/ch7.rst of the official "Plone Book":http://docs.neuroinf.de/PloneBook by Andy McKay. The links are unofficials but they are the only public ones I know that deliver a rendered HTML version of the book, and they are up-to-date. These paragraphs cover TTW Plone customization. Although it is a good way for learning the *Skins Tool* layers traversal mechanism, we know that working in the ZMI is not the best approach when it comes to building a full graphical environment for Plone. When building a skin product on the filesystem, concepts are the same:
The install function first creates a skin selection containing the layers of the skin it is based on, then adds the product specific layers to it. On the filesystem, the product specific layers are the folders that are located in the product 'skins/' directory (*). In practice, if your product is built for customizing a Plone site by adding a few stylesheets and replacing graphical UI elements (images like the logo and some icons), you won't need to have much more than one layer to add to your skin selection (**). But there are situations where it might be useful to have several layers, mainly for organizing skin elements into categories (images, customizations, stylesheets, etc). (*) Any folder located in the 'skins/' directory of your product will be registered as an FSDirectoryView with the portal *Skins Tool*, and then be added to your skin selection layers. Exceptions are folders which name starts with '.' or equals 'CVS' or '{arch}' (This is hardcoded in *Products.DIYPloneStyle.Extensions.utils.getSkinsFolderNames()*). (**) If DIYPloneStyle provides more than one skin layer (if its 'skins/' folder contains more than one folder), it's only for making easier the example removal part of the *Get Started* process.

Customizing 'base_properties.props' is the easiest way to modify the style attributes of Plone UI elements. But it has its caveat: due to the way the skins tool works, you must have all default Plone base properties in the file, even if you plan to customize only a small set of them. If you remove some of the properties from the file, Plone won't be able to access them anymore. All this doesn't make the 'base_properties.props' approach ideal for maintenance, upgrades and customization. That's one of the reasons why it will be gradually phased out in Plone (also for avoiding the use of DTML in CSS files).
I am not yet aware of how and when this will be implemented, so check for further updates of this paragraph. You can find more information about the Plone pre-defined properties in the file 'CMFPlone/skins/plone_styles/ploneCustom.css'. You may need to use your own properties in addition to the ones that are pre-defined in Plone. Instead of adding new properties to 'base_properties.props', it is probably better practice to create a new '.props' file in your skin layer and to register a stylesheet that uses it (instead of the base_properties one - see in the original 'DIYPloneStyle/skins/diystyle/renameThisFile.css.dtml' DTML code).

Registering new stylesheets Before the "ResourceRegistries":http://plone.org/products/resourceregistries was included in Plone, the only way to override the Plone default CSS rules was to customize the files 'base_properties.props' and 'ploneCustom.css'. Because of that, choosing what rules should override the plone ones had to be done by playing with the layers traversal in the *Skins Tool*, or by setting unelegant Zope *Access Rules*.
As we saw in the "previous chapter":base-properties, we still have to use 'base_properties.props' for defining our basic graphical chart. But now that we can register stylesheets with the CSS tool, 'ploneCustom.css' is kept for backward compatibility only. Another limit of Plone without the ResourceRegistries was that there was no possibility to put a condition on whether a stylesheet should be loaded or not. Stylesheet registration in DIYPloneStyle is set up in 'config.py', in the 'STYLESHEETS' declaration. 'STYLESHEETS' is a tuple of python dictionaries, one dictionary for each stylesheet to register with the *portal_css* tool. If you need to put a condition on a stylesheet, you have too add to its dictionary an 'expression' key. It's value is a TAL expression that works the same way as for actions in the *portal_actions* tool. You can learn more about the stylesheet attributes (dictionary keys) from the 'STYLESHEETS' inline comments. Customizing existing stylesheets DIYPloneStyle can be useful not only for registering new stylesheets: you can also define in the 'config.py' how you want to customize resources that are already registered in the registries. In the 'STYLESHEETS' declaration, simply add a dictionary with the same 'id' than the one of the resource that you want to customize, and add a key to the dictionary for each resource property that you want to modify. It can be handy for instance for disabling some Plone default resources in order to start a project from absolute no-style scratch or to put specific conditions on them to define different styles for public and registered modes. **Note:** All customizations will be automatically reverted when uninstalling the product. Practical example A very common use case is to define a skin for public anonymous access, and keep a basic plone style for members access. One easy way to do so is to put a condition on the product specific stylesheet(s), and disable basic plone resources under the same condition. In the 'config.py' file of your product, declare your stylesheets like these ones (in 'STYLESHEETS'):: STYLESHEETS = ( {'id': 'diystylesheet.css', 'media': 'screen', 'rendering': 'import', 'expression': 'python: member is None'}, {'id': 'base.css', 'expression': 'python: member is not None'}, {'id': 'public.css', 'expression': 'python: member is not None'}, {'id': 'portlets.css', 'expression': 'python: member is not None'}, {'id': 'generated.css', 'expression': 'python: member is not None'}, )

Use and development of your product Use valid name for your product -- A products which name starts with a digit won't be installable in Plone, even if you see it registered as a Zope product in the ZMI in Control_Panel > Products. Empty all caches (!!) -- If the changes you applied to the product don't show out the way you planned, or if some skin elements persist after you uninstalled the product, make sure that either the browser and the front-end proxy caches (apache, squid) are emptied, and reload the current page.
In Firefox, press shift while clicking the reload button. In IE, use the key combination <Ctrl-F5>.
Do not underestimate this possible issue, it covers at least **60% of the problems** that you may encounter with a skin product (based on DIYPloneStyle or not). Beware of any TTW customization -- Some of your product skin elements might have been customized from within the ZMI, and be overridden by their equivalent in the 'custom' skin layer. This one also covers a lot of the possible problems you might experience. Uninstall your product before renaming its elements -- If you forgot to do so before renaming stylesheets or javascripts, you can resolve conflicts from the *portal_css* and *portal_javascripts* tools in the ZMI.
If you didn't uninstall the product before renaming it or the skin selection, revert your changes on the filesystem, uninstall the product and rename the elements again. Check that the product is loaded in Zope -- From the ZMI, go to '/Control_Panel/Products/manage_main' and check that the product is listed and not marked as broken.
If it's not listed you should double check the product installation on the filesystem, making sure that the user who launches the Zope server has at least read access on it.
If it is marked as broken, you should check your error log and make sure that your business python code is valid (this should only happen if you added a broken Python class definition to your initial skeleton Plone style product). Make sure that the product is installable in Plone -- If your product is not listed or is marked as removed in *Site Setup > Add/Remove Products* or in the Quick Installer (*portal_quickinstaller* in the ZMI), it probably means that you have to debug the module 'Extensions/Install.py'. Use the provided testing framework -- DIYPloneStyle comes with basic unit tests.
Follow the links from the "Resources":resources chapter of this tutorial if you care about learning the Plone Unit Testing Framework. Use of the generator script Check that the script uses the right python interpreter -- Thank you Casper R. Nielsen for suggesting me to add this point.
With unix like systems, you can run the script by calling it directly, omitting the python command. If you get the error 'bad interpreter: No such file or directory' by calling the script that way, it's because the first line of the script refers to a file that does not exist.
To make it run without error, you can either:

• prefix the shell command by the python command

  $ python generator.py --productname CustomSkin

  or by the full path of the python interpreter. For instance:

  $ /usr/local/bin/python generator.py --productname CustomSkin

• edit the first line of the script to make it point to your python interpreter.

Check that the script is executable -- If you get the error 'Permission denied' by calling the script directly (under Linux/Unix), there are big chances that the executable bit was removed from the script file permissions. You can either run the script by prefixing the command by a python call (see previous paragraph) or use 'chmod' to restore file permissions:: $ chmod 0755 generator.py Check that you have the needed write permissions -- If you get a traceback that looks like this one,

Traceback (most recent call last):
  File "DIYPloneStyle/bin/generator.py", line 226, in ?
    generateDirectoryCopy( path, path.replace('DIYPloneStyle', productname) )
  File "DIYPloneStyle/bin/generator.py", line 182, in generateDirectoryCopy
    os.mkdir(dstDirectory)
OSError: [Errno 13] Permission denied: '/Users/david/plone-instance/Products/CustomStyle/'
    

it is probably because you don't have write permissions on the folder where DIYPloneStyle resides and where the new product will be created. Get Further support From the Plone community -- Before adding a comment to the manual, please post your question/issue on the "plone-users":/contact#users mailing list or try to get some support on the IRC "#plone":irc://irc.freenode.net/plone channel.
From the DIYPloneStyle product authors -- Feel free to contact DIYPloneStyle authors by sending them an email (email addresses appear in the product 'README.txt' file).

Download the latest release of DIYPloneStyle from "here":/products/diyplonestyle/releases. Essential References The following links will certainly answer most of the questions that could remain unanswered after reading this tutorial. ResourceRegistries -- The "Project Description":/products/resourceregistries or the product "README.txt":http://svn.plone.org/svn/plone/ResourceRegistries/trunk/README.txt give a good overview of its functionalities.
To learn more about the registries' API, you can install "DocFinderTab":http://zope.org/Members/shh/DocFinderTab. This product is recommended anyway as soon as you start learning the Zope/Plone API. "Customizing Plone - the Plone 2.0 approach":http://plone.org/events/conferences/1/archive/customizingplone by Alex Limi -- An overview of Plone 2.0 layout structure and philosophy, and of what you can do with CSS.
(This document can be used as a good demo of the full-screen mode in Opera that uses the 'projection' CSS media ,which displays Plone page sections as projection slides). TTW Customization These links can be useful for a better understanding of the *Skins Tool* machinery and how things are organized with regard to Plone User Interface elements. The Plone Book by Andy McKay -- Chapter 7, about "Customizing the Look and Feel of Plone":http://docs.neuroinf.de/PloneBook/ch7.rst is a must-read for People who need to understand better the *Skins Tool* machinery. "Where is what?":../where-is-what by Jet Wilda and John DeStefano -- A reference on what templates and CSS control the UI elements and where to find them in the ZMI (updated for Plone 3.0). "Plone Skin Dump":http://quintagroup.com/services/plone-development/products/skin-dump -- A Plone product developped by Quinta Group, which "allows to create Plone product based on some ZMI located skin folder (eg "custom") from portal_skins. So you can easy create Plone product with skin based on folder with customized styles and page templates". Plone Skin Dump supports stylesheets registration since version 0.3.0. Filesystem Development The "How-to section":/documentation/how-to/ of plone.org -- There are many good resources from the section **User Interface: Styles and styling, CSS**.
In particular the one about "Creating a Custom Skin":/documentation/how-to/creating-custom-skins by Ben Calder. "Best Practices for Plone development":/documentation/tutorial/best-practices by Joel Burton -- It will give you good advice if you plan to develop filesystem python code based products. The following references may seem off topic as they are mainly about developing content types, but they are valuable for learning how to build Python products for Plone. "MySite":http://www.neuroinf.de/LabTools/MySite by Raphael Ritz -- This tutorial/product for Plone newbies (and less newbies) covers many aspects of the product development on the filesystem. "RichDocument":/documentation/tutorial/richdocument by Martin Aspeli -- Although this tutorial/product is more about creating a new type of content for Plone, It has a short section covering the "use of the ResourceRegistries":/documentation/tutorial/richdocument/resourceregistries The Plone Book by Andy McKay -- There is also a chapter about "Writing a Product in Python":http://docs.neuroinf.de/PloneBook/ch12.rst. DIYPloneStyle ships *Unit Tests Included*.
Even if most of the following references describe the Zope and Plone Unit Testing Framework, it's really easy to adapt them to any product *for* Plone. "PloneTestCase":/products/plonetestcase/ -- PloneTestCase is a thin layer on top of the "ZopeTestCase":http://www.zope.org/Members/shh/ZopeTestCase package. It has been developed to simplify testing of Plone-based applications and products. "How to write unit tests for Plone":/development/info/writing-unit-tests -- This document shows how easy it is to write unit tests and describes how to set up your environment to invoke them. "the ZopeTestCase Wiki":http://www.zope.org/Members/shh/ZopeTestCaseWiki/FrontPage -- A comprehensive documentation about the Zope Unit Tesing Framework. Other Plone Skins Products Most of the graphical designs for Plone that can be found are not yet making use of the Resource Registries, but adapting the code should be easy now that you read this tutorial ;-) The "Products section":/products of plone.org -- Is a central repository for Plone Add-ons. It has a section dedicated to "visual themes":/products/by-category/themes that can be used as a source of useful examples on how to apply new designs to a Plone site. "ploneskins.org":http://www.ploneskins.org/ -- Is another repository for Plone skins. CSS Design "official W3C CSS documentation":http://www.w3.org/Style/CSS/ -- The official Cascading Style Sheets documentation delivered by the Word Wide Web Consortium. "CSS Zen Garden: The Beauty in CSS Design":http://www.csszengarden.com/ -- A demonstration of what can be accomplished visually through CSS-based design. "A List Apart":http://www.alistapart.com/ -- A web magazine that "explores the design, development, and meaning of web content, with a special focus on techniques and benefits of designing with web standards". Famous book author web sites -- Some authors of books about CSS design like "Eric Meyer":http://meyerweb.com, "Jeffrey Zeldman":http://www.zeldman.com/, "Dan Cederholm":http://www.simplebits.com/ and "Owen Briggs":http://www.thenoodleincident.com have their own web site that are good places for finding documentation, examples and recipes. Mozilla/Firefox Tools and Extensions The following tools are your best friends when you need to inspect the CSS attributes of Plone page elements or find out what id or class you want to override in your stylesheets. "DOM Inspector":http://www.mozilla.org/projects/inspector/ -- This Mozilla tool can be used to inspect and edit the live DOM of any web document. "Web Developer":http://chrispederick.com/work/firefox/webdeveloper/ -- Adds a menu and a toolbar with various web developer tools. "Aardvark":http://www.karmatics.com/aardvark/ -- This extension displays on a Web page the attributes (like ID or class name) of a selected element. "EditCSS":http://addons.mozilla.org/extensions/moreinfo.php?id=179 -- Stylesheet modifier in the Sidebar. "ColorZilla":http://www.iosart.com/firefox/colorzilla/index.html -- Advanced Eyedropper, ColorPicker, Page Zoomer and other colorful goodies. It assists web developers and graphic designers with color related tasks - both basic and advanced. "View formatted source (format source extension)":https://addons.mozilla.org/en-US/firefox/addon/697 -- Displays formatted and color-coded source and optional CSS information for each element. You can see exactly which CSS rules match for an element. The rules are displayed including file name and line number. The topmost element is that with the highest priority. You can fold/unfold/hilite block elements (table, tr, td, div, span,...). Really cool feature: select a block level element of interest directly in the page and view it's source! To help you to quickly analyze the source code you can view images directly from the source and add comments to folded block elements. The code view is based on the rendered document, so you will also see dynamically (by Javascript) created and modified html elements! Works also with frames and selected text. "View Rendered Source Chart":https://addons.mozilla.org/en-US/firefox/addon/655 -- Creates a Colorful Chart of a Webpage's Rendered Source Code.
Displays Dynamically Generated HTML and Static HTML Together.
Removes JavaScript Code, Displays JavaScript Output.
Excellent as a Visual Aid in Learning Environments.

Chinese --
"Chinese translation":http://www.czug.org/plone/tutorial/diyplonestyle

Japanese --
"Japanese translation":http://nagosui.org:8080/Nagosui/plone-visual/DIYPloneStyle-nyusukese/creating-custom-style/

German --
"German translation":http://amantke.de/index.php?/content/view/37/23/