1. Where is What on the Page

How can you track down the files related to an individual page element?

At the time of writing, there's no in-built magic wand to point at an element on a Plone web page and find out exactly what templates and code are involved in its creation. There may be soon though, and the adventurous might like to explore Weblion's Gloworm tool.

If you're not ready for an adventure yet, then there are a number of good tutorials available with diagrams and guides to where is what.

Understanding how the CSS maps to the Page

The Weblion project has an excellent Wiki page to help you with this

https://weblion.psu.edu/trac/weblion/wiki/PloneThreeWhereIsWhat

Firebug (an add-on for Firefox), of course, is an essential tool for inspecting code and CSS for a page.

http://www.getfirebug.com/

Page Elements

Page elements are consistently named in Plone, so once you know the name of an area of the page, you're well on the way to tracking down the relevant files

you can find a visual key to page elements in the Elements section of this manual
you'll also find an excellent overview in the What Controls What You See tutorial on Plone.org
and a mapping of the viewlet and portlet managers on the Weblion wiki

2. Where's my Zope Instance?

Where your Zope instance lives depends on the Plone installer or installation process you used.

Plone Version 3.1.2 onwards

Buildout: In a Buildout based installation, you don't need to worry much about your Zope instance. If you really want to investigate you'll find the actual instance in [your buildout]/parts/instance. However most of the key bits (your Plone products, 3^rd party products, your Data.fs) don't actually live there. They are all assembled together from various parts of your file system by the zope.conf file which is generated when you run buildout.

Plone Version 3.1.1 or lower

Plone Installer: The Plone installers (apart from the Plone 3.1 Universal Installer) usually drop a Zope instance directory alongside the Zope and Python software directories. So, for example, a standard Windows installation, locates your Zope instance at c:\Program Files\Plone 3\Data. On a Mac, it will be called 'instance' and will probably live in a Plone folder in your applications folder.; The Plone 3.1 Universal Installer, however, will have given you a buildout based installation.
Plone Product Package: If you've installed Zope yourself, you'll have been prompted to create a Zope instance, so you should have a good idea of where that is on your system.

3. Where's my Products Directory?

How to track down your products directory. It'll differ according to the Plone installer or installation process you used.

The products directory is where old-style 2.5 products live. To track this down, you'll need to know where your Zope Instance or your Buildout is first.

For theming purposes, the main reason you'll need to investigate the products directory is to locate Plone Default theme files - as parts of Plone are still in old-style product form.

Plone version 3.1.2 onwards

In a Buildout based installation, you'll find products in various directories.

Core Plone products (such as CMFPlone)

For these, have a look in

[your buildout]/parts/plone.

Products you download yourself

These should go in

[your buildout]/products.

If you find you haven't got a products directory there, then it is OK to create one yourself.

Products you asked buildout to download

If you asked buildout to go and fetch some old-style products, then these will have been dropped into

[your buildout]/parts/[directory name].

(Buildout will also have created the directory and will have called it something like "productdistros").

Plone version 3.1.1 or lower

Plone Installer and Plone Product Package

It should be easy to locate all your products (those belonging to the core Plone installation and those you've downloaded yourself) in

[your zope instance]/products

However, if you used the Plone 3.1 Universal Installer your installation will be buildout based.

4. Where's my Egg Location?

It is easy enough for Zope to find your eggs, harder for humans.

Plone version 3.1.2 onwards

Core Plone Default Products

For core products used in the Plone Default Theme, buildout has an eggs directory

[your buildout]/eggs

which is where eggs are automatically dropped when Plone is installed.

Your own theme product

Because your own theme product will be under development, this will go in a separate place in your buildout

[your buildout]/[zinstance|zeocluster|]/src

(note that to share eggs between buildouts you can specify a different location for this in a buildout defaults file, check the buildout tutorial on plone.org for more information).

Using Omelette to get at your eggs quickly

It is a bit of a drag navigating your way around all the eggs used by Plone. David Glick's Omelette recipe creates a unified directory structure of all namespace packages, symlinking to the actual contents, via buildout. Full instructions and documentation on this can be found here:

http://pypi.python.org/pypi/collective.recipe.omelette

Once you've re-run buildout with the omelette recipe, you'll find that you have a new section here:

[your buildout]/[zinstance|zeocluster]/parts/omelette

and eggs such as plone.app.layout can be found in:

[your buildout]/[zinstance|zeocluster]/parts/omelette/plone/app/layout

Plone version 3.1.1 or lower

Plone Installer

If you have installed Plone with an installer, then the eggs will probably have been dropped into

[your plone installation]/Python/Lib/site-packages.

However, if you've used the Plone 3.1 universal installer, then you will have a buildout based installation.

The Plone Product Package

If you used the product package (i.e. installed from source), then you may well find them in

[your Zope instance]/lib/python.

5. Location of files in your own Theme Product

The egg created for you by the plone3_theme paster template should have a file system layout very similar to this diagram.

If the diagram doesn't help, then consult the next few pages where sections of the diagram are combined with a text explanation.

your theme egg

6. Files for the Skin

These files and directories will be relevant when working on the Skin part of your theme.

/skins/[your theme namespace].[your theme name]_custom_templates | custom_images | styles: These directories will form your skin layers. Your templates, images, and stylesheets can go here. If you asked it to, the plone3_theme paster template will have provided blank style sheets to override the Plone Default ones.
/skins.zcml: When your Zope instance starts up, this turns your directories into skin layers
/profiles/default/skins.xml | cssregistry.xml | jsregistry.xml: When your theme is installed in your Plone site, this sets up the hierarchy of skin layers, and registers your style sheets and JavaScript with the registries

7. Files for Components

These files and directories will be relevant when working on the Components part of your theme.

/browser/viewlet.py | viewlet.pt: An example viewlet component
/browser/interfaces.py: This is used to create your theme interface (and any other interfaces you might need)
/profiles/default/viewlets.xml: Use this file to order your viewlets within viewlet managers
/browser/configure.zcml: Use this file to wire up your components
/browser/templates | styles: These directories can be used for templates, styles, and images. You will need to register these as directories as resources in configure.zcml.

8. Files for Configuration

These files and directories will be relevant when working on the Configuration part of your theme.

/profiles/default/: This directory holds the xml for Generic Setup. The plone3_theme paster template will have provided you with some ready-made files - for setting up your skin layers, registering your style sheets and JavaScripts, and ordering your viewlets.
/profiles.zcml: When your Zope instance starts up, this file makes the profile available for Generic Setup to use.

9. Files for Installing your Egg

These are the files and directories required to install your egg in your python path and make it available to Zope on start up.

your theme egg - the files used for installing the egg

10. Files for Installing your Theme

These are the files used when you install your theme product using Site Setup > Add / Remove Products or Zope Management Interface > portal_quickinstaller

/profiles/default/: Generic Setup will install your theme profile when your theme is installed. import_steps.xml points to a 'handler' for installation steps which aren't yet part of Generic Setup or can't be expressed as XML.
/setuphandlers.py: This contains the handler for non-Generic Setup installation steps.