Selecting a theme

To apply an existing theme, simply click the Activate button underneath the theme preview. The currently active theme will be highlighted in yellow. If you deactivate the currently active theme, no Diazo theme will be applied, i.e. "vanilla" Plone theming will apply.

Note: The Theming control panel is never theemd, ensuring that you can always deactivate an errant theme that could render the control panel unusable. Thus, you may not see any difference immediately after enabling a theme. Simply navigate to another page in the Plone site, though, and you should see the theme applied.

Creating a new theme

New themes can be created in one of two ways:

• Click the New theme button at the top of the Themes tab in the Theming control panel and enter a title and description in the form that appears. A bare-bones theme will be created, and you will be taken to the Modify theme screen (see below), where you can edit or create theme and rules files.
• Click the Copy button underneath any existing theme and enter a title and description in the form that appears. A new theme will be created as a copy of the existing theme, and you will be taken to the Modify theme (see below), where you can edit or create theme and rules files.

Uploading an existing theme

Themes can be distributed as Zip files, containing the HTML mockup and rules file. To download an existing theme, click the Download button underneath the theme on the Themes tab of the Theming control panel.

To upload such a Zip file into another site, use the Upload Zip file button on the Themes tab of the Theming control panel. You can choose whether or not to replace any existing theme with the same name (based on the name of the top-level directory contained within the Zip file).

You can also upload a Zip file of a static HTML mockup that does not contain a rules file, such as a design provided by a Plone-agnostic web designer.

In this case, a basic rules.xml file will be added for you to start building up a theme from using the Modify theme screen (see below). The generated rules file will assume the main HTML mockup file is called index.html, but you can change this in rules.xml.

Once you have successfully uploaded a theme Zip file, you will be taken to the Modify theme screen (see below), where you can edit or create theme files.

Hint: If you get an error message like "The uploaded file does not contain a valid theme archive", this usually means that you have uploaded a Zip file that contains multiple files and folders, rather than a single top level folder with all the theme resources in it. This could happen if you compressed a theme or HTML mockup by adding its files and folders directly a Zip archive, rather than compressing the directory in which they were found. To fix this, simply unzip the archive on your computer into a new directory, move up a level, and compress this directory on its own into a new Zip file, which you can then upload.

Modifying the theme

You can modify a theme by clicking Modify theme underneath a theme in the Themes tab of the Theming control panel. This screen is also launched automatically when you create or upload a new theme.

Note: Only themes created or uploaded through the Theming control panel can be modified through Plone. Themes installed by third-party add-ons or distributed on the filesystem cannot, although changes made on the filesystem will be reflected immediately if Zope is running in debug mode. To modify a filesystem theme, you can copy it to a new in-Plone theme by clicking the Copy button underneath the theme in the Theming control panel.

The Modify theme screen initially shows a file manager, with a file tree on the left and an editor on the right. Click on a file in the file tree to open an editor or preview: HTML, CSS, JavaScript and other text files can be edited directly through the editor. Other files (e.g. images) will be rendered as a preview.

Note: The advanced editor with syntax highlighting is not available in Microsoft Internet Explorer.

Click New folder to create a new folder. You can also right-click on a folder in the file tree to bring up this action.

Click New file to create a new text file. You can also right-click on a folder in the file tree to bring up this action.

Click Upload file to upload a file from your computer. You can also right- click on a folder in the file tree to bring up this action.

Click Preview theme to preview the theme as it will be applied with the mockup and rules as currently saved. The preview is navigable, but forms and certain advanced features will not work.

To save the file currently being edited, click the Save file button, or use the keyboard shortcut Ctrl+S (Windows/Linux) or Cmd+S (Mac).

To rename or delete a file or folder, right-click on it in the file tree and select the appropriate action.

The theme inspector

The theme inspector provides an advanced interface for discovering and building up the rules of a Diazo theme. It can be launched by clicking the Show inspectors button on the Modify theme screen for in-Plone themes, or by clicking the Inspect theme button underneath a filesystem theme on the Themes tab of the Theming control panel.

The theme inspector consists of two panels:

• The HTML mockup. If there are several HTML files in the theme, you can switch between them using the drop-down list underneath the HTML mockup panel.
• The Unthemed content. This shows Plone without any theme applied.

Either panel can be maximised by clicking the arrows icon at the top right of either.

The HTML mockups and Unthemed content panels can be switch to source view, showing their underlying HTML markup, by clicking the tags icon at the top right of either.

As you hover over elements in the HTML mockup or Unthemed content panels, you will see:

• An outline showing the element under the cursor.
• A CSS or XPath selector in the status bar at the bottom if the panel which would uniquely identify this element in a Diazo rule.

Click on an element or press Enter whilst hovering oveer an element to select it. The most recently selected element in each panel is shown in the bottom right of the relevant status bar.

Press Esc whilst hovering over an element to select its parent. This is useful when trying to select "invisible" container elements. Press Enter to save this selection.

The contents of the HTML mockup or (more commonly) Unthemed content panels can be navigated, for example to get to a content page that requires specific theme rules, by disabling the inspector. Use the toggle switches at the bottom right of the relevant panel to enable or disable the selector.

The rule builder

Click the Build rule button near the top of the Modify theme or Inspect theme screen to launch an interactive rule building wizard. You will be asked which type of rule to build, and then prompted to select the relevant elements in the HTML mockup and/or Unthemed content panels as required. By default, this will use any saved selections, unless you untick the Use selected elements box on the first page if the wizard.

Once the wizard completes, you will be shown the generated rule. You can edit this if you wish. If you click Insert, the newly generated rule will be inserted into the rules.xml editor at or near your current cursor position. You can move it around or edit it further as you wish.

Click Preview theme to preview the theme in a new tab or window. Don't forget to save the rules.xml file if you have made changes.

Note: In readonly mode, you can build rules and inspect the HTML mockup and theme, but not change the rules.xml file. In this case, the Insert button of the rule builder (see below) will not be available either.

Note: The ability to insert rules from the Build rule wizard are not available in Microsoft Internet Explorer, although you will be given the option to copy the rule to the clipboard when using this browser.

Advanced settings

The Theming control panel also contains a tab named Advanced settings. Here be dragons.

The Advanced setings tab is divided into two areas. The first, Theme details, contains the underlying settings that are modified when a theme is applied from the Themes control panel. These are:

• Whether or not Diazo themes are enabled at all.
• The path to the rules file, conventionally called rules.xml, either relative to the Plone site root or as an absolute path to an external server.
• The prefix to apply when turning relative paths in themes (e.g. references to images in an <img /> tag's src attribute) into absolute ones at rendering time.
• The HTML DOCTYPE to apply to the rendered output, if different to the default XHTML 1.0 Transitional.
• Whether or not to allow theme resources (likes rules.xml) to be read from the network. Disabling this gives a modest performance boost.
• A list of host names for which a theme is never applied. Most commonly, this contains 127.0.0.1, allowing you to view an unthemed site through 127.0.0.1:8080 and a themed one at localhost:8080 during development, say.
• A list of theme parameters and the TALES expressions to generate them (see below).

The second, Theme base, controls the presentation of the unthemed content, and apply even if no Diazo theme is being applied. These are the settings that used to be found in the Themes control panel in previous versions of Plone.

Deploying and testing themes

To build and test a theme, you must first create a static HTML mockup of the look and feel you want, and then build a rules file to describe how Plone's content maps to the placeholders in this mockup.

The mockup can be created anywhere using whatever tool you feel most comfortable building web pages in. To simplify integration with Plone, you are recommended to make sure it uses relative links for resources like CSS, JavaScript and image files, so that it will render properly when opened in a web browser from a local file. Plone will convert these relative links to the appropriate absolute paths automatically, ensuring the theme works no matter which URL the user is viewing when the theme is applied to a Plone site.

There are several ways to get the theme into Plone:

1. On the filesystem

If you used an installer or a standard "buildout" to set up your Plone site, you should have a directory called resources in the root of your Plone installation (this is created using the resources option to the buildout recipe plone.recipe.zope2instance. See pypi.python.org/pypi/plone.recipe.zope2instance for more details.)

You can find (or create) a theme directory inside this directory, which is used to contain themes. Each theme needs its own directory with a unique name. Create one (e.g. resources/theme/mytheme) and put your HTML files and any references resources inside this directory. You can use subdirectories if you wish, but you are recommended to keep the basic theme HTML files at the top of the theme directory.

You will also need a rules file called rules.xml inside this directory. If you haven't got one yet, start with an empty one:

<?xml version="1.0" encoding="UTF-8"?>
<rules
    xmlns="namespaces.plone.org/diazo"
    xmlns:css="namespaces.plone.org/diazo/css"
    xmlns:xsl="www.w3.org/1999/XSL/Transform">`

    <theme class="theme.html" />
    <replace css:content-children="#content" css:theme-children="#main" />

</rules>

Provided you are running Zope in debug mode (e.g. you start it up with bin/instance fg), changes to the theme and rules should take effect immediately. You can preview or enable the theme through the Themes control panel, and then iteratively modify the rules.xml file or the theme mockup as you wish.

2. Through the web

If you prefer (or do not have filesystem access), you can create themes entirely through the Plone control panel, either by duplicating an existing theme, or starting from scratch with a near-empty theme.

See the instructions on using the control panel above for more details.

Once a theme has been created, you can modify it through the Theming control panel. See above for more details.

3. As a zip file

Themes can be downloaded from Plone as Zip files, which can then be uploaded into other sites.

See the instructions on using the control panel above for more details.

In fact, you can create valid theme zip archives by compressing a theme directory on the filesystem using a standard compression tool such as 7-Zip or Winzip (for Windows) or the built-in Compress action in the Mac OS X Finder. Just make sure you compress exactly one folder that contains all the theme files and the rules.xml file. (Do not compress the contents of the folder directly: when unpacked, the zip file should produce exactly one folder which in turn contains all the relevant files).

4. In a Python package (programmers only)

If you are creating a Python package containing Plone customisations that you intend to install into your site, you can let it register a theme for installation into the site.

To do this, place a directory called e.g. theme at the top of the package, next to the Zope configure.zcml file, and add a <plone:static /> declaration to the configure.zcml file:

<configure
    xmlns:plone="namespaces.plone.org/plone"
    xmlns="namespaces.zope.org/zope">

    ...

    <plone:static name="mytheme" directory="theme" type="theme" />

    ...

</configure>

Notice the declaration of the plone namespace at the root <configure /> element. Place the theme files and the rules.xml file into the theme directory.

If your package has a GenericSetup profile, you can automatically enable the theme upon installation of this profile by adding a theme.xml file in the profiles/default directory, containing e.g.:

<theme>
    <name>mytheme</name>
    <enabled>true</enabled>
</theme>

The manifest file

It is possible to give additional information about a theme by placing a file called manifest.cfg next to the rules.xml file at the top of a theme directory.

This file may look like this:

[theme]
title = My theme
description = A test theme

As shown here, the manifest file can be used to provide a more user friendly title and a longer description for the theme, for use in the control panel. Only the [theme] header is required - all other keys are optional.

You can also set:

rules = example.org/myrules.xml

to use a different rule file name than rules.xml (you should provide a URL or relative path).

To change the absolute path prefix (see Advanced settings), use:

prefix = /some/prefix

To emply a DOCTYPE in the themed content other than XHTML 1.0 Transitional, add e.g.:

doctype = html

To provide a user-friendly preview of your theme in the Theming control panel, add:

preview = preview.png

Here, preview.png is an image file relative to the location of the manifest.cfg file.

Extensions to the Diazo theming engine can add support for additional blocks of configurable parameters.

Rules syntax

The following is a short summary of the Diazo rules syntax. See diazo.org for more details and further examples.

<rules>
    ...
</rules>

<rules
    xmlns="namespaces.plone.org/diazo"
    xmlns:css="namespaces.plone.org/diazo/css"
    xmlns:xsl="www.w3.org/1999/XSL/Transform">
    ...
</rules>

<theme class="theme.html" />
<theme class="news.html" if-path="/news" />
<notheme if="$host = 'admin.example.org'" />

<replace
    css:content="#content"
    css:theme="#main"
    />

<before
    css:content-children="#portal-column-one"
    css:theme-children="#portlets"
    />

<after
    css:content-children="#portal-column-two"
    css:theme-children="#portlets"
    />

<drop css:content=".documentByLine" />
<drop theme="/head/link" />
<drop css:theme="#content *" attributes="onclick onmouseup" />

<strip css:content="#parent-fieldname-text" />

<merge
    attributes="class"
    css:content="body"
    css:theme="body"
    />

<copy
    attributes="class"
    css:content="#content"
    css:theme="#main"
    />

<after css:theme="head">
    <style type="text/css">
        body > h1 { color: red; }
    </style>
</after>

<replace css:content="#portal-searchbox input.searchButton">
    <button type="submit">
        <img src="/img/spacer.gif"> 
In addition to including static HTML in this manner, you can use XSLT
instructions that operate on the content. You can even use css: selectors
directly in the XSLT.:
<replace css:theme="#details">
    <dl id="details">
        <xsl:for-each css:select="table#details > tr">
            <dt><xsl:copy-of select="td[1]/text()"/></dt>
            <dd><xsl:copy-of select="td[2]/node()"/></dd>
        </xsl:for-each>
    </dl>
</replace>

Rules may operate on content that is fetched from somewhere other than the
current page being rendered by Plone, by using the href attribute to specify
a path of a resource relative to the root of the Plone site:
<after
    css:theme-children="#leftnav"
    css:content=".navitem"
    class="/@@extra-nav"
    />