This package offers a simple way to develop and deploy Plone themes using the Diazo theming engine.
If you are not familiar with Diazo, check out the `Diazo documentation <http://diazo.org>`_.
It comes with a user guide, reproduced below, available through the theming
control panel.
plone.app.theming manual
========================
This guide provides an overview of Diazo theming in Plone versions 4.3 and higher.
.. contents:: Contents
:local:
Introduction
------------
In `Plone <http://plone.org>`_ versions 4.3 and higher you
can edit your website theme through web browser in Plone's site setup control panel.
Only HTML, CSS and little XML knowledge needed as the prerequisitements.
This guide explains how to use this feature of Plone.
See `introduction video to plone.app.theming <https://vimeo.com/42564510>`_.
What is a Diazo theme?
----------------------
A "theme" makes a website (in this case, one powered by Plone) take on a
particular look and feel.
*Diazo* (formerly known as XDV) is a technology that can be used to theme
websites. It is not specific to Plone per se, but has been created by the Plone
community and, as of Plone 4.3, provides the default way to apply a theme to a
Plone site. You can learn more about Diazo at http://diazo.org.
Diazo themes may be a little different to themes you have created in other
systems, and indeed to themes you may have created for earlier versions of
Plone. A Diazo theme is really about transforming some content - in this case
the output from "vanilla" Plone - into a different set of HTML markup by
applying a set of rules to combine a static HTML mock-up of the end result you
want with the dynamic content coming from Plone.
In comparison, the previous way to theme a Plone site (like the way many other
content management systems are themed) relies on selectively overriding the
templates and scripts that Plone uses to build a page with custom versions
that produce different HTML markup. The latter approach can be more powerful,
certainly, but also requires much deeper knowledge of Plone's internals and
command of server-side technologies such as Zope Page Templates and even Python.
Diazo themes, by contrast, are easy to understand for web designers and non-
developers alike.
A Diazo theme consists of three elements:
1. One or more HTML mockups, also referred to as *theme* files, that represent
the desired look and feel.
These will contain placeholders for content that is to be provided by the
Plone content management system. Mockups usually reference CSS, JavaScript
and image files by relative path. The most common way to create a theme is to
use desktop software like Dreamweaver or a text editor to create the relevant
markup, styles and scripts, and test the theme locally in a web browser.
2. The *content* that is being themed. In this case, that is the output from
Plone.
3. A *rules file*, which defines how the placeholders in the theme (i.e. the
HTML mockup) should be replaced by relevant markup in the content.
The rules file uses XML syntax (similar to HTML). Here is a very simple
example::
<?xml version="1.0" encoding="UTF-8"?>
<rules
xmlns="http://namespaces.plone.org/diazo"
xmlns:css="http://namespaces.plone.org/diazo/css"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">`
<theme href="theme.html" />
<replace css:content-children="#content" css:theme-children="#main" />
</rules>
Here, we are replacing the contents (child nodes) of a placeholder element
with HTML id ``main`` in the theme file (``theme.html``, found in the same
directory as the ``rules.xml`` file, as referenced by the ``<theme />`` rule)
with the contents (children) of the element with the HTML id ``content`` in
the markup generated by Plone.
When this theme is applied, the result will look very much like the static
HTML file ``theme.html`` (and its referenced CSS, JavaScript and image
files), except the placeholder that is identified by the node in the theme
with id ``main`` will be filled by Plone's main content area.
Plone ships with an example theme called, appropriately, *Example theme*, which
uses the venerable `Twitter Bootstrap <http://twitter.github.com/bootstrap/>`_
to build a simple yet functional theme exposing most of Plone's core
functionality. You are advised to study it - in particular the ``rules.xml``
file - to learn more about how Diazo themes work.
Using the control panel
-----------------------
After installation of the *Diazo theme support* package in a Plone site, the
*Theming* control panel will appear in Plone's *Site setup*.
The main tab of this control panel, *Themes*, will show all available themes,
with buttons to activate/deactivate, modify, copy or delete each, as well as
buttons to create new themes or bring up this help text.
Click on a theme preview image to open a preview of that theme in a new tab
or window. The preview is navigable, but form submissions and some advanced
features will not work.
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 settings* 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
``http://127.0.0.1:8080`` and a themed one at ``http://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.
Reference
---------
The remainder of this guide contains reference materials useful for theme
builders.
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
http://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="http://namespaces.plone.org/diazo"
xmlns:css="http://namespaces.plone.org/diazo/css"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">`
<theme href="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="http://namespaces.plone.org/plone"
xmlns="http://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
rules = http://example.org/myrules.xml
prefix = /some/prefix
doctype = <!DOCTYPE html>
preview = preview.png
enabled-bundles = mybundle
disabled-bundles = plone
development-css = /++theme++barceloneta/css/barceloneta.css
production-css = /++theme++barceloneta/css/barceloneta.min.css
development-js = /++theme++barceloneta/barceloneta.js
production-js = /++theme++barceloneta/barceloneta.min.js
tinymce-content-css = /++theme++barceloneta/barceloneta.min.css
tinymce-styles-css = /++theme++barceloneta/custom-styles.css
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.
Manifest settings:
rules
to use a different rule file name than ``rules.xml`` (you should provide a URL
or relative path).
prefix
To change the absolute path prefix (see *Advanced settings*),
use::
prefix = /some/prefix
doctype
To employ a ``DOCTYPE`` in the themed content other than ``XHTML 1.0
Transitional``, add e.g.::
doctype = <!DOCTYPE html>
preview
To provide a user-friendly preview of your theme in the *Theming* control panel.
Here, ``preview.png`` is an image file relative to the location of the
``manifest.cfg`` file::
preview = preview.png
enabled-bundles
Bundles that will automatically be enabled when a theme is activated
disabled-bundles
Bundles that will automatically be disabled when a theme is activated
development-css
CSS to automatically include when in development mode and theme is active
development-js
JavaScript file to automatically include when in development mode when
theme is active
production-css
CSS to automatically include when theme is active and in production mode
production-js
JavaScript to automatically include when theme is active and in production mode
tinymce-content-css
CSS file tinymce should load to apply styles to content inside the editor
tinymce-styles-css
CSS file tinymce should load to provide additionally automatically detected
drop-down styles in the editor
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
http://diazo.org for more details and further examples.
Selectors
+++++++++
Each rule is represented by an XML tag that operates on one or more HTML
elements in the content and/or theme. The elements to operate on are indicated
using attributes of the rules known as *selectors*.
The easiest way to select elements is to use a CSS expression selector, such as
``css:content="#content"`` or ``css:theme="#main .content"``. Any valid CSS 3
expression (including pseudo-selectors like ``:first-child`` may be used.
The standard selectors, ``css:theme`` and ``css:content``, operate on the
element(s) that are matched. If you want to operate on the children of the
matched element instead, use ``css:theme-children="..."`` or
``css:content-children="..."`` instead.
If you cannot construct a suitable CSS 3 expression, you can use XPath
expressions such as ``content="/head/link"`` or ``theme="//div[@id='main']"``
(note the lack of a ``css:`` prefix when using XPath expressions). The two
approaches are equivalent, and you can mix and match freely, but you cannot
have e.g. both a ``css:theme`` and a ``theme`` attribute on a single rule. To
operate on children of a node selected with an XPath expression, use
``theme-children="..."`` or ``content-children="..."``.
You can learn more about XPath at http://www.w3schools.com/xpath/default.asp.
Conditions
++++++++++
By default, every rule is executed, though rules that do not match any elements
will of course do nothing. You can make a rule, set of rules or theme reference
(see below) conditional upon an element appearing in the content by adding an
attribute to the rule like ``css:if-content="#some-element"`` (to use an XPath
expression instead, drop the ``css:`` prefix). If no elements match the
expression, the rule is ignored.
**Tip:** if a ``<replace />`` rule matches an element in the theme but not in
the content, the theme node will be dropped (replaced with nothing). If you do
not want this behavior and you are unsure if the content will contain the
relevant element(s), you can use ``css:if-content`` conditional rule. Since
this is a common scenario, there is a shortcut: ``css:if-content=""`` means
"use the expression from the ``css:content`` attribute".
Similarly, you can construct a condition based on the path of the current
request by using an attribute like ``if-path="/news"`` (note that there is no
``css:if-path`` ). If the path starts with a slash, it will match from the root
of the Plone site. If it ends with a slash, it will match to the end of the URL.
You can set an absolute path by using a leading and a trailing slash.
Finally, you can use arbitrary XPath expressions against any defined variable
using an attribute like ``if="$host = 'localhost'"`` . By default, the variables
``url`` , ``scheme`` , ``host`` and ``base`` are available, representing the
current URL. Themes may define additional variables in their manifests.
Available rules
+++++++++++++++
The various rule types are summarized below.
``rules``
#########
::
<rules>
...
</rules>
Wraps a set of rules. Must be used as the root element of the rules file. Nested
``<rules />`` can be used with a *condition* to apply a single condition to a
set of rules.
When used as the root element of the rules file, the various XML namespaces must
be declared::
<rules
xmlns="http://namespaces.plone.org/diazo"
xmlns:css="http://namespaces.plone.org/diazo/css"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
...
</rules>
``theme`` and ``notheme``
#########################
::
<theme href="theme.html" />
<theme href="news.html" if-path="/news" />
<notheme if="$host = 'admin.example.org'" />
Choose the theme file to be used. The ``href`` is a path relative to the rules
file. If multiple ``<theme />`` elements are present, at most one may be given
without a condition. The first theme with a condition that is true will be used,
with the unconditional theme, if any, used as a fallback.
``<notheme />`` can be used to specify a condition under which no theme
should be used. ``<notheme />`` takes precedence over ``<theme />``.
**Tip:** To ensure you do not accidentally style non-Plone pages, add a
condition like ``css:if-content="#visual-portal-wrapper"`` to the last theme
listed, and do not have any unconditional themes.
``replace``
###########
::
<replace
css:content="#content"
css:theme="#main"
/>
Replaces the matched element(s) in the theme with the matched element(s) from
the content.
``before`` and ``after``
########################
::
<before
css:content-children="#portal-column-one"
css:theme-children="#portlets"
/>
<after
css:content-children="#portal-column-two"
css:theme-children="#portlets"
/>
Inserts the matched element(s) from the content before or after the matched
element(s) in the theme. By using ``theme-children`` , you can insert the
matched content element(s) as the first (prepend) or last (append) element(s)
inside the matched theme element(s).
``drop`` and ``strip``
######################
::
<drop css:content=".documentByLine" />
<drop theme="/head/link" />
<drop css:theme="#content *" attributes="onclick onmouseup" />
<strip css:content="#parent-fieldname-text" />
Remove element(s) from the theme or content. Note that unlike most other rules,
a ``<drop />`` or ``<strip />`` rule can operate on the ``theme`` or
``content`` , but not both. ``<drop />`` removes the matched element(s) and
any children, whereas ``<strip />`` removes the matched element(s), but leaves
any children in place.
``<drop />`` may be given a whitespace-separated list of ``attributes`` to
drop. In this case, the matched element(s) themselves will not be removed. Use
``attributes="*"`` to drop all attributes.
``merge`` and ``copy``
######################
::
<merge
attributes="class"
css:content="body"
css:theme="body"
/>
<copy
attributes="class"
css:content="#content"
css:theme="#main"
/>
These rules operate on attributes. ``<merge />`` will add the contents of the
named attribute(s) in the theme to the value(s) of any existing attributes with
the same name(s) in the content, separated by whitespace. It is mainly used to
merge CSS classes.
``<copy />`` will copy attributes from the matched element(s) in the content
to the matched element(s) in the theme, fully replacing any attributes with
the same name that may already be in the theme.
The ``attributes`` attribute can contain a whitespace-separated list of
attributes, or the special value ``*`` to operate on all attributes of the
matched element.
Advanced modification
++++++++++++++++++++++
Instead of selecting markup to insert into the theme from the content, you can
place markup directly into the rules file, as child nodes of the relevant rule
element::
<after css:theme="head">
<style type="text/css">
body > h1 { color: red; }
</style>
</after>
This also works on the content, allowing you to modify it on the fly before any
rules are applied::
<replace css:content="#portal-searchbox input.searchButton">
<button type="submit">
<img src="images/search.png" alt="Search" />
</button>
</replace>
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::
<!-- Pull in extra navigation from a browser view on the Plone site root -->
<after
css:theme-children="#leftnav"
css:content=".navitem"
href="/@@extra-nav"
/>
Theme parameters
~~~~~~~~~~~~~~~~
It is possible to pass arbitrary parameters to your theme, which can be
referenced as variables in XPath expressions. Parameters can be set in Plone's
theming control panel, and may be imported from a ``manifest.cfg`` file.
For example, you could have a parameter ``mode`` that could be set to the
string ``live`` or ``test``. In your rules, you could do something like this
to insert a warning when you are on the test server::
<before css:theme-children="body" if="$mode = 'test'">
<span class="warning">Warning: This is the test server</span>
</before>
You could even use the parameter value directly, e.g.::
<before css:theme-children="body">
<span class="info">This is the <xsl:value-of select="$mode" /> server</span>
</before>
The following parameters are always available to Plone themes:
``scheme``
The scheme portion of the inbound URL, usually ``http`` or ``https``.
``host``
The hostname in the inbound URL.
``path``
The path segment of the inbound URL. This will not include any virtual
hosting tokens, i.e. it is the path the end user sees.
``base``
The Zope base url (the ``BASE1`` request variable).
You can add additional parameters through the control panel, using TALES
expressions. Parameters are listed on the *Advanced* tab, one per line, in
the form ``<name> = <expression>``.
For example, if you want to avoid theming any pages that are loaded by Plone's
overlays, you can make use of the ``ajax_load`` request parameter that they
set. Your rules file might include::
<notheme if="$ajax_load" />
To add this parameter as well as the ``mode`` parameter outlined earlier, you
could add the following in the control panel::
ajax_load = python: request.form.get('ajax_load')
mode = string: test
The right hand side is a TALES expression. It *must* evaluate to a string,
integer, float, boolean or ``None``: lists, dicts and objects are not
supported. ``python:``, ``string:`` and path expressions work as they do
in Zope Page Templates.
The following variables are available when constructing these TALES expressions:
``context``
The context of the current request, usually a content object.
``request``
The current request.
``portal``
The portal root object.
``context_state``
The ``@@plone_context_state`` view, from which you can look up additional
values such as the context's URL or default view.
``portal_state``
The ``@@plone_portal_state`` view, form which you can look up additional
values such as the navigation root URL or whether or not the current
user is logged in.
See ``plone.app.layout`` for details about the ``@@plone_context_state`` and
``@@plone_portal_state`` views.
Theme parameters are usually integral to a theme, and will therefore be set
based on a theme's manifest when a theme is imported or enabled. This is done
using the ``[theme:parameters]`` section in the ``manifest.cfg`` file. For
example::
[theme]
title = My theme
description = A test theme
[theme:parameters]
ajax_load = python: request.form.get('ajax_load')
mode = string: test
Theme debugging
~~~~~~~~~~~~~~~
When Zope is in development mode (e.g. running in the foreground in a console
with ``bin/instance fg``), the theme will be re-compiled on each request. In
non-development mode, it is compiled once when first accessed, and then only re-
compiled the control panel values are changed.
Also, in development mode, it is possible to temporarily disable the theme
by appending a query string parameter ``diazo.off=1``. For example::
http://localhost:8080/Plone/some-page?diazo.off=1
Finally, you can get an overlay containing your rules, annotated with how
many times the conditions matched both the theme and the document. Green
means the condition matched, red means it didn't. The entire rule tag will
be green (i.e. it had an effect) so long as all conditions within are green.
To enable this, append ``diazo.debug=1``. For example::
http://localhost:8080/Plone/some-page?diazo.debug=1
The parameter is ignored in non-development mode.
Commonly used rules
~~~~~~~~~~~~~~~~~~~
The following recipes illustrate rules commonly used in building Plone themes:
To copy the page title::
<replace css:theme="title" css:content="title" />
To copy the ``<base />`` tag (necessary for Plone's links to work)::
<replace css:theme="base" css:content="base" />
If there is no ``<base />`` tag in the theme, you can do::
<before css:theme-children="head" css:content="base" />
To drop all styles and JavaScript resources from the theme and copy them
from Plone's ``portal_css`` tool instead::
<!-- Drop styles in the head - these are added back by including them from Plone -->
<drop theme="/html/head/link" />
<drop theme="/html/head/style" />
<!-- Pull in Plone CSS -->
<after theme-children="/html/head" content="/html/head/link | /html/head/style" />
To copy Plone's JavaScript resources::
<!-- Pull in Plone CSS -->
<after theme-children="/html/head" content="/html/head/script" />
To copy the class of the ``<body />`` tag (necessary for certain Plone
JavaScript functions and styles to work properly)::
<!-- Body -->
<merge attributes="class" css:theme="body" css:content="body" />
Advanced: Using portal_css to manage your CSS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Plone's "resource registries", including the ``portal_css`` tool, can be used
to manage CSS stylesheets. This offers several advantages over simply linking
to your stylesheets in the template, such as:
* Detailed control over the ordering of stylesheets
* Merging of stylesheets to reduce the number of downloads required to render
your page
* On-the-fly stylesheet compression (e.g. whitespace removal)
* The ability to include or exclude a stylesheet based on an expression
It is usually desirable (and sometimes completely necessary) to leave the
theme file untouched, but you can still use ``portal_css`` to manage your
stylesheets. The trick is to:
* Register your theme's styles with Plone's ``portal_css`` tool (this is
normally best done when you ship a theme in a Python package - there is
currently no way to automate this for a theme imported from a Zip file or
created through the web)
* Drop the theme's styles with a rule, and then
* Include all styles from Plone
For example, you could add the following rules::
<drop theme="/html/head/link" />
<drop theme="/html/head/style" />
<!-- Pull in Plone CSS -->
<after theme-children="/html/head" content="/html/head/link | /html/head/style" />
The use of an "or" expression for the content in the ``after />`` rule means
that the relative ordering of link and style elements is maintained.
To register stylesheets upon product installation using GenericSetup, use the
``cssregistry.xml`` import step in your GenericSetup ``profiles/default``
directory::
<?xml version="1.0"?>
<object name="portal_css">
<!-- Set conditions on stylesheets we don't want to pull in -->
<stylesheet
expression="not:request/HTTP_X_THEME_ENABLED | nothing"
id="public.css"
/>
<!-- Add new stylesheets -->
<stylesheet title="" authenticated="False" cacheable="True"
compression="safe" conditionalcomment="" cookable="True" enabled="on"
expression="request/HTTP_X_THEME_ENABLED | nothing"
id="++theme++my.theme/css/styles.css" media="" rel="stylesheet"
rendering="link"
applyPrefix="True"
/>
</object>
There is one important caveat, however. Your stylesheet may include relative
URL references of the following form::
background-image: url(../images/bg.jpg);
If your stylesheet lives in a resource directory (e.g. it is registered in
``portal_css`` with the id ``++theme++my.theme/css/styles.css``), this
will work fine so long as the registry (and Zope) is in debug mode. The
relative URL will be resolved by the browser to
``++theme++my.theme/images/bg.jpg``.
However, you may find that the relative URL breaks when the registry is put
into production mode. This is because resource merging also changes the URL
of the stylesheet to be something like::
/plone-site/portal_css/Suburst+Theme/merged-cachekey-1234.css
To correct for this, you must set the ``applyPrefix`` flag to ``true`` when
installing your CSS resource using ``cssregistry.xml``. There is a
corresponding flag in the ``portal_css`` user interface.
It is sometimes useful to show some of Plone's CSS in the styled site. You
can achieve this by using an Diazo ``<after />`` rule or similar to copy the
CSS from Plone's generated ``<head />`` into the theme. You can use the
``portal_css`` tool to turn off the style sheets you do not want.
However, if you also want the site to be usable in non-themed mode (e.g. on a
separate URL), you may want to have a larger set of styles enabled when Diazo
is not used. To make this easier, you can use the following expressions as
conditions in the ``portal_css`` tool (and ``portal_javascripts`` if relevant),
in ``portal_actions``, in page templates, and other places that use TAL
expression syntax::
request/HTTP_X_THEME_ENABLED | nothing
This expression will return True if Diazo is currently enabled, in which case
an HTTP header "X-Theme-Enabled" will be set.
If you later deploy the theme to a fronting web server such as nginx, you can
set the same request header there to get the same effect, even if
``plone.app.theming`` is uninstalled.
Use::
not: request/HTTP_X_THEME_ENABLED | nothing
to 'hide' a style sheet from the themed site.
Advanced: Disable diazo transformation by setting the ``X-Theme-Disabled`` header
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The diazo transformation is not applied
if a response header ``X-Theme-Disabled`` is set.
In a browser view, the header can be set by using this instruction::
self.request.response.setHeader('X-Theme-Disabled', '1')
This is a complete example::
class NoDiazoView(BrowserView):
def __call__(self):
self.request.response.setHeader('X-Theme-Disabled', '1')
return super(NoDiazoView).__call__()
Changelog
=========
.. You should *NOT* be adding new change log entries to this file.
You should create a file in the news directory instead.
For helpful instructions, please see:
https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst
.. towncrier release notes start
5.0.7 (2024-01-18)
------------------
Bug fixes:
- Traverse to theme resources from the portal. Fix broken theme when rendering accessible content contained in an inaccessible navigation-root. Fixes #142
[pbauer] (#142)
5.0.6 (2023-12-14)
------------------
Bug fixes:
- Fix AttributeError in ``custom.css``: "module 'wsgiref' has no attribute 'handlers'".
[maurits] (#230)
5.0.5 (2023-10-07)
------------------
Internal:
- Update configuration files.
[plone devs] (cfffba8c)
5.0.4 (2023-06-22)
------------------
Bug fixes:
- Unify default values for translations
[erral] (#223)
5.0.3 (2023-04-06)
------------------
Bug fixes:
- Fix theme for `pat-code-editor`.
[petschki] (#219)
5.0.2 (2023-03-22)
------------------
Bug fixes:
- Fixes circular dependency on ZCML level to `Products.CMFPlone`:
Move permission id=`plone.app.controlpanel.Themes` title=`Plone Site Setup: Themes` to this package.
[jensens] (permission-move)
Internal:
- Update configuration files.
[plone devs] (80cf330f)
5.0.1 (2023-03-14)
------------------
Bug fixes:
- Import more from plone.base.
Removed compatibility code for Python 2 and Zope 4.
[maurits] (#1)
- Bugfix: If there is no rules.xml given in a theme, abort transform early.
Otherwise, given an open file is given as iterable, the read buffer pointer is empty after this function, but None returned.
The new way the read buffer pointer is not touched.
[jensens, toalba] (#216)
5.0.0 (2022-12-02)
------------------
Bug fixes:
- Final release for Plone 6.0.0. (#600)
5.0.0b2 (2022-10-11)
--------------------
Bug fixes:
- Fix for `tinymce-styles-css` when copying theme.
[petschki] (#214)
5.0.0b1 (2022-08-31)
--------------------
Bug fixes:
- The action buttons in the theming control panel have been improved
[rohnsha0] (#212)
5.0.0a5 (2022-04-04)
--------------------
New features:
- Deactivate copy button and modal in theming control panel. [MrTango] (#205)
- Load barceloneta css in theming control panel to have it styled. [MrTango] (#205)
- Remove all thememapper functionality from theming control panel,
including Inspect/Modify theme and the Preview. [maurits] (#205)
- Use pat-code-editor for custom-css field. [MrTango] (#205)
5.0.0a4 (2021-11-23)
--------------------
Bug fixes:
- Add missing i18n:translate tags
[erral] (#204)
5.0.0a3 (2021-10-13)
--------------------
Bug fixes:
- Use HTML5 meta charset.
[thet] (#203)
5.0.0a2 (2021-09-15)
--------------------
Bug fixes:
- Fix unclosed file when reading manifest.cfg
[petschki] (#199)
- Remove cyclic dependency with Products.CMFPlone
[sneridagh] (#201)
5.0.0a1 (2021-07-26)
--------------------
Breaking changes:
- Add bootstrap icon from resolver from Plone 6.
[petschki, agitator] (#194)
Bug fixes:
- Avoid Server Side Request Forgery via lxml parser.
Taken over from `PloneHotfix20210518 <https://plone.org/security/hotfix/20210518/server-side-request-forgery-via-lxml-parser>`_.
[maurits] (#3274)
4.1.6 (2020-11-17)
------------------
Bug fixes:
- For increased security, fail when trying file protocol access in diazo rules.
Also do not resolve entities, and remove processing instructions.
[maurits] (#3209)
4.1.5 (2020-09-26)
------------------
Bug fixes:
- Fixed WrongContainedType for hostnameBlackList on Zope 5.
See also `issue 183 <https://github.com/plone/plone.app.theming/issues/183>`_.
[maurits] (#183)
- Fixed deprecation warning for ConfigParser.readfp.
[maurits] (#3130)
4.1.4 (2020-08-14)
------------------
Bug fixes:
- Fix a missing import [ale-rt] (#188)
4.1.3 (2020-07-30)
------------------
Bug fixes:
- Fixes #187: Invalid dependency on plone.app.caching
[jensens] (#187)
- Cleanup: Remove meanwhile unused test fixture code referring to ``plone.app.caching``.
Removed class and fixtures: ``ThemingWithCaching``, ``THEMINGWITHCACHING_FIXTURE``, ``THEMINGWITHCACHING_TESTING``.
Those were nowhere used active in Plone nor outside in Github.
[jensens] (#188)
4.1.2 (2020-07-01)
------------------
Bug fixes:
- Internationalize the Custom CSS placeholder.
This fixes https://github.com/plone/Products.CMFPlone/issues/3139
[vincentfretin] (#186)
4.1.1 (2020-06-24)
------------------
Bug fixes:
- Fix i18n of new messages related to new Custom CSS feature.
[vincentfretin] (#185)
4.1.0 (2020-06-16)
------------------
New features:
- Insert diazo bundle without rules.
[santonelli] (#176)
- Add custom CSS settings and view to theming control panel.
Depends on https://github.com/plone/Products.CMFPlone/pull/3089
[MrTango] (#178)
Bug fixes:
- Fix error on Python 3 with nonascii subrequest.
The subrequest would succeed, but the non-ascii would be ugly.
Fixes `issue 3069 <https://github.com/plone/Products.CMFPlone/issues/3068>`_ and `issue 162 <https://github.com/plone/plone.app.theming/issues/162>`_.
[maurits] (#162)
- Make it possible to preview themes TTW again.
[petri] (#173)
- Fix hostnameBlacklist (Theming ControlPanel) in Py3. [MrTango] (#179)
- Fix various ``WrongType`` exceptions when saving the control panel.
This was introduced by the ``processInputs`` change in version 4.0.5.
See `issue 183 <https://github.com/plone/plone.app.theming/issues/183>`_.
[maurits] (#183)
4.0.6 (2020-04-20)
------------------
Bug fixes:
- Minor packaging updates. (#1)
4.0.5 (2020-03-13)
------------------
Bug fixes:
- Do not call ``processInputs``.
It is not needed since Zope 4, and not existing in Zope 5.
[maurits] (#171)
4.0.4 (2019-12-11)
------------------
Bug fixes:
- Fix creating a new theme ttw in py2 with Zope 4.1.3.
[pbauer] (#166)
4.0.3 (2019-10-12)
------------------
Bug fixes:
- Load zcml of ``plone.resource`` for our use of the ``plone:static`` directive.
[maurits] (#2952)
4.0.2 (2019-09-13)
------------------
Bug fixes:
- Fixed Python3 TypeError: 'filter' object is not subscriptable.
This happened when overriding a filesystem theme with a TTW version
[fredvd] (#160)
4.0.1 (2019-02-14)
------------------
Bug fixes:
- Fix skinname-encoding in py3 (fixes
https://github.com/plone/Products.CMFPlone/issues/2748) [pbauer] (#2748)
4.0.0 (2019-02-13)
------------------
Breaking changes:
- Factor out all static resources into plone.staticresources as part of PLIP
1653. [thet, sunew] (#149)
Bug fixes:
- a11y: Added role attribute for portalMessage [nzambello] (#151)
- Fixed DeprecationWarning about SafeConfigParser class on Python 3. [maurits]
(#152)
- Fixed ResourceWarnings for unclosed files in tests. [maurits] (#154)
- Fixed "RuntimeError: dictionary changed size during iteration" [jensens]
(#156)
3.0.1 (2018-12-11)
------------------
Breaking changes:
- Remove five.globalrequest dependency.
It has been deprecated upstream (Zope 4).
[gforcada]
3.0.0 (2018-11-02)
------------------
New features:
- Recompiled resource bundles with latest mockup.
[sunew]
Bug fixes:
- Explicit load permissions for controlpanel.
[jensens]
- Fix tests for merged plone.login.
[jensens]
- More Python 3 fixes
[ale-rt, pbauer, davisagli]
2.0.3 (2018-04-04)
------------------
Bug fixes:
- Added a failing (5.1) test for fileuploads in the theme editor that breaks when plone.rest is installed. Fix is in https://github.com/plone/plone.rest/issues/59
[djay]
2.0.2 (2018-02-04)
------------------
Bug fixes:
- remove mention of non-existent Example theme
[tkimnguyen]
- Prepare for Python 2 / 3 compatibility
[pbauer, ale-rt]
2.0.1 (2017-07-03)
------------------
Bug fixes:
- Remove unittest2 dependency
[kakshay21]
2.0 (2017-05-24)
----------------
Breaking changes:
- Let the pattern configuration of the thememapper be in JSON format.
Fixes problems of thememapper working together with latest patternslib (2.1.0).
[thet]
Bug fixes:
- Fix thememapper pattern handling of buttons (via mockup update).
Update thememapper bundle.
[thet]
1.3.6 (2017-03-28)
------------------
Bug fixes:
- Reduce log level of ThemingPolicy cache to 'debug'.
[jensens]
1.3.5 (2017-02-12)
------------------
Bug fixes:
- Fix imports from Globals that was removed in Zope4
[pbauer]
- No longer patch Control Panel internals, as it was removed in Zope4
[MatthewWilkes]
- reST syntax, styleguide, wording and line length of the docs
[svx]
1.3.4 (2016-12-30)
------------------
Bug fixes:
- Make diazo.debug work again when DIAZO_ALWAYS_CACHE_RULES is set.
[ale-rt]
1.3.3 (2016-12-02)
------------------
Bug fixes:
- Remove roman monkey patch.
[gforcada]
1.3.2 (2016-09-23)
------------------
New features:
- Add Update -button for theming control panel making it possible to
reload modified theme manifest without deactivating theme at first.
[datakurre]
1.3.1 (2016-09-07)
------------------
Fixes:
- Enable unload protection by using pattern class ``pat-formunloadalert`` instead ``enableUnloadProtection``.
[thet]
- Small fix in documentation
[staeff]
- Fix issue where theming control panel errored when a packaged
theme was overridden with a global resource directory theme
[datakurre]
1.3.0 (2016-06-07)
------------------
New:
- Control theme compilation in development mode
through the environment variable ``DIAZO_ALWAYS_CACHE_RULES``
[ale-rt]
Fixes:
- Small fixes to documentation
[ale-rt]
1.2.19 (2016-03-31)
-------------------
New:
- For the theming controlpanel, change base URLs from portal URL to what getSite returns, but don't change the controlpanels context binding.
This allows for more flexibility when configuring it to be allowed on a sub site with a local registry.
[thet]
1.2.18 (2016-03-03)
-------------------
Fixes:
- Fixed html validation: element nav does not need a role attribute.
[maurits]
- Handle potential scenarios where wrong theme would show selected in the theming
control panel
[vangheem]
1.2.17 (2016-02-11)
-------------------
New:
- Documented how to disable diazo transform by setting the
``X-Theme-Disabled`` header. [ale-rt]
Fixes:
- Rebuild resources so they work with latest mockup/patternslib
integration changes. [vangheem]
- Removed github dependencies in thememapper. [Gagaro]
1.2.16 (2015-11-26)
-------------------
Fixes:
- Updated Site Setup link in all control panels.
Fixes https://github.com/plone/Products.CMFPlone/issues/1255
[davilima6]
1.2.15 (2015-10-28)
-------------------
Fixes:
- Do not fail in ``isThemeEnabled`` when we have no settings, for
example when migrating from Plone 3 to Plone 5, but maybe also in
other cases.
[maurits]
- Fixed Unicode Encode Error when to copy into multi-byte title / description
[terapyon]
1.2.14 (2015-09-27)
-------------------
- Fix i18n in mapper.pt
[vincentfretin]
1.2.13 (2015-09-20)
-------------------
- Pull mark_special_links, external_links_open_new_window values
from configuration registry.
[esteele]
- Fix visual glitch on Safari
[davilima6]
- Show active theme at the top of the theme list.
Fixes https://github.com/plone/plone.app.theming/issues/70
[tmassman]
1.2.12 (2015-09-15)
-------------------
- Remove bundled twitter bootstrap theme 'example'.
Fixes https://github.com/plone/Products.CMFPlone/issues/877
[pbauer]
- Remove duplicate type attribute for theming control panel delete modal.
[esteele]
1.2.11 (2015-09-11)
-------------------
- rewrite manifest from copied theme with relative paths also
[vangheem]
1.2.10 (2015-09-08)
-------------------
- theme mapper fixes for odd behavior in save files at times
[swartz]
1.2.9 (2015-08-22)
------------------
- Build thememapper resources.
[vangheem]
- Added cache invalidation option.
[swartz]
1.2.8 (2015-08-20)
------------------
- change link from plone.org to plone.com.
[tkimnguyen]
- fix toolbar on control panel
[vangheem]
- fix less building
[obct537]
- Fixed copy modal for themes with a dot in the name.
[Gagaro]
1.2.7 (2015-07-18)
------------------
- Provide better styling to themeing control panel, less build, finish implementation
[obct537]
- make sure when copying themes that you try to modify the base urls
to match the new theme are all the manifest.cfg settings
[vangheem]
- implement switchable theming policy API, re-implement theme caching
[gyst]
- fixed configuration of copied theme
[vmaksymiv]
- implemented upload for theme manager
[schwartz]
- Change the category of the configlet to 'plone-general'.
[sneridagh]
1.2.6 (2015-06-05)
------------------
- removed irrelevant theme renaming code
[schwartz]
- Filesystem themes are now correctly overridden. TTW themes can no longer be overridden
[schwartz]
- re-added manifest check
[schwartz]
- Fixed broken getTheme method
[schwartz]
- Minor ReStructuredText fixes for documentation.
[maurits]
1.2.5 (2015-05-13)
------------------
- Fix RestructuredText representation on PyPI by bringing back a few
example lines in the manifest.
[maurits]
1.2.4 (2015-05-12)
------------------
- Add setting for tinymce automatically detected styles
[vangheem]
1.2.3 (2015-05-04)
------------------
- fix AttributeError: 'NoneType' object has no attribute 'getroottree' when the result is not
html / is empty.
[sunew]
- make control panel usable again. Fixed problem where skins
control panel is no longer present.
[vangheem]
- unified different getTheme functions.
[jensens]
- pep8ified, housekeeping, cleanup
[jensens]
- Specify i18n:domain in controlpanel.pt.
[vincentfretin]
- pat-modal pattern has been renamed to pat-plone-modal
[jcbrand]
- Fix load pluginSettings for the enabled theme before calling plugins for
onEnabled and call onEnabled plugins with correct parameters
[datakurre]
1.2.2 (2015-03-22)
------------------
- Patch the ZMI only for available ZMI pages.
[thet]
- Change deprecated import of ``zope.site.hooks.getSite`` to
``zope.component.hooks.getSite``.
[thet]
- Add an error log if the subrequest failed (probably a relative xi:include)
instead of silently returning None (and so having a xi:include returning
nothing).
[vincentfretin]
- Fix transform to not affect the result when theming is disabled
[datakurre]
- Integrate thememapper mockup pattern and fix theming control panel
to be more usable
[ebrehault]
1.2.1 (2014-10-23)
------------------
- Remove DL's from portal message in templates.
https://github.com/plone/Products.CMFPlone/issues/153
[khink]
- Fix "Insufficient Privileges" for "Site Administrators" on the control panel.
[@rpatterson]
- Add IThemeAppliedEvent
[vangheem]
- Put themes in a separate zcml file to be able to exclude them
[laulaz]
- #14107 bot requests like /widget/oauth_login/info.txt causes
problems finding correct context with plone.app.theming
[anthonygerrard]
- Added support for ++theme++ to traverse to the contents of the
current activated theme.
[bosim]
1.2.0 (2014-03-02)
------------------
- Disable theming for manage_shutdown view.
[davisagli]
- Fix reference to theme error template
[afrepues]
- Add "Test Styles" button in control panel to expose, test_rendering template.
[runyaga]
1.1.1 (2013-05-23)
------------------
- Fixed i18n issues.
[thomasdesvenain]
- Fixed i18n issues.
[jianaijun]
- This fixed UnicodeDecodeError when Theme Title is Non-ASCII
in the manifest.cfg file.
[jianaijun]
1.1 (2013-04-06)
----------------
- Fixed i18n issues.
[vincentfretin]
- Make the template theme do what it claims to do: copy styles as
well as scripts.
[smcmahon]
- Change the label and description for the example theme to supply useful
information.
[smcmahon]
- Upgrades from 1.0 get the combined "Theming" control panel that was added in
1.1a1.
[danjacka]
1.1b2 (2013-01-01)
------------------
- Ensure host blacklist utilises SERVER_URL to correctly determine hostname
for sites hosted as sub-folders at any depth.
[davidjb]
- Add test about plone.app.theming / plone.app.caching integration when
using GZIP compression for anonymous
(see ticket `12038 <https://dev.plone.org/ticket/12038>`_). [ebrehault]
1.1b1 (2012-10-16)
------------------
- Add diazo.debug option, route all error_log output through
this so debugging can be displayed
[lentinj]
- Make example Bootstrap-based theme use the HTML5 DOCTYPE.
[danjacka]
- Demote ZMI patch log message to debug level.
[hannosch]
- Upgrade to ACE 1.0 via plone.resourceeditor
[optilude]
- Put quotes around jQuery attribute selector values to appease
jQuery 1.7.2.
[danjacka]
1.1a2 (2012-08-30)
------------------
- Protect the control panel with a specific permission so it can be
delegated.
[davisagli]
- Advise defining ajax_load as ``request.form.get('ajax_load')`` in
manifest.cfg. For instance, the login_form has an hidden empty
ajax_load input, which would give an unthemed page after submitting
the form.
[maurits]
- Change theme editor page templates to use main_template rather than
prefs_main_template to avoid inserting CSS and JavaScript too early
under plonetheme.classic.
[danjacka]
1.1a1 (2012-08-08)
------------------
- Replace the stock "Themes" control panel with a renamed "Theming" control
panel, which incorporates the former's settings under its "Advanced" tab.
[optilude]
- Add a full in-Plone theme authoring environment
[optilude, vangheem]
- Update IBeforeTraverseEvent import to zope.traversing.
[hannosch]
- On tab "Manage themes", change table header to
better describe what's actually listed.
[kleist]
1.0 (2012-04-15)
----------------
* Prevent AttributeError when getRequest returns None.
[maurits]
* Calculate subrequests against navigation root rather than portal.
[elro]
* Supply closest context found for 404 pages.
[elro]
* Lookup portal state with correct context.
[elro]
1.0b9 - 2011-11-02
------------------
* Patch App.Management.Navigation to disable theming of ZMI pages.
[elro]
1.0b8 - 2011-07-04
------------------
* Evaluate theme parameters regardless of whether there is a valid context or
not (e.g. when templating a 404 page).
[lentinj]
1.0b7 - 2011-06-12
------------------
* Moved the *views* and *overrides* plugins out into a separate package
``plone.app.themingplugins``. If you want to use those features, you need
to install that package in your buildout. Themes attempting to register
views or overrides in environments where ``plone.app.themingplugins`` is not
installed will install, but views and overrides will not take effect.
[optilude]
1.0b6 - 2011-06-08
------------------
* Support for setting arbitrary Doctypes.
[elro]
* Upgrade step to update plone.app.registry configuration.
[elro]
* Fixed plugin initialization when applying a theme.
[maurits]
* Query the resource directory using the 'currentTheme' name instead
of the Theme object (updating the control panel was broken).
[maurits]
* Fix zip import (plugin initialization was broken.)
[elro]
1.0b5 - 2011-05-29
------------------
* Make sure the control panel is never themed, by setting the X-Theme-Disabled
response header.
[optilude]
* Add support for registering new views from Zope Page Templates and
overriding existing templates. See README for more details.
[optilude]
1.0b4 - 2011-05-24
------------------
* Add support for ``X-Theme-Disabled`` response header.
[elro]
* Make "Replace existing theme" checkbox default to off.
[elro]
* Fix control panel to correctly display a newly uploaded theme.
[elro]
* Fix zip import to work correctly when no manifest is supplied.
[elro]
1.0b3 - 2011-05-23
------------------
* Show theme name along with title in control panel.
[elro]
1.0b2 - 2011-05-16
------------------
* Encode internally resolved documents to support non-ascii characters
correctly.
[elro]
* Fix control panel to use theme name not id.
[optilude]
1.0b1 - 2011-04-22
------------------
* Wrap internal subrequests for css or js in style or script tags to
facilitate inline includes.
[elro]
* Add ``theme.xml`` import step (see README).
[optilude]
* Add support for ``[theme:parameters]`` section in ``manifest.cfg``, which
can be used to set parameters and the corresponding TALES expressions to
calculate them.
[optilude]
* Add support for parameter expressions based on TALES expressions
[optilude]
* Use plone.subrequest 1.6 features to work with IStreamIterator from
plone.resource.
[elro]
* Depend on ``Products.CMFPlone`` instead of ``Plone``.
[elro]
* Added support for uploading themes as Zip archives.
[optilude]
* Added theme off switch: Add a query string parameter ``diazo.off=1`` to a
request whilst Zope is in development mode to turn off the theme.
[optilude]
* Removed 'theme' and alternative themes support: Themes should be referenced
using the ``<theme />`` directive in the Diazo rules file.
[optilude]
* Removed 'domains' support: This can be handled with the rules file syntax
by using the ``host`` parameter.
[optilude]
* Removed 'notheme' support: This can be handled within the rules file syntax
by using the ``path`` parameter.
[optilude]
* Added ``path`` and ``host`` as parameters to the Diazo rules file. These
can now be used as conditional expressions.
[optilude]
* Removed dependency on XDV in favour of dependency on Diazo (which is the
new name for XDV).
[optilude]
* Forked from collective.xdv 1.0rc11.
[optilude]
Raw data
{
"_id": null,
"home_page": "https://pypi.org/project/plone.app.theming",
"name": "plone.app.theming",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "plone diazo xdv deliverance theme transform xslt",
"author": "Martin Aspeli and Laurence Rowe",
"author_email": "optilude@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c7/5e/1f9e1bfd1cb61d344a234324b0a9af777dc519ef0fdaa7ec2e1b364a82b9/plone.app.theming-5.0.7.tar.gz",
"platform": null,
"description": "This package offers a simple way to develop and deploy Plone themes using the Diazo theming engine. \nIf you are not familiar with Diazo, check out the `Diazo documentation <http://diazo.org>`_.\n\nIt comes with a user guide, reproduced below, available through the theming\ncontrol panel.\n\nplone.app.theming manual\n========================\n\nThis guide provides an overview of Diazo theming in Plone versions 4.3 and higher.\n\n.. contents:: Contents\n :local:\n\nIntroduction\n------------\n\nIn `Plone <http://plone.org>`_ versions 4.3 and higher you\ncan edit your website theme through web browser in Plone's site setup control panel.\nOnly HTML, CSS and little XML knowledge needed as the prerequisitements.\nThis guide explains how to use this feature of Plone.\n\nSee `introduction video to plone.app.theming <https://vimeo.com/42564510>`_.\n\nWhat is a Diazo theme?\n----------------------\n\nA \"theme\" makes a website (in this case, one powered by Plone) take on a\nparticular look and feel.\n\n*Diazo* (formerly known as XDV) is a technology that can be used to theme\nwebsites. It is not specific to Plone per se, but has been created by the Plone\ncommunity and, as of Plone 4.3, provides the default way to apply a theme to a\nPlone site. You can learn more about Diazo at http://diazo.org.\n\nDiazo themes may be a little different to themes you have created in other\nsystems, and indeed to themes you may have created for earlier versions of\nPlone. A Diazo theme is really about transforming some content - in this case\nthe output from \"vanilla\" Plone - into a different set of HTML markup by\napplying a set of rules to combine a static HTML mock-up of the end result you\nwant with the dynamic content coming from Plone.\n\nIn comparison, the previous way to theme a Plone site (like the way many other\ncontent management systems are themed) relies on selectively overriding the\ntemplates and scripts that Plone uses to build a page with custom versions\nthat produce different HTML markup. The latter approach can be more powerful,\ncertainly, but also requires much deeper knowledge of Plone's internals and\ncommand of server-side technologies such as Zope Page Templates and even Python.\nDiazo themes, by contrast, are easy to understand for web designers and non-\ndevelopers alike.\n\nA Diazo theme consists of three elements:\n\n1. One or more HTML mockups, also referred to as *theme* files, that represent\n the desired look and feel.\n\n These will contain placeholders for content that is to be provided by the\n Plone content management system. Mockups usually reference CSS, JavaScript\n and image files by relative path. The most common way to create a theme is to\n use desktop software like Dreamweaver or a text editor to create the relevant\n markup, styles and scripts, and test the theme locally in a web browser.\n2. The *content* that is being themed. In this case, that is the output from\n Plone.\n3. A *rules file*, which defines how the placeholders in the theme (i.e. the\n HTML mockup) should be replaced by relevant markup in the content.\n\n The rules file uses XML syntax (similar to HTML). Here is a very simple\n example::\n\n <?xml version=\"1.0\" encoding=\"UTF-8\"?>\n <rules\n xmlns=\"http://namespaces.plone.org/diazo\"\n xmlns:css=\"http://namespaces.plone.org/diazo/css\"\n xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\">`\n\n <theme href=\"theme.html\" />\n\n <replace css:content-children=\"#content\" css:theme-children=\"#main\" />\n\n </rules>\n\n Here, we are replacing the contents (child nodes) of a placeholder element\n with HTML id ``main`` in the theme file (``theme.html``, found in the same\n directory as the ``rules.xml`` file, as referenced by the ``<theme />`` rule)\n with the contents (children) of the element with the HTML id ``content`` in\n the markup generated by Plone.\n\n When this theme is applied, the result will look very much like the static\n HTML file ``theme.html`` (and its referenced CSS, JavaScript and image\n files), except the placeholder that is identified by the node in the theme\n with id ``main`` will be filled by Plone's main content area.\n\nPlone ships with an example theme called, appropriately, *Example theme*, which\nuses the venerable `Twitter Bootstrap <http://twitter.github.com/bootstrap/>`_\nto build a simple yet functional theme exposing most of Plone's core\nfunctionality. You are advised to study it - in particular the ``rules.xml``\nfile - to learn more about how Diazo themes work.\n\nUsing the control panel\n-----------------------\n\nAfter installation of the *Diazo theme support* package in a Plone site, the\n*Theming* control panel will appear in Plone's *Site setup*.\n\nThe main tab of this control panel, *Themes*, will show all available themes,\nwith buttons to activate/deactivate, modify, copy or delete each, as well as\nbuttons to create new themes or bring up this help text.\n\nClick on a theme preview image to open a preview of that theme in a new tab\nor window. The preview is navigable, but form submissions and some advanced\nfeatures will not work.\n\nSelecting a theme\n~~~~~~~~~~~~~~~~~\n\nTo apply an existing theme, simply click the *Activate* button underneath the\ntheme preview. The currently active theme will be highlighted in yellow. If\nyou deactivate the currently active theme, no Diazo theme will be applied, i.e.\n\"vanilla\" Plone theming will apply.\n\n*Note*: The *Theming* control panel is never theemd, ensuring that you can\nalways deactivate an errant theme that could render the control panel unusable.\nThus, you may not see any difference immediately after enabling a theme. Simply\nnavigate to another page in the Plone site, though, and you should see the\ntheme applied.\n\nCreating a new theme\n~~~~~~~~~~~~~~~~~~~~\n\nNew themes can be created in one of two ways:\n\n* Click the *New theme* button at the top of the *Themes* tab in the *Theming*\n control panel and enter a title and description in the form that appears.\n A bare-bones theme will be created, and you will be taken to the *Modify\n theme* screen (see below), where you can edit or create theme and rules files.\n* Click the *Copy* button underneath any existing theme and enter a title and\n description in the form that appears. A new theme will be created as a copy\n of the existing theme, and you will be taken to the *Modify theme* (see\n below), where you can edit or create theme and rules files.\n\nUploading an existing theme\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThemes can be distributed as Zip files, containing the HTML mockup and rules\nfile. To download an existing theme, click the *Download* button underneath the\ntheme on the *Themes* tab of the *Theming* control panel.\n\nTo upload such a Zip file into another site, use the *Upload Zip file* button\non the *Themes* tab of the *Theming* control panel. You can choose whether or\nnot to replace any existing theme with the same name (based on the name of the\ntop-level directory contained within the Zip file).\n\nYou can also upload a Zip file of a static HTML mockup that does not contain a\nrules file, such as a design provided by a Plone-agnostic web designer.\n\nIn this case, a basic ``rules.xml`` file will be added for you to start building\nup a theme from using the *Modify theme* screen (see below). The\ngenerated rules file will assume the main HTML mockup file is called\n``index.html``, but you can change this in ``rules.xml``.\n\nOnce you have successfully uploaded a theme Zip file, you will be taken to the\n*Modify theme* screen (see below), where you can edit or create theme files.\n\n*Hint:* If you get an error message like \"The uploaded file does not contain\na valid theme archive\", this usually means that you have uploaded a Zip file\nthat contains multiple files and folders, rather than a single top level\nfolder with all the theme resources in it. This could happen if you compressed\na theme or HTML mockup by adding its files and folders directly a Zip archive,\nrather than compressing the directory in which they were found. To fix this,\nsimply unzip the archive on your computer into a new directory, move up a level,\nand compress this directory on its own into a new Zip file, which you can then\nupload.\n\nModifying the theme\n~~~~~~~~~~~~~~~~~~~\n\nYou can modify a theme by clicking *Modify theme* underneath a theme in the\n*Themes* tab of the *Theming* control panel. This screen is also launched\nautomatically when you create or upload a new theme.\n\n*Note:* Only themes created or uploaded through the *Theming* control panel can\nbe modified through Plone. Themes installed by third-party add-ons or\ndistributed on the filesystem cannot, although changes made on the filesystem\nwill be reflected immediately if Zope is running in debug mode. To modify a\nfilesystem theme, you can copy it to a new in-Plone theme by clicking the *Copy*\nbutton underneath the theme in the *Theming* control panel.\n\nThe *Modify theme* screen initially shows a file manager, with a file tree on\nthe left and an editor on the right. Click on a file in the file tree to open an\neditor or preview: HTML, CSS, JavaScript and other text files can be edited\ndirectly through the editor. Other files (e.g. images) will be rendered as a\npreview.\n\n*Note:* The advanced editor with syntax highlighting is not available in\nMicrosoft Internet Explorer.\n\nClick *New folder* to create a new folder. You can also right-click on a folder\nin the file tree to bring up this action.\n\nClick *New file* to create a new text file. You can also right-click on a folder\nin the file tree to bring up this action.\n\nClick *Upload file* to upload a file from your computer. You can also right-\nclick on a folder in the file tree to bring up this action.\n\nClick *Preview theme* to preview the theme as it will be applied with the mockup\nand rules as currently saved. The preview is navigable, but forms and certain\nadvanced features will not work.\n\nTo save the file currently being edited, click the *Save file* button, or use\nthe keyboard shortcut ``Ctrl+S`` (Windows/Linux) or ``Cmd+S`` (Mac).\n\nTo rename or delete a file or folder, right-click on it in the file tree and\nselect the appropriate action.\n\nThe theme inspector\n~~~~~~~~~~~~~~~~~~~\n\nThe theme inspector provides an advanced interface for discovering and building\nup the rules of a Diazo theme. It can be launched by clicking the *Show\ninspectors* button on the *Modify theme* screen for in-Plone themes, or by\nclicking the *Inspect theme* button underneath a filesystem theme on the\n*Themes* tab of the *Theming* control panel.\n\nThe theme inspector consists of two panels:\n\n* The *HTML mockup*. If there are several HTML files in the theme, you can switch\n between them using the drop-down list underneath the *HTML mockup* panel.\n* The *Unthemed content*. This shows Plone without any theme applied.\n\nEither panel can be maximised by clicking the arrows icon at the top right of\neither.\n\nThe *HTML mockups* and *Unthemed content* panels can be switch to source view,\nshowing their underlying HTML markup, by clicking the tags icon at the top right\nof either.\n\nAs you hover over elements in the *HTML mockup* or *Unthemed content* panels,\nyou will see:\n\n* An outline showing the element under the cursor.\n* A CSS or XPath selector in the status bar at the bottom if the panel which\n would uniquely identify this element in a Diazo rule.\n\nClick on an element or press ``Enter`` whilst hovering oveer an element to\nselect it. The most recently selected element in each panel is shown in the\nbottom right of the relevant status bar.\n\nPress ``Esc`` whilst hovering over an element to select its parent. This is\nuseful when trying to select \"invisible\" container elements. Press ``Enter``\nto save this selection.\n\nThe contents of the *HTML mockup* or (more commonly) *Unthemed content* panels\ncan be navigated, for example to get to a content page that requires specific\ntheme rules, by disabling the inspector. Use the toggle switches at the bottom\nright of the relevant panel to enable or disable the selector.\n\nThe rule builder\n~~~~~~~~~~~~~~~~\n\nClick the *Build rule* button near the top of the *Modify theme* or *Inspect\ntheme* screen to launch an interactive rule building wizard. You will be asked\nwhich type of rule to build, and then prompted to select the relevant elements\nin the *HTML mockup* and/or *Unthemed content* panels as required. By default,\nthis will use any saved selections, unless you untick the *Use selected\nelements* box on the first page if the wizard.\n\nOnce the wizard completes, you will be shown the generated rule. You can edit\nthis if you wish. If you click *Insert*, the newly generated rule will be\ninserted into the ``rules.xml`` editor at or near your current cursor position.\nYou can move it around or edit it further as you wish.\n\nClick *Preview theme* to preview the theme in a new tab or window. Don't forget\nto save the ``rules.xml`` file if you have made changes.\n\n*Note*: In readonly mode, you can build rules and inspect the HTML mockup and\ntheme, but not change the ``rules.xml`` file. In this case, the *Insert* button\nof the rule builder (see below) will not be available either.\n\n*Note:* The ability to insert rules from the *Build rule* wizard are not\navailable in Microsoft Internet Explorer, although you will be given the option\nto copy the rule to the clipboard when using this browser.\n\nAdvanced settings\n~~~~~~~~~~~~~~~~~\n\nThe *Theming* control panel also contains a tab named *Advanced settings*. Here\nbe dragons.\n\nThe *Advanced settings* tab is divided into two areas. The first, *Theme\ndetails*, contains the underlying settings that are modified when a theme is\napplied from the *Themes* control panel. These are:\n\n* Whether or not Diazo themes are enabled at all.\n* The path to the rules file, conventionally called ``rules.xml``, either\n relative to the Plone site root or as an absolute path to an external\n server.\n* The prefix to apply when turning relative paths in themes (e.g. references to\n images in an ``<img />`` tag's ``src`` attribute) into absolute ones at\n rendering time.\n* The HTML ``DOCTYPE`` to apply to the rendered output, if different to the default\n ``XHTML 1.0 Transitional``.\n* Whether or not to allow theme resources (likes ``rules.xml``) to be read from\n the network. Disabling this gives a modest performance boost.\n* A list of host names for which a theme is never applied. Most commonly, this\n contains ``127.0.0.1``, allowing you to view an unthemed site through\n ``http://127.0.0.1:8080`` and a themed one at ``http://localhost:8080`` during\n development, say.\n* A list of theme parameters and the TALES expressions to generate them\n (see below).\n\nThe second, *Theme base*, controls the presentation of the unthemed content, and\napply even if no Diazo theme is being applied. These are the settings that used\nto be found in the *Themes* control panel in previous versions of Plone.\n\nReference\n---------\n\nThe remainder of this guide contains reference materials useful for theme\nbuilders.\n\nDeploying and testing themes\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo build and test a theme, you must first create a static HTML mockup of the\nlook and feel you want, and then build a rules file to describe how Plone's\ncontent maps to the placeholders in this mockup.\n\nThe mockup can be created anywhere using whatever tool you feel most comfortable\nbuilding web pages in. To simplify integration with Plone, you are recommended\nto make sure it uses relative links for resources like CSS, JavaScript and image\nfiles, so that it will render properly when opened in a web browser from a local\nfile. Plone will convert these relative links to the appropriate absolute paths\nautomatically, ensuring the theme works no matter which URL the user is viewing\nwhen the theme is applied to a Plone site.\n\nThere are several ways to get the theme into Plone:\n\n1. On the filesystem\n\n If you used an installer or a standard \"buildout\" to set up your\n Plone site, you should have a directory called ``resources`` in the\n root of your Plone installation (this is created using the\n ``resources`` option to the buildout recipe\n ``plone.recipe.zope2instance``. See\n http://pypi.python.org/pypi/plone.recipe.zope2instance for more\n details.)\n\n You can find (or create) a ``theme`` directory inside this\n directory, which is used to contain themes. Each theme needs its\n own directory with a unique name. Create one\n (e.g. ``resources/theme/mytheme``) and put your HTML files and any\n references resources inside this directory. You can use\n subdirectories if you wish, but you are recommended to keep the\n basic theme HTML files at the top of the theme directory.\n\n You will also need a rules file called ``rules.xml`` inside this\n directory. If you haven't got one yet, start with an empty one::\n\n <?xml version=\"1.0\" encoding=\"UTF-8\"?>\n <rules\n xmlns=\"http://namespaces.plone.org/diazo\"\n xmlns:css=\"http://namespaces.plone.org/diazo/css\"\n xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\">`\n\n <theme href=\"theme.html\" />\n <replace css:content-children=\"#content\" css:theme-children=\"#main\" />\n\n </rules>\n\n Provided you are running Zope in debug mode (e.g. you start it up\n with ``bin/instance fg``), changes to the theme and rules should\n take effect immediately. You can preview or enable the theme\n through the *Themes* control panel, and then iteratively modify the\n ``rules.xml`` file or the theme mockup as you wish.\n\n2. Through the web\n\n If you prefer (or do not have filesystem access), you can create\n themes entirely through the Plone control panel, either by\n duplicating an existing theme, or starting from scratch with a\n near-empty theme.\n\n See the instructions on using the control panel above for more\n details.\n\n Once a theme has been created, you can modify it through the\n *Theming* control panel. See above for more details.\n\n3. As a zip file\n\n Themes can be downloaded from Plone as Zip files, which can then be\n uploaded into other sites.\n\n See the instructions on using the control panel above for more\n details.\n\n In fact, you can create valid theme zip archives by compressing a\n theme directory on the filesystem using a standard compression tool\n such as *7-Zip* or *Winzip* (for Windows) or the built-in\n *Compress* action in the Mac OS X Finder. Just make sure you\n compress exactly one folder that contains all the theme files and\n the ``rules.xml`` file. (Do not compress the contents of the folder\n directly: when unpacked, the zip file should produce exactly one\n folder which in turn contains all the relevant files).\n\n4. In a Python package (programmers only)\n\n If you are creating a Python package containing Plone\n customisations that you intend to install into your site, you can\n let it register a theme for installation into the site.\n\n To do this, place a directory called e.g. ``theme`` at the top of\n the package, next to the Zope ``configure.zcml`` file, and add a\n ``<plone:static />`` declaration to the ``configure.zcml`` file::\n\n <configure\n xmlns:plone=\"http://namespaces.plone.org/plone\"\n xmlns=\"http://namespaces.zope.org/zope\">\n\n ...\n\n <plone:static name=\"mytheme\" directory=\"theme\" type=\"theme\" />\n\n ...\n\n </configure>\n\n Notice the declaration of the ``plone`` namespace at the root\n ``<configure />`` element. Place the theme files and the\n ``rules.xml`` file into the ``theme`` directory.\n\n If your package has a GenericSetup profile, you can automatically\n enable the theme upon installation of this profile by adding a\n ``theme.xml`` file in the ``profiles/default`` directory,\n containing e.g.::\n\n <theme>\n <name>mytheme</name>\n <enabled>true</enabled>\n </theme>\n\nThe manifest file\n~~~~~~~~~~~~~~~~~\n\nIt is possible to give additional information about a theme by placing a file\ncalled ``manifest.cfg`` next to the ``rules.xml`` file at the top of a theme\ndirectory.\n\nThis file may look like this::\n\n [theme]\n title = My theme\n description = A test theme\n rules = http://example.org/myrules.xml\n prefix = /some/prefix\n doctype = <!DOCTYPE html>\n preview = preview.png\n enabled-bundles = mybundle\n disabled-bundles = plone\n development-css = /++theme++barceloneta/css/barceloneta.css\n production-css = /++theme++barceloneta/css/barceloneta.min.css\n development-js = /++theme++barceloneta/barceloneta.js\n production-js = /++theme++barceloneta/barceloneta.min.js\n tinymce-content-css = /++theme++barceloneta/barceloneta.min.css\n tinymce-styles-css = /++theme++barceloneta/custom-styles.css\n\n\nAs shown here, the manifest file can be used to provide a more user friendly\ntitle and a longer description for the theme, for use in the control panel.\nOnly the ``[theme]`` header is required - all other keys are optional.\n\n\nManifest settings:\n\nrules\n to use a different rule file name than ``rules.xml`` (you should provide a URL\n or relative path).\n\nprefix\n To change the absolute path prefix (see *Advanced settings*),\n use::\n\n prefix = /some/prefix\n\ndoctype\n To employ a ``DOCTYPE`` in the themed content other than ``XHTML 1.0\n Transitional``, add e.g.::\n\n doctype = <!DOCTYPE html>\n\npreview\n To provide a user-friendly preview of your theme in the *Theming* control panel.\n Here, ``preview.png`` is an image file relative to the location of the\n ``manifest.cfg`` file::\n\n preview = preview.png\n\nenabled-bundles\n Bundles that will automatically be enabled when a theme is activated\n\ndisabled-bundles\n Bundles that will automatically be disabled when a theme is activated\n\ndevelopment-css\n CSS to automatically include when in development mode and theme is active\n\ndevelopment-js\n JavaScript file to automatically include when in development mode when\n theme is active\n\nproduction-css\n CSS to automatically include when theme is active and in production mode\n\nproduction-js\n JavaScript to automatically include when theme is active and in production mode\n\ntinymce-content-css\n CSS file tinymce should load to apply styles to content inside the editor\n\ntinymce-styles-css\n CSS file tinymce should load to provide additionally automatically detected\n drop-down styles in the editor\n\n\nExtensions to the Diazo theming engine can add support for additional blocks of\nconfigurable parameters.\n\nRules syntax\n~~~~~~~~~~~~\n\nThe following is a short summary of the Diazo rules syntax. See\nhttp://diazo.org for more details and further examples.\n\nSelectors\n+++++++++\n\nEach rule is represented by an XML tag that operates on one or more HTML\nelements in the content and/or theme. The elements to operate on are indicated\nusing attributes of the rules known as *selectors*.\n\nThe easiest way to select elements is to use a CSS expression selector, such as\n``css:content=\"#content\"`` or ``css:theme=\"#main .content\"``. Any valid CSS 3\nexpression (including pseudo-selectors like ``:first-child`` may be used.\n\nThe standard selectors, ``css:theme`` and ``css:content``, operate on the\nelement(s) that are matched. If you want to operate on the children of the\nmatched element instead, use ``css:theme-children=\"...\"`` or\n``css:content-children=\"...\"`` instead.\n\nIf you cannot construct a suitable CSS 3 expression, you can use XPath\nexpressions such as ``content=\"/head/link\"`` or ``theme=\"//div[@id='main']\"``\n(note the lack of a ``css:`` prefix when using XPath expressions). The two\napproaches are equivalent, and you can mix and match freely, but you cannot\nhave e.g. both a ``css:theme`` and a ``theme`` attribute on a single rule. To\noperate on children of a node selected with an XPath expression, use\n``theme-children=\"...\"`` or ``content-children=\"...\"``.\n\nYou can learn more about XPath at http://www.w3schools.com/xpath/default.asp.\n\nConditions\n++++++++++\n\nBy default, every rule is executed, though rules that do not match any elements\nwill of course do nothing. You can make a rule, set of rules or theme reference\n(see below) conditional upon an element appearing in the content by adding an\nattribute to the rule like ``css:if-content=\"#some-element\"`` (to use an XPath\nexpression instead, drop the ``css:`` prefix). If no elements match the\nexpression, the rule is ignored.\n\n**Tip:** if a ``<replace />`` rule matches an element in the theme but not in\nthe content, the theme node will be dropped (replaced with nothing). If you do\nnot want this behavior and you are unsure if the content will contain the\nrelevant element(s), you can use ``css:if-content`` conditional rule. Since\nthis is a common scenario, there is a shortcut: ``css:if-content=\"\"`` means\n\"use the expression from the ``css:content`` attribute\".\n\nSimilarly, you can construct a condition based on the path of the current\nrequest by using an attribute like ``if-path=\"/news\"`` (note that there is no\n``css:if-path`` ). If the path starts with a slash, it will match from the root\nof the Plone site. If it ends with a slash, it will match to the end of the URL.\nYou can set an absolute path by using a leading and a trailing slash.\n\nFinally, you can use arbitrary XPath expressions against any defined variable\nusing an attribute like ``if=\"$host = 'localhost'\"`` . By default, the variables\n``url`` , ``scheme`` , ``host`` and ``base`` are available, representing the\ncurrent URL. Themes may define additional variables in their manifests.\n\nAvailable rules\n+++++++++++++++\n\nThe various rule types are summarized below.\n\n``rules``\n#########\n\n::\n\n <rules>\n ...\n </rules>\n\nWraps a set of rules. Must be used as the root element of the rules file. Nested\n``<rules />`` can be used with a *condition* to apply a single condition to a\nset of rules.\n\nWhen used as the root element of the rules file, the various XML namespaces must\nbe declared::\n\n <rules\n xmlns=\"http://namespaces.plone.org/diazo\"\n xmlns:css=\"http://namespaces.plone.org/diazo/css\"\n xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\">\n ...\n </rules>\n\n``theme`` and ``notheme``\n#########################\n\n::\n\n <theme href=\"theme.html\" />\n <theme href=\"news.html\" if-path=\"/news\" />\n <notheme if=\"$host = 'admin.example.org'\" />\n\nChoose the theme file to be used. The ``href`` is a path relative to the rules\nfile. If multiple ``<theme />`` elements are present, at most one may be given\nwithout a condition. The first theme with a condition that is true will be used,\nwith the unconditional theme, if any, used as a fallback.\n\n``<notheme />`` can be used to specify a condition under which no theme\nshould be used. ``<notheme />`` takes precedence over ``<theme />``.\n\n**Tip:** To ensure you do not accidentally style non-Plone pages, add a\ncondition like ``css:if-content=\"#visual-portal-wrapper\"`` to the last theme\nlisted, and do not have any unconditional themes.\n\n``replace``\n###########\n\n::\n\n <replace\n css:content=\"#content\"\n css:theme=\"#main\"\n />\n\nReplaces the matched element(s) in the theme with the matched element(s) from\nthe content.\n\n``before`` and ``after``\n########################\n\n::\n\n <before\n css:content-children=\"#portal-column-one\"\n css:theme-children=\"#portlets\"\n />\n\n <after\n css:content-children=\"#portal-column-two\"\n css:theme-children=\"#portlets\"\n />\n\nInserts the matched element(s) from the content before or after the matched\nelement(s) in the theme. By using ``theme-children`` , you can insert the\nmatched content element(s) as the first (prepend) or last (append) element(s)\ninside the matched theme element(s).\n\n``drop`` and ``strip``\n######################\n\n::\n\n <drop css:content=\".documentByLine\" />\n <drop theme=\"/head/link\" />\n <drop css:theme=\"#content *\" attributes=\"onclick onmouseup\" />\n\n <strip css:content=\"#parent-fieldname-text\" />\n\nRemove element(s) from the theme or content. Note that unlike most other rules,\na ``<drop />`` or ``<strip />`` rule can operate on the ``theme`` or\n``content`` , but not both. ``<drop />`` removes the matched element(s) and\nany children, whereas ``<strip />`` removes the matched element(s), but leaves\nany children in place.\n\n``<drop />`` may be given a whitespace-separated list of ``attributes`` to\ndrop. In this case, the matched element(s) themselves will not be removed. Use\n``attributes=\"*\"`` to drop all attributes.\n\n``merge`` and ``copy``\n######################\n\n::\n\n <merge\n attributes=\"class\"\n css:content=\"body\"\n css:theme=\"body\"\n />\n\n <copy\n attributes=\"class\"\n css:content=\"#content\"\n css:theme=\"#main\"\n />\n\nThese rules operate on attributes. ``<merge />`` will add the contents of the\nnamed attribute(s) in the theme to the value(s) of any existing attributes with\nthe same name(s) in the content, separated by whitespace. It is mainly used to\nmerge CSS classes.\n\n``<copy />`` will copy attributes from the matched element(s) in the content\nto the matched element(s) in the theme, fully replacing any attributes with\nthe same name that may already be in the theme.\n\nThe ``attributes`` attribute can contain a whitespace-separated list of\nattributes, or the special value ``*`` to operate on all attributes of the\nmatched element.\n\nAdvanced modification\n++++++++++++++++++++++\n\nInstead of selecting markup to insert into the theme from the content, you can\nplace markup directly into the rules file, as child nodes of the relevant rule\nelement::\n\n <after css:theme=\"head\">\n <style type=\"text/css\">\n body > h1 { color: red; }\n </style>\n </after>\n\nThis also works on the content, allowing you to modify it on the fly before any\nrules are applied::\n\n <replace css:content=\"#portal-searchbox input.searchButton\">\n <button type=\"submit\">\n <img src=\"images/search.png\" alt=\"Search\" />\n </button>\n </replace>\n\nIn addition to including static HTML in this manner, you can use XSLT\ninstructions that operate on the content. You can even use ``css:`` selectors\ndirectly in the XSLT.::\n\n <replace css:theme=\"#details\">\n <dl id=\"details\">\n <xsl:for-each css:select=\"table#details > tr\">\n <dt><xsl:copy-of select=\"td[1]/text()\"/></dt>\n <dd><xsl:copy-of select=\"td[2]/node()\"/></dd>\n </xsl:for-each>\n </dl>\n </replace>\n\nRules may operate on content that is fetched from somewhere other than the\ncurrent page being rendered by Plone, by using the ``href`` attribute to specify\na path of a resource relative to the root of the Plone site::\n\n <!-- Pull in extra navigation from a browser view on the Plone site root -->\n <after\n css:theme-children=\"#leftnav\"\n css:content=\".navitem\"\n href=\"/@@extra-nav\"\n />\n\nTheme parameters\n~~~~~~~~~~~~~~~~\n\nIt is possible to pass arbitrary parameters to your theme, which can be\nreferenced as variables in XPath expressions. Parameters can be set in Plone's\ntheming control panel, and may be imported from a ``manifest.cfg`` file.\n\nFor example, you could have a parameter ``mode`` that could be set to the\nstring ``live`` or ``test``. In your rules, you could do something like this\nto insert a warning when you are on the test server::\n\n <before css:theme-children=\"body\" if=\"$mode = 'test'\">\n <span class=\"warning\">Warning: This is the test server</span>\n </before>\n\nYou could even use the parameter value directly, e.g.::\n\n <before css:theme-children=\"body\">\n <span class=\"info\">This is the <xsl:value-of select=\"$mode\" /> server</span>\n </before>\n\nThe following parameters are always available to Plone themes:\n\n``scheme``\n The scheme portion of the inbound URL, usually ``http`` or ``https``.\n``host``\n The hostname in the inbound URL.\n``path``\n The path segment of the inbound URL. This will not include any virtual\n hosting tokens, i.e. it is the path the end user sees.\n``base``\n The Zope base url (the ``BASE1`` request variable).\n\nYou can add additional parameters through the control panel, using TALES\nexpressions. Parameters are listed on the *Advanced* tab, one per line, in\nthe form ``<name> = <expression>``.\n\nFor example, if you want to avoid theming any pages that are loaded by Plone's\noverlays, you can make use of the ``ajax_load`` request parameter that they\nset. Your rules file might include::\n\n <notheme if=\"$ajax_load\" />\n\nTo add this parameter as well as the ``mode`` parameter outlined earlier, you\ncould add the following in the control panel::\n\n ajax_load = python: request.form.get('ajax_load')\n mode = string: test\n\nThe right hand side is a TALES expression. It *must* evaluate to a string,\ninteger, float, boolean or ``None``: lists, dicts and objects are not\nsupported. ``python:``, ``string:`` and path expressions work as they do\nin Zope Page Templates.\n\nThe following variables are available when constructing these TALES expressions:\n\n``context``\n The context of the current request, usually a content object.\n``request``\n The current request.\n``portal``\n The portal root object.\n``context_state``\n The ``@@plone_context_state`` view, from which you can look up additional\n values such as the context's URL or default view.\n``portal_state``\n The ``@@plone_portal_state`` view, form which you can look up additional\n values such as the navigation root URL or whether or not the current\n user is logged in.\n\nSee ``plone.app.layout`` for details about the ``@@plone_context_state`` and\n``@@plone_portal_state`` views.\n\nTheme parameters are usually integral to a theme, and will therefore be set\nbased on a theme's manifest when a theme is imported or enabled. This is done\nusing the ``[theme:parameters]`` section in the ``manifest.cfg`` file. For\nexample::\n\n [theme]\n title = My theme\n description = A test theme\n\n [theme:parameters]\n ajax_load = python: request.form.get('ajax_load')\n mode = string: test\n\nTheme debugging\n~~~~~~~~~~~~~~~\n\nWhen Zope is in development mode (e.g. running in the foreground in a console\nwith ``bin/instance fg``), the theme will be re-compiled on each request. In\nnon-development mode, it is compiled once when first accessed, and then only re-\ncompiled the control panel values are changed.\n\nAlso, in development mode, it is possible to temporarily disable the theme\nby appending a query string parameter ``diazo.off=1``. For example::\n\n http://localhost:8080/Plone/some-page?diazo.off=1\n\nFinally, you can get an overlay containing your rules, annotated with how\nmany times the conditions matched both the theme and the document. Green\nmeans the condition matched, red means it didn't. The entire rule tag will\nbe green (i.e. it had an effect) so long as all conditions within are green.\n\nTo enable this, append ``diazo.debug=1``. For example::\n\n http://localhost:8080/Plone/some-page?diazo.debug=1\n\nThe parameter is ignored in non-development mode.\n\nCommonly used rules\n~~~~~~~~~~~~~~~~~~~\n\nThe following recipes illustrate rules commonly used in building Plone themes:\n\nTo copy the page title::\n\n <replace css:theme=\"title\" css:content=\"title\" />\n\nTo copy the ``<base />`` tag (necessary for Plone's links to work)::\n\n <replace css:theme=\"base\" css:content=\"base\" />\n\nIf there is no ``<base />`` tag in the theme, you can do::\n\n <before css:theme-children=\"head\" css:content=\"base\" />\n\nTo drop all styles and JavaScript resources from the theme and copy them\nfrom Plone's ``portal_css`` tool instead::\n\n <!-- Drop styles in the head - these are added back by including them from Plone -->\n <drop theme=\"/html/head/link\" />\n <drop theme=\"/html/head/style\" />\n\n <!-- Pull in Plone CSS -->\n <after theme-children=\"/html/head\" content=\"/html/head/link | /html/head/style\" />\n\nTo copy Plone's JavaScript resources::\n\n <!-- Pull in Plone CSS -->\n <after theme-children=\"/html/head\" content=\"/html/head/script\" />\n\nTo copy the class of the ``<body />`` tag (necessary for certain Plone\nJavaScript functions and styles to work properly)::\n\n <!-- Body -->\n <merge attributes=\"class\" css:theme=\"body\" css:content=\"body\" />\n\nAdvanced: Using portal_css to manage your CSS\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nPlone's \"resource registries\", including the ``portal_css`` tool, can be used\nto manage CSS stylesheets. This offers several advantages over simply linking\nto your stylesheets in the template, such as:\n\n* Detailed control over the ordering of stylesheets\n* Merging of stylesheets to reduce the number of downloads required to render\n your page\n* On-the-fly stylesheet compression (e.g. whitespace removal)\n* The ability to include or exclude a stylesheet based on an expression\n\nIt is usually desirable (and sometimes completely necessary) to leave the\ntheme file untouched, but you can still use ``portal_css`` to manage your\nstylesheets. The trick is to:\n\n* Register your theme's styles with Plone's ``portal_css`` tool (this is\n normally best done when you ship a theme in a Python package - there is\n currently no way to automate this for a theme imported from a Zip file or\n created through the web)\n* Drop the theme's styles with a rule, and then\n* Include all styles from Plone\n\nFor example, you could add the following rules::\n\n <drop theme=\"/html/head/link\" />\n <drop theme=\"/html/head/style\" />\n\n <!-- Pull in Plone CSS -->\n <after theme-children=\"/html/head\" content=\"/html/head/link | /html/head/style\" />\n\nThe use of an \"or\" expression for the content in the ``after />`` rule means\nthat the relative ordering of link and style elements is maintained.\n\nTo register stylesheets upon product installation using GenericSetup, use the\n``cssregistry.xml`` import step in your GenericSetup ``profiles/default``\ndirectory::\n\n <?xml version=\"1.0\"?>\n <object name=\"portal_css\">\n\n <!-- Set conditions on stylesheets we don't want to pull in -->\n <stylesheet\n expression=\"not:request/HTTP_X_THEME_ENABLED | nothing\"\n id=\"public.css\"\n />\n\n <!-- Add new stylesheets -->\n <stylesheet title=\"\" authenticated=\"False\" cacheable=\"True\"\n compression=\"safe\" conditionalcomment=\"\" cookable=\"True\" enabled=\"on\"\n expression=\"request/HTTP_X_THEME_ENABLED | nothing\"\n id=\"++theme++my.theme/css/styles.css\" media=\"\" rel=\"stylesheet\"\n rendering=\"link\"\n applyPrefix=\"True\"\n />\n\n </object>\n\nThere is one important caveat, however. Your stylesheet may include relative\nURL references of the following form::\n\n background-image: url(../images/bg.jpg);\n\nIf your stylesheet lives in a resource directory (e.g. it is registered in\n``portal_css`` with the id ``++theme++my.theme/css/styles.css``), this\nwill work fine so long as the registry (and Zope) is in debug mode. The\nrelative URL will be resolved by the browser to\n``++theme++my.theme/images/bg.jpg``.\n\nHowever, you may find that the relative URL breaks when the registry is put\ninto production mode. This is because resource merging also changes the URL\nof the stylesheet to be something like::\n\n /plone-site/portal_css/Suburst+Theme/merged-cachekey-1234.css\n\nTo correct for this, you must set the ``applyPrefix`` flag to ``true`` when\ninstalling your CSS resource using ``cssregistry.xml``. There is a\ncorresponding flag in the ``portal_css`` user interface.\n\nIt is sometimes useful to show some of Plone's CSS in the styled site. You\ncan achieve this by using an Diazo ``<after />`` rule or similar to copy the\nCSS from Plone's generated ``<head />`` into the theme. You can use the\n``portal_css`` tool to turn off the style sheets you do not want.\n\nHowever, if you also want the site to be usable in non-themed mode (e.g. on a\nseparate URL), you may want to have a larger set of styles enabled when Diazo\nis not used. To make this easier, you can use the following expressions as\nconditions in the ``portal_css`` tool (and ``portal_javascripts`` if relevant),\nin ``portal_actions``, in page templates, and other places that use TAL\nexpression syntax::\n\n request/HTTP_X_THEME_ENABLED | nothing\n\nThis expression will return True if Diazo is currently enabled, in which case\nan HTTP header \"X-Theme-Enabled\" will be set.\n\nIf you later deploy the theme to a fronting web server such as nginx, you can\nset the same request header there to get the same effect, even if\n``plone.app.theming`` is uninstalled.\n\nUse::\n\n not: request/HTTP_X_THEME_ENABLED | nothing\n\nto 'hide' a style sheet from the themed site.\n\nAdvanced: Disable diazo transformation by setting the ``X-Theme-Disabled`` header\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe diazo transformation is not applied\nif a response header ``X-Theme-Disabled`` is set.\n\nIn a browser view, the header can be set by using this instruction::\n\n self.request.response.setHeader('X-Theme-Disabled', '1')\n\nThis is a complete example::\n\n class NoDiazoView(BrowserView):\n\n def __call__(self):\n self.request.response.setHeader('X-Theme-Disabled', '1')\n return super(NoDiazoView).__call__()\n\nChangelog\n=========\n\n\n.. You should *NOT* be adding new change log entries to this file.\n You should create a file in the news directory instead.\n For helpful instructions, please see:\n https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst\n\n.. towncrier release notes start\n\n5.0.7 (2024-01-18)\n------------------\n\nBug fixes:\n\n\n- Traverse to theme resources from the portal. Fix broken theme when rendering accessible content contained in an inaccessible navigation-root. Fixes #142\n [pbauer] (#142)\n\n\n5.0.6 (2023-12-14)\n------------------\n\nBug fixes:\n\n\n- Fix AttributeError in ``custom.css``: \"module 'wsgiref' has no attribute 'handlers'\".\n [maurits] (#230)\n\n\n5.0.5 (2023-10-07)\n------------------\n\nInternal:\n\n\n- Update configuration files.\n [plone devs] (cfffba8c)\n\n\n5.0.4 (2023-06-22)\n------------------\n\nBug fixes:\n\n\n- Unify default values for translations\n [erral] (#223)\n\n\n5.0.3 (2023-04-06)\n------------------\n\nBug fixes:\n\n\n- Fix theme for `pat-code-editor`.\n [petschki] (#219)\n\n\n5.0.2 (2023-03-22)\n------------------\n\nBug fixes:\n\n\n- Fixes circular dependency on ZCML level to `Products.CMFPlone`:\n Move permission id=`plone.app.controlpanel.Themes` title=`Plone Site Setup: Themes` to this package.\n [jensens] (permission-move)\n\n\nInternal:\n\n\n- Update configuration files.\n [plone devs] (80cf330f)\n\n\n5.0.1 (2023-03-14)\n------------------\n\nBug fixes:\n\n\n- Import more from plone.base.\n Removed compatibility code for Python 2 and Zope 4.\n [maurits] (#1)\n- Bugfix: If there is no rules.xml given in a theme, abort transform early. \n Otherwise, given an open file is given as iterable, the read buffer pointer is empty after this function, but None returned. \n The new way the read buffer pointer is not touched.\n [jensens, toalba] (#216)\n\n\n5.0.0 (2022-12-02)\n------------------\n\nBug fixes:\n\n\n- Final release for Plone 6.0.0. (#600)\n\n\n5.0.0b2 (2022-10-11)\n--------------------\n\nBug fixes:\n\n\n- Fix for `tinymce-styles-css` when copying theme.\n [petschki] (#214)\n\n\n5.0.0b1 (2022-08-31)\n--------------------\n\nBug fixes:\n\n\n- The action buttons in the theming control panel have been improved\n [rohnsha0] (#212)\n\n\n5.0.0a5 (2022-04-04)\n--------------------\n\nNew features:\n\n\n- Deactivate copy button and modal in theming control panel. [MrTango] (#205)\n- Load barceloneta css in theming control panel to have it styled. [MrTango] (#205)\n- Remove all thememapper functionality from theming control panel,\n including Inspect/Modify theme and the Preview. [maurits] (#205)\n- Use pat-code-editor for custom-css field. [MrTango] (#205)\n\n\n5.0.0a4 (2021-11-23)\n--------------------\n\nBug fixes:\n\n\n- Add missing i18n:translate tags\n [erral] (#204)\n\n\n5.0.0a3 (2021-10-13)\n--------------------\n\nBug fixes:\n\n\n- Use HTML5 meta charset.\n [thet] (#203)\n\n\n5.0.0a2 (2021-09-15)\n--------------------\n\nBug fixes:\n\n\n- Fix unclosed file when reading manifest.cfg\n [petschki] (#199)\n- Remove cyclic dependency with Products.CMFPlone\n [sneridagh] (#201)\n\n\n5.0.0a1 (2021-07-26)\n--------------------\n\nBreaking changes:\n\n\n- Add bootstrap icon from resolver from Plone 6.\n [petschki, agitator] (#194)\n\n\nBug fixes:\n\n\n- Avoid Server Side Request Forgery via lxml parser.\n Taken over from `PloneHotfix20210518 <https://plone.org/security/hotfix/20210518/server-side-request-forgery-via-lxml-parser>`_.\n [maurits] (#3274)\n\n\n4.1.6 (2020-11-17)\n------------------\n\nBug fixes:\n\n\n- For increased security, fail when trying file protocol access in diazo rules.\n Also do not resolve entities, and remove processing instructions.\n [maurits] (#3209)\n\n\n4.1.5 (2020-09-26)\n------------------\n\nBug fixes:\n\n\n- Fixed WrongContainedType for hostnameBlackList on Zope 5.\n See also `issue 183 <https://github.com/plone/plone.app.theming/issues/183>`_.\n [maurits] (#183)\n- Fixed deprecation warning for ConfigParser.readfp.\n [maurits] (#3130)\n\n\n4.1.4 (2020-08-14)\n------------------\n\nBug fixes:\n\n\n- Fix a missing import [ale-rt] (#188)\n\n\n4.1.3 (2020-07-30)\n------------------\n\nBug fixes:\n\n\n- Fixes #187: Invalid dependency on plone.app.caching\n [jensens] (#187)\n- Cleanup: Remove meanwhile unused test fixture code referring to ``plone.app.caching``.\n Removed class and fixtures: ``ThemingWithCaching``, ``THEMINGWITHCACHING_FIXTURE``, ``THEMINGWITHCACHING_TESTING``.\n Those were nowhere used active in Plone nor outside in Github.\n [jensens] (#188)\n\n\n4.1.2 (2020-07-01)\n------------------\n\nBug fixes:\n\n\n- Internationalize the Custom CSS placeholder.\n This fixes https://github.com/plone/Products.CMFPlone/issues/3139\n [vincentfretin] (#186)\n\n\n4.1.1 (2020-06-24)\n------------------\n\nBug fixes:\n\n\n- Fix i18n of new messages related to new Custom CSS feature.\n [vincentfretin] (#185)\n\n\n4.1.0 (2020-06-16)\n------------------\n\nNew features:\n\n\n- Insert diazo bundle without rules.\n [santonelli] (#176)\n- Add custom CSS settings and view to theming control panel.\n Depends on https://github.com/plone/Products.CMFPlone/pull/3089\n [MrTango] (#178)\n\n\nBug fixes:\n\n\n- Fix error on Python 3 with nonascii subrequest.\n The subrequest would succeed, but the non-ascii would be ugly.\n Fixes `issue 3069 <https://github.com/plone/Products.CMFPlone/issues/3068>`_ and `issue 162 <https://github.com/plone/plone.app.theming/issues/162>`_.\n [maurits] (#162)\n- Make it possible to preview themes TTW again.\n [petri] (#173)\n- Fix hostnameBlacklist (Theming ControlPanel) in Py3. [MrTango] (#179)\n- Fix various ``WrongType`` exceptions when saving the control panel.\n This was introduced by the ``processInputs`` change in version 4.0.5.\n See `issue 183 <https://github.com/plone/plone.app.theming/issues/183>`_.\n [maurits] (#183)\n\n\n4.0.6 (2020-04-20)\n------------------\n\nBug fixes:\n\n\n- Minor packaging updates. (#1)\n\n\n4.0.5 (2020-03-13)\n------------------\n\nBug fixes:\n\n\n- Do not call ``processInputs``.\n It is not needed since Zope 4, and not existing in Zope 5.\n [maurits] (#171)\n\n\n4.0.4 (2019-12-11)\n------------------\n\nBug fixes:\n\n\n- Fix creating a new theme ttw in py2 with Zope 4.1.3.\n [pbauer] (#166)\n\n\n4.0.3 (2019-10-12)\n------------------\n\nBug fixes:\n\n\n- Load zcml of ``plone.resource`` for our use of the ``plone:static`` directive.\n [maurits] (#2952)\n\n\n4.0.2 (2019-09-13)\n------------------\n\nBug fixes:\n\n\n- Fixed Python3 TypeError: 'filter' object is not subscriptable.\n This happened when overriding a filesystem theme with a TTW version\n [fredvd] (#160)\n\n\n4.0.1 (2019-02-14)\n------------------\n\nBug fixes:\n\n\n- Fix skinname-encoding in py3 (fixes\n https://github.com/plone/Products.CMFPlone/issues/2748) [pbauer] (#2748)\n\n\n4.0.0 (2019-02-13)\n------------------\n\nBreaking changes:\n\n\n- Factor out all static resources into plone.staticresources as part of PLIP\n 1653. [thet, sunew] (#149)\n\n\nBug fixes:\n\n\n- a11y: Added role attribute for portalMessage [nzambello] (#151)\n- Fixed DeprecationWarning about SafeConfigParser class on Python 3. [maurits]\n (#152)\n- Fixed ResourceWarnings for unclosed files in tests. [maurits] (#154)\n- Fixed \"RuntimeError: dictionary changed size during iteration\" [jensens]\n (#156)\n\n\n3.0.1 (2018-12-11)\n------------------\n\nBreaking changes:\n\n- Remove five.globalrequest dependency.\n It has been deprecated upstream (Zope 4).\n [gforcada]\n\n\n3.0.0 (2018-11-02)\n------------------\n\nNew features:\n\n- Recompiled resource bundles with latest mockup.\n [sunew]\n\nBug fixes:\n\n- Explicit load permissions for controlpanel.\n [jensens]\n\n- Fix tests for merged plone.login.\n [jensens]\n\n- More Python 3 fixes\n [ale-rt, pbauer, davisagli]\n\n\n2.0.3 (2018-04-04)\n------------------\n\nBug fixes:\n\n- Added a failing (5.1) test for fileuploads in the theme editor that breaks when plone.rest is installed. Fix is in https://github.com/plone/plone.rest/issues/59\n [djay]\n\n\n2.0.2 (2018-02-04)\n------------------\n\nBug fixes:\n\n- remove mention of non-existent Example theme\n [tkimnguyen]\n\n- Prepare for Python 2 / 3 compatibility\n [pbauer, ale-rt]\n\n\n2.0.1 (2017-07-03)\n------------------\n\nBug fixes:\n\n- Remove unittest2 dependency\n [kakshay21]\n\n\n2.0 (2017-05-24)\n----------------\n\nBreaking changes:\n\n- Let the pattern configuration of the thememapper be in JSON format.\n Fixes problems of thememapper working together with latest patternslib (2.1.0).\n [thet]\n\nBug fixes:\n\n- Fix thememapper pattern handling of buttons (via mockup update).\n Update thememapper bundle.\n [thet]\n\n\n1.3.6 (2017-03-28)\n------------------\n\nBug fixes:\n\n- Reduce log level of ThemingPolicy cache to 'debug'.\n [jensens]\n\n\n1.3.5 (2017-02-12)\n------------------\n\nBug fixes:\n\n- Fix imports from Globals that was removed in Zope4\n [pbauer]\n\n- No longer patch Control Panel internals, as it was removed in Zope4\n [MatthewWilkes]\n\n- reST syntax, styleguide, wording and line length of the docs\n [svx]\n\n1.3.4 (2016-12-30)\n------------------\n\nBug fixes:\n\n- Make diazo.debug work again when DIAZO_ALWAYS_CACHE_RULES is set.\n [ale-rt]\n\n\n1.3.3 (2016-12-02)\n------------------\n\nBug fixes:\n\n- Remove roman monkey patch.\n [gforcada]\n\n1.3.2 (2016-09-23)\n------------------\n\nNew features:\n\n- Add Update -button for theming control panel making it possible to\n reload modified theme manifest without deactivating theme at first.\n [datakurre]\n\n\n1.3.1 (2016-09-07)\n------------------\n\nFixes:\n\n- Enable unload protection by using pattern class ``pat-formunloadalert`` instead ``enableUnloadProtection``.\n [thet]\n\n- Small fix in documentation\n [staeff]\n\n- Fix issue where theming control panel errored when a packaged\n theme was overridden with a global resource directory theme\n [datakurre]\n\n1.3.0 (2016-06-07)\n------------------\n\nNew:\n\n- Control theme compilation in development mode\n through the environment variable ``DIAZO_ALWAYS_CACHE_RULES``\n [ale-rt]\n\nFixes:\n\n- Small fixes to documentation\n [ale-rt]\n\n1.2.19 (2016-03-31)\n-------------------\n\nNew:\n\n- For the theming controlpanel, change base URLs from portal URL to what getSite returns, but don't change the controlpanels context binding.\n This allows for more flexibility when configuring it to be allowed on a sub site with a local registry.\n [thet]\n\n\n1.2.18 (2016-03-03)\n-------------------\n\nFixes:\n\n- Fixed html validation: element nav does not need a role attribute.\n [maurits]\n\n- Handle potential scenarios where wrong theme would show selected in the theming\n control panel\n [vangheem]\n\n\n1.2.17 (2016-02-11)\n-------------------\n\nNew:\n\n- Documented how to disable diazo transform by setting the\n ``X-Theme-Disabled`` header. [ale-rt]\n\nFixes:\n\n- Rebuild resources so they work with latest mockup/patternslib\n integration changes. [vangheem]\n\n- Removed github dependencies in thememapper. [Gagaro]\n\n\n1.2.16 (2015-11-26)\n-------------------\n\nFixes:\n\n- Updated Site Setup link in all control panels.\n Fixes https://github.com/plone/Products.CMFPlone/issues/1255\n [davilima6]\n\n\n1.2.15 (2015-10-28)\n-------------------\n\nFixes:\n\n- Do not fail in ``isThemeEnabled`` when we have no settings, for\n example when migrating from Plone 3 to Plone 5, but maybe also in\n other cases.\n [maurits]\n\n- Fixed Unicode Encode Error when to copy into multi-byte title / description\n [terapyon]\n\n\n1.2.14 (2015-09-27)\n-------------------\n\n- Fix i18n in mapper.pt\n [vincentfretin]\n\n\n1.2.13 (2015-09-20)\n-------------------\n\n- Pull mark_special_links, external_links_open_new_window values\n from configuration registry.\n [esteele]\n\n- Fix visual glitch on Safari\n [davilima6]\n\n- Show active theme at the top of the theme list.\n Fixes https://github.com/plone/plone.app.theming/issues/70\n [tmassman]\n\n\n1.2.12 (2015-09-15)\n-------------------\n\n- Remove bundled twitter bootstrap theme 'example'.\n Fixes https://github.com/plone/Products.CMFPlone/issues/877\n [pbauer]\n\n- Remove duplicate type attribute for theming control panel delete modal.\n [esteele]\n\n\n1.2.11 (2015-09-11)\n-------------------\n\n- rewrite manifest from copied theme with relative paths also\n [vangheem]\n\n\n1.2.10 (2015-09-08)\n-------------------\n\n- theme mapper fixes for odd behavior in save files at times\n [swartz]\n\n\n1.2.9 (2015-08-22)\n------------------\n\n- Build thememapper resources.\n [vangheem]\n\n- Added cache invalidation option.\n [swartz]\n\n\n1.2.8 (2015-08-20)\n------------------\n\n- change link from plone.org to plone.com.\n [tkimnguyen]\n\n- fix toolbar on control panel\n [vangheem]\n\n- fix less building\n [obct537]\n\n- Fixed copy modal for themes with a dot in the name.\n [Gagaro]\n\n\n1.2.7 (2015-07-18)\n------------------\n\n- Provide better styling to themeing control panel, less build, finish implementation\n [obct537]\n\n- make sure when copying themes that you try to modify the base urls\n to match the new theme are all the manifest.cfg settings\n [vangheem]\n\n- implement switchable theming policy API, re-implement theme caching\n [gyst]\n\n- fixed configuration of copied theme\n [vmaksymiv]\n\n- implemented upload for theme manager\n [schwartz]\n\n- Change the category of the configlet to 'plone-general'.\n [sneridagh]\n\n\n1.2.6 (2015-06-05)\n------------------\n\n- removed irrelevant theme renaming code\n [schwartz]\n\n- Filesystem themes are now correctly overridden. TTW themes can no longer be overridden\n [schwartz]\n\n- re-added manifest check\n [schwartz]\n\n- Fixed broken getTheme method\n [schwartz]\n\n- Minor ReStructuredText fixes for documentation.\n [maurits]\n\n\n1.2.5 (2015-05-13)\n------------------\n\n- Fix RestructuredText representation on PyPI by bringing back a few\n example lines in the manifest.\n [maurits]\n\n\n1.2.4 (2015-05-12)\n------------------\n\n- Add setting for tinymce automatically detected styles\n [vangheem]\n\n1.2.3 (2015-05-04)\n------------------\n\n- fix AttributeError: 'NoneType' object has no attribute 'getroottree' when the result is not\n html / is empty.\n [sunew]\n\n- make control panel usable again. Fixed problem where skins\n control panel is no longer present.\n [vangheem]\n\n- unified different getTheme functions.\n [jensens]\n\n- pep8ified, housekeeping, cleanup\n [jensens]\n\n- Specify i18n:domain in controlpanel.pt.\n [vincentfretin]\n\n- pat-modal pattern has been renamed to pat-plone-modal\n [jcbrand]\n\n- Fix load pluginSettings for the enabled theme before calling plugins for\n onEnabled and call onEnabled plugins with correct parameters\n [datakurre]\n\n\n1.2.2 (2015-03-22)\n------------------\n\n- Patch the ZMI only for available ZMI pages.\n [thet]\n\n- Change deprecated import of ``zope.site.hooks.getSite`` to\n ``zope.component.hooks.getSite``.\n [thet]\n\n- Add an error log if the subrequest failed (probably a relative xi:include)\n instead of silently returning None (and so having a xi:include returning\n nothing).\n [vincentfretin]\n\n- Fix transform to not affect the result when theming is disabled\n [datakurre]\n\n- Integrate thememapper mockup pattern and fix theming control panel\n to be more usable\n [ebrehault]\n\n\n1.2.1 (2014-10-23)\n------------------\n\n- Remove DL's from portal message in templates.\n https://github.com/plone/Products.CMFPlone/issues/153\n [khink]\n\n- Fix \"Insufficient Privileges\" for \"Site Administrators\" on the control panel.\n [@rpatterson]\n\n- Add IThemeAppliedEvent\n [vangheem]\n\n- Put themes in a separate zcml file to be able to exclude them\n [laulaz]\n\n- #14107 bot requests like /widget/oauth_login/info.txt causes\n problems finding correct context with plone.app.theming\n [anthonygerrard]\n\n- Added support for ++theme++ to traverse to the contents of the\n current activated theme.\n [bosim]\n\n\n1.2.0 (2014-03-02)\n------------------\n\n- Disable theming for manage_shutdown view.\n [davisagli]\n\n- Fix reference to theme error template\n [afrepues]\n\n- Add \"Test Styles\" button in control panel to expose, test_rendering template.\n [runyaga]\n\n1.1.1 (2013-05-23)\n------------------\n\n- Fixed i18n issues.\n [thomasdesvenain]\n\n- Fixed i18n issues.\n [jianaijun]\n\n- This fixed UnicodeDecodeError when Theme Title is Non-ASCII\n in the manifest.cfg file.\n [jianaijun]\n\n\n1.1 (2013-04-06)\n----------------\n\n- Fixed i18n issues.\n [vincentfretin]\n\n- Make the template theme do what it claims to do: copy styles as\n well as scripts.\n [smcmahon]\n\n- Change the label and description for the example theme to supply useful\n information.\n [smcmahon]\n\n- Upgrades from 1.0 get the combined \"Theming\" control panel that was added in\n 1.1a1.\n [danjacka]\n\n\n1.1b2 (2013-01-01)\n------------------\n\n- Ensure host blacklist utilises SERVER_URL to correctly determine hostname\n for sites hosted as sub-folders at any depth.\n [davidjb]\n\n- Add test about plone.app.theming / plone.app.caching integration when\n using GZIP compression for anonymous\n (see ticket `12038 <https://dev.plone.org/ticket/12038>`_). [ebrehault]\n\n\n1.1b1 (2012-10-16)\n------------------\n\n- Add diazo.debug option, route all error_log output through\n this so debugging can be displayed\n [lentinj]\n\n- Make example Bootstrap-based theme use the HTML5 DOCTYPE.\n [danjacka]\n\n- Demote ZMI patch log message to debug level.\n [hannosch]\n\n- Upgrade to ACE 1.0 via plone.resourceeditor\n [optilude]\n\n- Put quotes around jQuery attribute selector values to appease\n jQuery 1.7.2.\n [danjacka]\n\n1.1a2 (2012-08-30)\n------------------\n\n- Protect the control panel with a specific permission so it can be\n delegated.\n [davisagli]\n\n- Advise defining ajax_load as ``request.form.get('ajax_load')`` in\n manifest.cfg. For instance, the login_form has an hidden empty\n ajax_load input, which would give an unthemed page after submitting\n the form.\n [maurits]\n\n- Change theme editor page templates to use main_template rather than\n prefs_main_template to avoid inserting CSS and JavaScript too early\n under plonetheme.classic.\n [danjacka]\n\n1.1a1 (2012-08-08)\n------------------\n\n- Replace the stock \"Themes\" control panel with a renamed \"Theming\" control\n panel, which incorporates the former's settings under its \"Advanced\" tab.\n [optilude]\n\n- Add a full in-Plone theme authoring environment\n [optilude, vangheem]\n\n- Update IBeforeTraverseEvent import to zope.traversing.\n [hannosch]\n\n- On tab \"Manage themes\", change table header to\n better describe what's actually listed.\n [kleist]\n\n1.0 (2012-04-15)\n----------------\n\n* Prevent AttributeError when getRequest returns None.\n [maurits]\n\n* Calculate subrequests against navigation root rather than portal.\n [elro]\n\n* Supply closest context found for 404 pages.\n [elro]\n\n* Lookup portal state with correct context.\n [elro]\n\n1.0b9 - 2011-11-02\n------------------\n\n* Patch App.Management.Navigation to disable theming of ZMI pages.\n [elro]\n\n1.0b8 - 2011-07-04\n------------------\n\n* Evaluate theme parameters regardless of whether there is a valid context or\n not (e.g. when templating a 404 page).\n [lentinj]\n\n1.0b7 - 2011-06-12\n------------------\n\n* Moved the *views* and *overrides* plugins out into a separate package\n ``plone.app.themingplugins``. If you want to use those features, you need\n to install that package in your buildout. Themes attempting to register\n views or overrides in environments where ``plone.app.themingplugins`` is not\n installed will install, but views and overrides will not take effect.\n [optilude]\n\n1.0b6 - 2011-06-08\n------------------\n\n* Support for setting arbitrary Doctypes.\n [elro]\n\n* Upgrade step to update plone.app.registry configuration.\n [elro]\n\n* Fixed plugin initialization when applying a theme.\n [maurits]\n\n* Query the resource directory using the 'currentTheme' name instead\n of the Theme object (updating the control panel was broken).\n [maurits]\n\n* Fix zip import (plugin initialization was broken.)\n [elro]\n\n1.0b5 - 2011-05-29\n------------------\n\n* Make sure the control panel is never themed, by setting the X-Theme-Disabled\n response header.\n [optilude]\n\n* Add support for registering new views from Zope Page Templates and\n overriding existing templates. See README for more details.\n [optilude]\n\n1.0b4 - 2011-05-24\n------------------\n\n* Add support for ``X-Theme-Disabled`` response header.\n [elro]\n\n* Make \"Replace existing theme\" checkbox default to off.\n [elro]\n\n* Fix control panel to correctly display a newly uploaded theme.\n [elro]\n\n* Fix zip import to work correctly when no manifest is supplied.\n [elro]\n\n1.0b3 - 2011-05-23\n------------------\n\n* Show theme name along with title in control panel.\n [elro]\n\n1.0b2 - 2011-05-16\n------------------\n\n* Encode internally resolved documents to support non-ascii characters\n correctly.\n [elro]\n\n* Fix control panel to use theme name not id.\n [optilude]\n\n1.0b1 - 2011-04-22\n------------------\n\n* Wrap internal subrequests for css or js in style or script tags to\n facilitate inline includes.\n [elro]\n\n* Add ``theme.xml`` import step (see README).\n [optilude]\n\n* Add support for ``[theme:parameters]`` section in ``manifest.cfg``, which\n can be used to set parameters and the corresponding TALES expressions to\n calculate them.\n [optilude]\n\n* Add support for parameter expressions based on TALES expressions\n [optilude]\n\n* Use plone.subrequest 1.6 features to work with IStreamIterator from\n plone.resource.\n [elro]\n\n* Depend on ``Products.CMFPlone`` instead of ``Plone``.\n [elro]\n\n* Added support for uploading themes as Zip archives.\n [optilude]\n\n* Added theme off switch: Add a query string parameter ``diazo.off=1`` to a\n request whilst Zope is in development mode to turn off the theme.\n [optilude]\n\n* Removed 'theme' and alternative themes support: Themes should be referenced\n using the ``<theme />`` directive in the Diazo rules file.\n [optilude]\n\n* Removed 'domains' support: This can be handled with the rules file syntax\n by using the ``host`` parameter.\n [optilude]\n\n* Removed 'notheme' support: This can be handled within the rules file syntax\n by using the ``path`` parameter.\n [optilude]\n\n* Added ``path`` and ``host`` as parameters to the Diazo rules file. These\n can now be used as conditional expressions.\n [optilude]\n\n* Removed dependency on XDV in favour of dependency on Diazo (which is the\n new name for XDV).\n [optilude]\n\n* Forked from collective.xdv 1.0rc11.\n [optilude]\n",
"bugtrack_url": null,
"license": "GPL",
"summary": "Integrates the Diazo theming engine with Plone",
"version": "5.0.7",
"project_urls": {
"Homepage": "https://pypi.org/project/plone.app.theming"
},
"split_keywords": [
"plone",
"diazo",
"xdv",
"deliverance",
"theme",
"transform",
"xslt"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1562a13e7d18374aa376d9b283288c967f4c1ab5344c62d96b756f229b4c8705",
"md5": "a9d8b449a863126e53baeac3a8437041",
"sha256": "1734200299663b673d78a705452ebfae76d1e31cf40045878ddfff1ded454389"
},
"downloads": -1,
"filename": "plone.app.theming-5.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a9d8b449a863126e53baeac3a8437041",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 123403,
"upload_time": "2024-01-18T19:27:55",
"upload_time_iso_8601": "2024-01-18T19:27:55.868746Z",
"url": "https://files.pythonhosted.org/packages/15/62/a13e7d18374aa376d9b283288c967f4c1ab5344c62d96b756f229b4c8705/plone.app.theming-5.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c75e1f9e1bfd1cb61d344a234324b0a9af777dc519ef0fdaa7ec2e1b364a82b9",
"md5": "9e29693d0b18572e9ee142301e20468c",
"sha256": "01d2024af8faa291b024bd98a37e47f22933c93e7a411441a43980fb1783f1b8"
},
"downloads": -1,
"filename": "plone.app.theming-5.0.7.tar.gz",
"has_sig": false,
"md5_digest": "9e29693d0b18572e9ee142301e20468c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 150201,
"upload_time": "2024-01-18T19:27:59",
"upload_time_iso_8601": "2024-01-18T19:27:59.317602Z",
"url": "https://files.pythonhosted.org/packages/c7/5e/1f9e1bfd1cb61d344a234324b0a9af777dc519ef0fdaa7ec2e1b364a82b9/plone.app.theming-5.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-18 19:27:59",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "plone.app.theming"
}
JSON