collective.xdv 1.0rc11

安装

collective.xdv 依赖于

• plone.transformchain 以将转换钩入发布者

• plone.registry 和 plone.app.registry 以管理设置

• plone.autoform、plone.z3cform 和 plone.app.z3cform 以渲染控制面板

• five.globalrequest 和 zope.globalrequest 用于内部请求访问

• XDV，包含XDV本身

• lxml 执行最终转换

如果您使用 zc.buildout 并遵循安装说明，这些都将自动安装。

要将 collective.xdv 安装到您的 Plone 实例中，在文件系统中找到您的 Plone 实例目录根目录中的 buildout.cfg 文件，并使用文本编辑器打开它。找到类似以下内容的部分

# extends = http://dist.plone.org/release/3.3/versions.cfg
extends = versions.cfg
versions = versions

它也可能在“extends”部分有一个 URL，类似于取消注释的第一行，这取决于您是从网络还是本地拉取 Plone 配置。

要将 collective.xdv 添加到我们的设置中，我们需要一些不同版本的几个包，因此我们使用 good-py 服务的版本列表扩展基本配置，因此更改配置的这一部分，使其看起来像这样

extends =
    versions.cfg
    http://good-py.appspot.com/release/collective.xdv/1.0?plone=3.3.5
versions = versions

注意，上述 URL 的最后一部分在?之前是 xdv 版本号。在您阅读此内容时可能会有更新的版本，因此请查看概述页面以获取已知的好版本集。

将?plone=3.3.5替换为您正在使用的 Plone 版本。这将根据您的 Plone 选择适当的依赖版本。

这里发生的情况是，collective.xdv 的依赖列表通过 good-py URL 为您指定了一些新版本。这样，您不必担心获取正确的版本，Buildout 会为您处理。

下一步是将实际的 collective.xdv 扩展程序添加到 buildout.cfg 的“eggs”部分。查找类似以下内容的部分

eggs =
    Plone

如果您已经安装了其他扩展程序，此部分可能还有其他行。只需将 collective.xdv 在单独的一行上添加，如下所示

eggs =
    Plone
    collective.xdv [Zope2.10]

注意使用了 [Zope2.10] 额外选项，它将 ZPublisherEventsBackport 包引入以与 Zope 2.12/Plone 4 保持向前兼容性。如果您正在使用 Zope 2.12 或更高版本（例如，与 Plone 4 一起使用），则应执行以下操作

eggs =
    Plone
    collective.xdv

请注意，不需要添加 ZCML slug，因为 collective.xdv 使用 z3c.autoinclude 来自动配置自己。

一旦您已将此行添加到配置文件中，现在是时候运行 buildout，以便系统为您添加和设置 collective.xdv。转到命令行，并从您的 Plone 实例根目录（与 buildout.cfg 所在的目录相同）运行 buildout，如下所示

$ bin/buildout

您将看到类似于以下内容的输出

Getting distribution for 'collective.xdv==1.0'.
Got collective.xdv 1.0.
Getting distribution for 'plone.app.registry'.
Got plone.app.registry 1.0a1.
Getting distribution for 'plone.synchronize'.
Got plone.synchronize 1.0b1.
...

如果一切按计划进行，现在您已经在您的 Zope 实例中安装了 collective.xdv。

接下来，启动 Zope，例如使用以下命令

$ bin/instance fg

然后以管理员身份进入Plone中的“插件”控制面板，安装“XDV主题支持”产品。此时您应该会在Plone站点的设置中注意到一个新的“XDV主题”控制面板。

使用

在“XDV主题”控制面板中，您可以设置以下选项

启用/禁用

是否启用转换。

域名

将匹配HOST头以确定是否应用主题的域名列表（包括端口）。请注意，127.0.0.1永远不会被样式化，以确保始终有方法回到Plone来更改这些设置。然而，“localhost”应该可以正常工作。

主题

指向主题文件的文件路径或URL。这只是一个静态HTML文件。

规则

规则XML文件的文件系统路径。

备用主题

备用主题和规则文件的路径定义列表。应采用“路径 主题 规则”的形式，其中路径可以使用正则表达式语法，主题是主题模板的文件路径或URL，规则是规则文件的文件路径。如果主题或规则字符串以“python://”开头，则执行路径解析，例如，您可以引用主题包中的主题文件，如python://yourtheme.xdvtheme/static/page.html。

XSLT扩展文件

可以扩展XDV以自定义XSLT文件。如果您有此类文件，请在此处提供其URL。

绝对前缀

如果提供，则主题HTML文件中的任何相对URL（在<img>、<link>、<style>或<script>标签中）在编译主题时将被此URL片段前缀。这使得在文件系统上使用相对路径来开发主题HTML/CSS变得更容易，同时这些路径在服务器上的任何URL上仍然有效。

无样式路径

用于提供不会在启用XDV的情况下进行样式的页面URL模式列表（使用正则表达式语法）。默认情况下，这包括对于Kupu编辑器必要且用于ZMI的manage_*页面，即“emptypage”视图。

请注意，当Zope处于调试模式时，主题将在每次请求时重新编译。在非调试模式下，它将在启动时编译一次，并且只有在控制面板值更改时才会重新编译。

``python://my.package/mytheme/rules.xml``

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

    ...

    <browser:resourceDirectory
        name="my.package"
        directory="mytheme"
        />

    ...

</configure>

https://127.0.0.1:8080/Plone/++resource++my.package/theme.html

<drop theme="/html/head/link" />
<drop theme="/html/head/style" />

<!-- Pull in Plone CSS -->
<append theme="/html/head" content="/html/head/link | /html/head/style" />

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

request/HTTP_X_XDV | nothing

not: request/HTTP_X_XDV | nothing

工作示例

设置XDV主题的方式有很多。例如，您可以将主题和规则作为Plone中的内容上传，并使用绝对路径来配置它们。您也可以从单独的静态Web服务器提供它们，甚至从文件系统加载它们。

但是，要创建可部署的主题，通常最好创建一个简单的Python包。这也为与主题相关的自定义（如模板覆盖）提供了一个自然的家。

尽管详细的教程超出了本帮助文件的范畴，但下面展示了一个简短的、实际操作的示例。

1. 创建一个包并将其安装到您的buildout中

   $ cd src
   $ paster create -t plone my.theme

有关详细信息，请参阅buildout手册

如果您安装了较新的ZopeSkel，这应该会工作。选择easy模式。当被问及是否要注册配置文件时，请回答“是”。

然后编辑buildout.cfg，将您的新包（如上例中的my.theme）添加到develop和eggs列表中。

2. 编辑新创建的包中的setup.py

install_requires列表应该是

install_requires=[
      'setuptools',
      'collective.xdv',
  ],

重新运行buildout

$ bin/buildout

3. 编辑新创建的包中的configure.zcml

在<configure />标签内添加资源目录。注意，您可能需要添加如上所示的browser命名空间。

<configure

xmlns=”http://namespaces.zope.org/zope” xmlns:browser=”http://namespaces.zope.org/browser” xmlns:i18n=”http://namespaces.zope.org/i18n” xmlns:genericsetup=”http://namespaces.zope.org/genericsetup” i18n_domain=”my.theme”>

<genericsetup:registerProfile

name=”default” title=”my.theme” directory=”profiles/default” description=”Installs the my.theme package” provides=”Products.GenericSetup.interfaces.EXTENSION” />

<browser:resourceDirectory

name=”my.theme” directory=”static” />

</configure>

在此处，我们使用了包名my.theme作为资源目录的名称。根据需要调整。

4. 在configure.zcml旁边添加一个static目录。

5. 将您的主题和规则文件放在这个目录中。

例如，您可能有一个引用子目录images/中的图片和子目录css/中的样式表的theme.html。将此文件和两个目录放在新创建的static目录中。

确保主题使用相对URL（例如，<img src="images/foo.jpg" />）来引用其资源。这意味着您可以从文件系统打开主题并查看其华丽之处。

还放置一个rules.xml文件。有关其语法的详细信息，请参阅XDV文档。如果您只想测试，可以开始使用一些非常简单的规则。

<?xml version="1.0" encoding="UTF-8"?>
<rules
    xmlns="http://namespaces.plone.org/xdv"
    xmlns:css="http://namespaces.plone.org/xdv+css">

    <!-- Head: title -->
    <replace theme="/html/head/title" content="/html/head/title" />

    <!-- Base tag -->
    <replace theme="/html/head/base" content="/html/head/base" />

    <!-- 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 -->
    <append theme="/html/head" content="/html/head/link | /html/head/style " />

</rules>

这些规则将引入<title/>标签（即浏览器窗口的标题）、<base/>标签（某些Plone URL正常运行所必需的），以及Plone的样式表。

下面有一些更有用的规则。

6. 创建安装配置文件

上面为<genericsetup:registerProfile/>标签生成的代码包含对目录profiles/default的引用。如果它尚未存在，您可能需要将其创建在configure.zcml旁边，即创建一个新的目录profiles，并在其中创建另一个目录default。

在这个目录中，添加一个名为metadata.xml的文件，包含以下内容

<metadata>
    <version>1</version>
    <dependencies>
        <dependency>profile-collective.xdv:default</dependency>
    </dependencies>
</metadata>

这将在我.theme通过附加控件面板安装时将collective.xdv安装到Plone中。

此外，创建一个名为registry.xml的文件，内容如下

<registry>

    <!-- collective.xdv settings -->

    <record interface="collective.xdv.interfaces.ITransformSettings" field="domains">
        <value>
            <element>domain.my:8080</element>
        </value>
    </record>

    <record interface="collective.xdv.interfaces.ITransformSettings" field="rules">
        <value>python://my.theme/static/rules.xml</value>
    </record>

    <record interface="collective.xdv.interfaces.ITransformSettings" field="theme">
        <value>python://my.theme/static/theme.html</value>
    </record>

    <record interface="collective.xdv.interfaces.ITransformSettings" field="absolute_prefix">
        <value>/++resource++my.theme</value>
    </record>

</registry>

将my.theme替换为您自己的包名，并根据需要将rules.xml和theme.html替换为适当的内容。

此文件配置了XDV控件面板背后的设置。

提示：如果您已经玩过控件面板并想要导出设置，您可以在ZMI中的portal_setup工具中创建一个快照。检查创建的registry.xml文件，并挑选出与collective.xdv相关的记录。您应该从导出中删除<field/>标签，这样您就只剩下如上所示<record/>和<value/>标签。

此外，在profiles/default目录中添加一个cssregistry.xml以配置portal_css工具

<?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_XDV | nothing"
     id="public.css"
     />

 <!-- Add new stylesheets -->
 <!-- Note: applyPrefix is not available in Plone < 4.0b3 -->

 <stylesheet title="" authenticated="False" cacheable="True"
    compression="safe" conditionalcomment="" cookable="True" enabled="on"
    expression="request/HTTP_X_XDV | nothing"
    id="++resource++my.theme/css/styles.css" media="" rel="stylesheet"
    rendering="link"
    applyPrefix="True"
    />

</object>

这展示了如何对现有的样式表设置条件，以及如何注册一个新的样式表。我们在这里将applyPrefix设置为True，如上所述。这仅在Plone 4.b3及更高版本中有效。对于早期版本，只需将其删除即可。

7. 测试

启动Zope并访问您的Plone站点。您的新包应显示在附加产品控件面板中的可安装状态。安装后，它应将collective.xdv作为依赖项安装，并预先配置它使用您的主题和规则集。默认情况下，主题是禁用的，因此您需要前往控件面板将其打开。

您现在可以通过以下URL比较您未修改的主题、未加样式的Plone站点和加样式的站点

• https://127.0.0.1:8080（或您已配置为样式化域的任何内容）用于样式化的Plone。如果您使用了上面的示例规则，这将几乎与您的主题完全相同，但<title/>标签（通常显示在您的网络浏览器标题栏中）取自Plone。

• http://127.0.0.1:8080（假设这是Plone运行的端口）用于未加样式的Plone。

• https://127.0.0.1:8080/++resource++my.theme/theme.html用于原始主题。这是一个静态资源，几乎就像它是在文件系统中打开的一样。

常见规则

要复制页面标题

<!-- Head: title -->
<replace theme="/html/head/title" content="/html/head/title" />

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

<!-- Base tag -->
<replace theme="/html/head/base" content="/html/head/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 -->
<append theme="/html/head" content="/html/head/link | /html/head/style" />

要复制Plone的JavaScript资源

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

要复制<body/>标签的类（对于某些Plone JavaScript功能和样式正常工作所必需的）

<!-- Body -->
<prepend theme="/html/body" content="/html/body/attribute::class" />

其他技巧

• Firebug是一个在构建规则时检查主题和内容的优秀工具。它甚至有一个XPath提取器。

• 阅读关于XPath的内容。它不像看起来那么复杂，而且非常强大。

• 在开发过程中以调试模式运行 Zope，这样你就不需要重启来查看主题、规则或资源的更改。

变更日志