plone.app.theming 4.1.7

选择主题

要应用现有主题，只需单击主题预览下方的激活按钮。当前活动的主题将以黄色突出显示。如果您停用当前活动的主题，则不会应用重氮主题，即将应用“香草”克隆主题。

注意：主题控制面板永远不会出现，确保您始终可以停用可能导致控制面板无法使用的错误主题。因此，启用主题后您可能不会立即看到任何差异。不过，只需导航到 Plone 站点中的另一个页面，您应该会看到应用的主题。

创建新主题

可以通过以下两种方式之一创建新主题：

• 单击主题控制面板中主题选项卡顶部的新建主题按钮，然后 在出现的表单中输入标题和描述。将创建一个基本主题，您将被带到修改主题屏幕（见下文），您可以在其中编辑或创建主题和规则文件。

• 单击任何现有主题下方的复制按钮，然后在出现的表单中输入标题和描述。将创建一个新主题作为现有主题的副本，您将被带到修改主题（见下文），您可以在其中编辑或创建主题和规则文件。

上传现有主题

主题可以作为 Zip 文件分发，包含 HTML 模型和规则文件。要下载现有主题，请单击主题控制面板的主题选项卡上主题下方的下载按钮。

要将此类 Zip 文件上传到另一个站点，请使用主题控制面板的主题选项卡上的上传 Zip 文件按钮。您可以选择是否替换任何具有相同名称的现有主题（基于 Zip 文件中包含的顶级目录的名称）。

您还可以上传不包含规则文件的静态 HTML 模型的 Zip 文件，例如与 Plone 无关的网页设计师提供的设计。

在这种情况下，将添加一个基本的rules.xml文件，以便您使用“修改主题”屏幕开始构建主题（见下文）。生成的规则文件将假定主 HTML 模型文件名为 index.html，但您可以在rules.xml中更改它。

成功上传主题 Zip 文件后，您将进入 修改主题屏幕（见下文），您可以在其中编辑或创建主题文件。

提示：如果您收到“上传的文件不包含有效的主题存档”之类的错误消息，这通常意味着您上传的 Zip 文件包含多个文件和文件夹，而不是包含所有主题的单个顶级文件夹里面的资源。如果您通过将其文件和文件夹直接添加到 Zip 存档而不是压缩找到它们的目录来压缩主题或 HTML 模型，则可能会发生这种情况。要解决此问题，只需将计算机上的存档解压缩到一个新目录中，向上移动一个级别，然后将该目录自己压缩为一个新的 Zip 文件，然后您可以上传该文件。

修改主题

您可以通过在主题控制面板的主题选项卡中单击主题下方的修改主题来 修改主题。当您创建或上传新主题时，此屏幕也会自动启动。

注意：只有通过Theming控制面板创建或上传的主题才能通过 Plone 进行修改。由第三方插件安装或分布在文件系统上的主题不能，尽管如果 Zope 在调试模式下运行，文件系统上所做的更改将立即反映。要修改文件系统主题，您可以通过单击主题控制面板中主题下方的复制按钮将其复制到新的 in - Plone 主题。

修改主题屏幕最初显示一个文件管理器，左侧是文件树，右侧是编辑器。单击文件树中的文件打开编辑器或预览：HTML、CSS、JavaScript 和其他文本文件可以直接通过编辑器进行编辑。其他文件（例如图像）将呈现为预览。

注意：带有语法突出显示的高级编辑器在 Microsoft Internet Explorer 中不可用。

单击新建文件夹以创建新文件夹。您还可以右键单击文件树中的文件夹以调出此操作。

单击新建文件以创建新的文本文件。您还可以右键单击文件树中的文件夹以调出此操作。

单击上传文件以从您的计算机上传文件。您也可以右键单击文件树中的文件夹来调出此操作。

单击预览主题以预览主题，因为它将与当前保存的模型和规则一起应用。预览是可导航的，但表单和某些高级功能将不起作用。

要保存当前正在编辑的文件，请单击保存文件按钮，或使用键盘快捷键Ctrl+S (Windows/Linux) 或Cmd+S (Mac)。

要重命名或删除文件或文件夹，请在文件树中右键单击它并选择适当的操作。

主题检查员

主题检查器提供了用于发现和建立重氮主题规则的高级界面。它可以通过单击In-Plone 主题的修改主题屏幕上的显示检查器按钮来启动，或者通过单击主题控制面板的主题选项卡上文件系统主题下的检查主题按钮来启动 。

主题检查器由两个面板组成：

• HTML模型。如果主题中有多个 HTML 文件，您可以使用HTML 模型面板下方的下拉列表在它们之间切换。

• 无主题的内容。这显示了没有应用任何主题的 Plone。

通过单击任一面板右上角的箭头图标，可以最大化任一面板。

HTML 模型和Unthemed内容面板可以切换到源视图，显示它们的底层 HTML 标记，方法是单击它们右上角的标签图标。

当您将鼠标悬停在HTML 模型或非主题内容面板中的元素上时，您将看到：

• 显示光标下元素的轮廓。

• 如果面板将在重氮规则中唯一标识此元素，则底部状态栏中的 CSS 或 XPath 选择器。

单击一个元素或在将鼠标悬停在一个元素上方时按Enter以选择它。每个面板中最近选择的元素显示在相关状态栏的右下角。

将鼠标悬停在元素上时按Esc以选择其父元素。这在尝试选择“不可见”的容器元素时很有用。按Enter 保存此选择。

可以导航HTML 模型的内容或（更常见的）非主题内容面板，例如，通过禁用检查器来访问需要特定主题规则的内容页面。使用相关面板右下方的切换开关来启用或禁用选择器。

规则构建器

单击修改主题或检查主题屏幕顶部附近的构建规则按钮以启动交互式规则构建向导。系统将询问您要构建哪种类型的规则，然后提示您根据需要在HTML 模型和/或非主题内容面板中选择相关元素。默认情况下，这将使用任何已保存的选择，除非您在向导的第一页上取消选中使用选定元素框。

向导完成后，您将看到生成的规则。如果你愿意，你可以编辑它。如果单击Insert，新生成的规则将被插入到rules.xml编辑器中当前光标位置或附近。您可以随意移动它或进一步编辑它。

单击预览主题以在新选项卡或窗口中预览主题。如果您进行了更改，请不要忘记保存rules.xml文件。

注意：在只读模式下，您可以构建规则并检查 HTML 模型和主题，但不能更改rules.xml文件。在这种情况下，规则构建器的插入按钮（见下文）也将不可用。

注意： Microsoft Internet Explorer 中不提供从构建规则向导插入规则的功能，但在使用此浏览器时，您可以选择将规则复制到剪贴板。

高级设置

Theming控制面板还包含一个名为Advanced settings的选项卡。这里是龙。

高级设置选项卡分为两个区域。第一个，主题详细信息，包含从主题控制面板应用主题时修改的基础设置。这些是：

• 是否启用了重氮主题。

• 规则文件的路径，通常称为rules.xml，相对于 Plone 站点根目录或外部服务器的绝对路径。

• 在渲染时将主题中的相对路径（例如对<img />标签的src属性中的图像的引用）转换为绝对路径时应用的前缀。

• 应用于渲染输出 的 HTML DOCTYPE ，如果与默认的XHTML 1.0 Transitional不同。

• 是否允许从网络中读取主题资源（如rules.xml ）。禁用此功能可适度提升性能。

• 从未应用主题的主机名列表。最常见的是，它包含127.0.0.1，例如，在开发过程中，您可以通过 http://127.0.0.1:8080查看非主题站点，并在http://localhost:8080查看主题站点。

• 主题参数列表和生成它们的 TALES 表达式（见下文）。

第二个，Theme base，控制非主题内容的呈现，即使没有应用 Diazo 主题也可以应用。这些是以前版本的 Plone的主题控制面板中的设置。

部署和测试主题

要构建和测试主题，您必须首先创建所需外观的静态 HTML 模型，然后构建规则文件来描述 Plone 的内容如何映射到此模型中的占位符。

可以使用任何您觉得最适合构建网页的工具在任何地方创建模型。为了简化与 Plone 的集成，建议您确保它使用 CSS、JavaScript 和图像文件等资源的相对链接，以便正确呈现从本地文件在 Web 浏览器中打开时。Plone 会自动将这些相对链接转换为适当的绝对路径，确保在将主题应用于 Plone 站点时，无论用户正在查看哪个 URL，主题都能正常工作。

有几种方法可以将主题放入 Plone：

1. 在文件系统上

   如果您使用安装程序或标准“构建”来设置您的 Plone 站点，您应该在 Plone 安装的根目录中有一个名为resources的目录（这是使用构建 配方plone.recipe.zope2instance的资源选项 创建的。有关更多详细信息，请参阅 http://pypi.python.org/pypi/plone.recipe.zope2instance。）

   您可以在此目录中找到（或创建）一个主题目录，该目录用于包含主题。每个主题都需要自己的目录，并具有唯一的名称。创建一个（例如resources/theme/mytheme）并将您的 HTML 文件和任何引用资源放在此目录中。如果您愿意，可以使用子目录，但建议您将基本主题 HTML 文件保留在主题目录的顶部。

   您还需要在此目录中创建一个名为rules.xml的规则文件。如果您还没有，请从一个空的开始：

   <?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>

   如果您在调试模式下运行 Zope（例如，您使用bin/instance fg启动它），对主题和规则的更改应该立即生效。您可以通过Themes控制面板预览或启用主题，然后根据需要迭代修改 rules.xml文件或主题模型。

2. 通过网络

   如果您喜欢（或没有文件系统访问权限），您可以完全通过 Plone 控制面板创建主题，方法是复制现有主题，或者从零开始使用近乎空的主题。

   有关更多详细信息，请参阅上面有关使用控制面板的说明。

   创建主题后，您可以通过 主题控制面板对其进行修改。有关更多详细信息，请参见上文。

3. 作为 zip 文件

   主题可以从 Plone 下载为 Zip 文件，然后可以上传到其他站点。

   有关更多详细信息，请参阅上面有关使用控制面板的说明。

   事实上，您可以通过使用标准压缩工具（如7-Zip或Winzip （适用于 Windows）或Mac OS X Finder 中的内置 压缩操作）压缩文件系统上的主题目录来创建有效的主题 zip 存档。只需确保您压缩了一个包含所有主题文件和rules.xml文件的文件夹。（不要直接压缩文件夹的内容：解压后，zip 文件应该只生成一个文件夹，该文件夹又包含所有相关文件）。

4. 在 Python 包中（仅限程序员）

   如果您正在创建一个 Python 包，其中包含您打算安装到您的站点中的 Plone 定制，您可以让它注册一个主题以安装到站点中。

   为此，在包的顶部，Zope configure.zcml文件旁边放置一个名为例如theme的目录，并将 <plone:static />声明添加到configure.zcml文件：

   <configure
       xmlns:plone="http://namespaces.plone.org/plone"
       xmlns="http://namespaces.zope.org/zope">
   
       ...
   
       <plone:static name="mytheme" directory="theme" type="theme" />
   
       ...
   
   </configure>

   注意根 <configure />元素中plone命名空间的声明。将主题文件和 rules.xml文件放入主题目录。

   如果您的包有一个 GenericSetup 配置文件，您可以在安装此配置文件时自动启用主题，方法是 在配置文件/默认目录中添加一个theme.xml文件，其中包含例如：

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

清单文件

可以通过在主题目录顶部的rules.xml文件旁边放置一个名为manifest.cfg的文件来提供有关主题的其他信息。

该文件可能如下所示：

[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/less/barceloneta.plone.less
production-css = /++theme++barceloneta/less/barceloneta-compiled.css
development-js = /++theme++barceloneta/barceloneta.js
production-js = /++theme++barceloneta/barceloneta.min.js
tinymce-content-css = /++theme++barceloneta/tinymce-styles.css

如此处所示，清单文件可用于为主题提供更友好的标题和更长的描述，以便在控制面板中使用。只有[theme]标头是必需的 - 所有其他键都是可选的。

清单设置：

规则

使用与rules.xml不同的规则文件名（您应该提供 URL 或相对路径）。

字首

要更改绝对路径前缀（请参阅高级设置），请使用：

prefix = /some/prefix

文档类型

要在XHTML 1.0 Transitional以外的主题内容中使用DOCTYPE，请添加例如：

doctype = <!DOCTYPE html>

预习

在主题控制面板中提供用户友好的主题预览。这里，preview.png是相对于 manifest.cfg文件位置的图像文件：

preview = preview.png

启用包

激活主题时将自动启用的捆绑包

禁用捆绑

激活主题时将自动禁用的捆绑包

开发-CSS

CSS 在开发模式和主题处于活动状态时自动包含

开发-js

当主题处于活动状态时，在开发模式下自动包含的 JavaScript 文件

生产-CSS

当主题处于活动状态并处于生产模式时自动包含 CSS

生产-js

当主题处于活动状态并处于生产模式时自动包含 JavaScript

tinymce 内容 css

应加载 CSS 文件 tinymce 以将样式应用于编辑器内的内容

tinymce 样式-css

应加载 CSS 文件 tinymce 以在编辑器中额外提供自动检测到的下拉样式

对重氮主题引擎的扩展可以添加对其他可配置参数块的支持。

规则语法

以下是重氮规则语法的简短摘要。有关更多详细信息和更多示例，请参见 http://diazo.org。

<rules>
    ...
</rules>

<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 href="theme.html" />
<theme href="news.html" if-path="/news" />
<notheme if="$host = 'admin.example.org'" />

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

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

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

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

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

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

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

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

<replace css:content="#portal-searchbox input.searchButton">
    <button type="submit">
        <img src="images/search.png" alt="Search" />
    </button>
</replace>

<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>

<!-- Pull in extra navigation from a browser view on the Plone site root -->
<after
    css:theme-children="#leftnav"
    css:content=".navitem"
    href="/@@extra-nav"
    />

主题参数

可以将任意参数传递给您的主题，这些参数可以作为 XPath 表达式中的变量进行引用。参数可以在 Plone 的主题控制面板中设置，并且可以从manifest.cfg文件中导入。

例如，您可以将参数模式设置为字符串live或test。在您的规则中，当您在测试服务器上时，您可以执行以下操作来插入警告：

<before css:theme-children="body" if="$mode = 'test'">
    <span class="warning">Warning: This is the test server</span>
</before>

您甚至可以直接使用参数值，例如：

<before css:theme-children="body">
    <span class="info">This is the <xsl:value-of select="$mode" /> server</span>
</before>

以下参数始终可用于 Plone 主题：

方案

入站 URL 的方案部分，通常是http或https。

主持人

入站 URL 中的主机名。

小路

入站 URL 的路径段。这将不包括任何虚拟主机令牌，即它是最终用户看到的路径。

根据

Zope 基本 url（BASE1请求变量）。

您可以使用 TALES 表达式通过控制面板添加其他参数。参数列在高级选项卡上，每行一个，格式为<name> = <expression>。

例如，如果您想避免对 Plone 的覆盖加载的任何页面进行主题化，您可以使用他们设置的ajax_load请求参数。您的规则文件可能包括：

<notheme if="$ajax_load" />

要添加此参数以及前面概述的模式参数，您可以在控制面板中添加以下内容：

ajax_load = python: request.form.get('ajax_load')
mode = string: test

右手边是一个 TALES 表达式。它必须评估为字符串、整数、浮点数、布尔值或无：不支持列表、字典和对象。python:、string:和路径表达式的工作方式与 Zope 页面模板中的一样。

构建这些 TALES 表达式时，可以使用以下变量：

语境

当前请求的上下文，通常是一个内容对象。

要求

当前请求。

门户网站

门户根对象。

上下文状态

@@plone_context_state视图，您可以从中查找其他值，例如上下文的 URL 或默认视图。

门户状态

@@plone_portal_state视图，您可以在其中查找其他值，例如导航根 URL 或当前用户是否登录。

有关@@plone_context_state和 @@plone_portal_state视图的详细信息，请参阅plone.app.layout 。

主题参数通常是主题的组成部分，因此在导入或启用主题时将根据主题的清单进行设置。这是使用manifest.cfg文件中的[theme:parameters]部分完成的。例如：

[主题]
标题 = 我的主题
描述 = 一个测试主题

[主题：参数]
ajax_load = python: request.form.get('ajax_load')
mode = string: test

主题调试

当 Zope 处于开发模式时（例如，在控制台中使用bin/instance fg在前台运行），主题将在每个请求时重新编译。在非开发模式下，第一次访问时编译一次，然后只重新编译控制面板值改变。

此外，在开发模式下，可以通过附加查询字符串参数diazo.off=1来临时禁用主题。例如：

http://localhost:8080/Plone/some-page?diazo.off=1

最后，您可以获得一个包含规则的叠加层，并标注条件与主题和文档匹配的次数。绿色表示条件匹配，红色表示不匹配。只要其中的所有条件都是绿色的，整个规则标签就会是绿色的（即它有效果）。

要启用此功能，请附加diazo.debug=1。例如：

http://localhost:8080/Plone/some-page?diazo.debug=1

该参数在非开发模式下被忽略。

常用规则

以下配方说明了构建 Plone 主题中常用的规则：

要复制页面标题：

<replace css:theme="title" css:content="title" />

要复制<base />标签（Plone 的链接工作所必需的）：

<replace css:theme="base" css:content="base" />

如果主题中没有<base />标签，你可以这样做：

<before css:theme-children=”head” css:content=”base” />

要从主题中删除所有样式和 JavaScript 资源并从 Plone 的portal_css工具中复制它们：

<!-- 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" />

复制 Plone 的 JavaScript 资源：

<!-- Pull in Plone CSS -->
<after theme-children="/html/head" content="/html/head/script" />

要复制<body />标签的类（某些 Plone JavaScript 函数和样式正常工作所必需的）：

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

进阶：使用 portal_css 管理你的 CSS

Plone 的“资源注册表”，包括portal_css工具，可用于管理CSS 样式表。与简单地链接到模板中的样式表相比，这提供了几个优点，例如：

• 对样式表顺序的详细控制

• 合并样式表以减少渲染页面所需的下载次数

• 即时样式表压缩（例如空格删除）

• 基于表达式包含或排除样式表的能力

保持主题文件不变通常是可取的（有时是完全必要的），但您仍然可以使用portal_css来管理您的样式表。诀窍是：

• 使用 Plone 的portal_css工具注册您的主题样式（这通常最好在您在 Python 包中发布主题时完成 - 目前无法为从 Zip 文件导入或通过网络创建的主题自动执行此操作）

• 使用规则删除主题的样式，然后

• 包括来自 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" />

after />规则中对内容使用“或”表达式意味着保持链接和样式元素的相对顺序。

要在使用 GenericSetup 安装产品时注册样式表，请使用 GenericSetup配置文件/默认 目录中的cssregistry.xml导入步骤：

<?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>

然而，有一个重要的警告。您的样式表可能包含以下形式的相对 URL 引用：

背景图片：网址（../images/bg.jpg）；

如果您的样式表位于资源目​​录中（例如，它在 portal_css中注册， id 为++theme++my.theme/css/styles.css），只要注册表（和 Zope）处于调试状态，这将正常工作模式。浏览器将相对 URL 解析为 ++theme++my.theme/images/bg.jpg。

但是，当注册表进入生产模式时，您可能会发现相对 URL 中断。这是因为资源合并还会将样式表的 URL 更改为：

/plone-site/portal_css/Suburst+Theme/merged-cachekey-1234.css

要更正此问题，您必须在使用cssregistry.xml安装 CSS 资源时将applyPrefix标志设置为true。在portal_css用户界面中有一个相应的标志。

在样式化站点中显示一些 Plone 的 CSS 有时很有用。您可以通过使用 Diazo <after />规则或类似规则将 Plone 生成的<head />中的 CSS 复制到主题中来实现此目的。您可以使用 portal_css工具来关闭您不需要的样式表。

但是，如果您还希望站点在非主题模式下可用（例如，在单独的 URL 上），您可能希望在不使用 Diazo 时启用更大的样式集。为了使这更容易，您可以在portal_css工具（和portal_javascripts，如果相关）、portal_actions、页面模板和其他使用 TAL 表达式语法的地方使用以下表达式作为条件：

request/HTTP_X_THEME_ENABLED | nothing

如果当前启用了 Diazo，此表达式将返回 True，在这种情况下，将设置 HTTP 标头“X-Theme-Enabled”。

如果您稍后将主题部署到前端 Web 服务器（例如 nginx），您可以在那里设置相同的请求标头以获得相同的效果，即使 plone.app.theming已卸载。

利用：

不是：request/HTTP_X_THEME_ENABLED | nothing

从主题站点“隐藏”样式表。

高级：通过设置X-Theme-Disabled标头禁用重氮转换

如果设置了响应头X-Theme-Disabled，则不应用重氮转换。

在浏览器视图中，可以使用以下指令设置标题：

self.request.response.setHeader('X-Theme-Disabled', '1')

这是一个完整的例子：

class NoDiazoView(BrowserView):

    def __call__(self):
        self.request.response.setHeader('X-Theme-Disabled', '1')
        return super(NoDiazoView).__call__()