Metadata-Version: 1.1
Name: plone.app.theming
Version: 1.0.1
Summary: Integrates the Diazo theming engine with Plone
Home-page: http://pypi.python.org/pypi/plone.app.theming
Author: Martin Aspeli and Laurence Rowe
Author-email: optilude@gmail.com
License: GPL
Description: ============
        Introduction
        ============
        
        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>`_.
        
        This version of ``plone.app.theming`` ships with Plone version 4.3 or later.
        It comes with a user guide, reproduced below, avaialble through the theming
        control panel.
        
        
        Diazo theming
        =============
        
        This guide provides an overview of Diazo theming in Plone.
        
        .. contents:: Contents
            :local:
        
        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 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
        -----------------------
        
        TODO
        
        Selecting a theme
        ~~~~~~~~~~~~~~~~~
        
        TODO: Describe how to enable a theme in the control panel
        
        Creating a new theme
        ~~~~~~~~~~~~~~~~~~~~
        
        TODO: Describe actions: cloning and creating anew
        
        Uploading an existing theme
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        TODO: Describe uploading a theme - with or without rules.xml file to start with
        
        The file manager
        ~~~~~~~~~~~~~~~~
        
        TODO: Describe purpose and UI
        
        The rule builder
        ~~~~~~~~~~~~~~~~
        
        TODO: Describe purpose and UI - filesystem and ZODB themes
        
        Advanced settings
        ~~~~~~~~~~~~~~~~~
        
        TODO: Describe the available settings at a high level
        
        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.
        
        TODO: Describe specific UI to do this
        
        Once a theme has been created, you can modify it through the in-Plone theme
        file manager or rule builder. See below 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.
        
        TODO: Describe specific UI to do this
        
        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
        
        As shown here, the manifest file can be used to provide a more user friendly
        title and a longer description for the theme, for use in the control panel.
        Only the ``[theme]`` header is required - all other keys are optional.
        
        You can also set::
        
            rules = myrules.xml
        
        to use a different rule file name than ``rules.xml``, and::
        
            prefix = /some/prefix
        
        to change the absolute path prefix (see *Advanced settings*).
        
        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-condition="#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::
        
            <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
        
        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 Pyton 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.
        
        
        Changelog
        =========
        
        1.0.1 (2012-08-18)
        ------------------
        
        - 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]
        
        - 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]
        
Keywords: plone diazo xdv deliverance theme transform xslt
Platform: UNKNOWN
Classifier: Framework :: Plone
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Libraries :: Python Modules
