collective.themefragments 2.12

片段模板

碎片是与您的主题捆绑在一起的 Zope 页面模板文件。您可以通过在主题资源目录（即包含 rules.xml 的目录）中添加一个名为 fragments 的文件夹来创建它们，无论是通过 Web 还是文件系统，然后在该目录中创建一个或多个扩展名为 .pt 的文件。

例如，您可以在主题目录中创建一个名为 fragments/customnav.pt 的文件，包含以下内容：

<ul id="nav">
  <li tal:repeat="item context/@@folderListing">
    <img tal:replace="structure item/getIcon" />
    <span tal:replace="item/Title" tal:attributes="titile item/Description">Title</span>
  </li>
</ul>

这使用 Zope 页面模板 TAL 语法（如果您在文件系统 Python 开发中使用，可能会用到的相同语法）来根据当前上下文可用的属性和辅助视图生成一些标记。

以下变量可用于用于构建碎片的页面模板

上下文

查找碎片所在的上下文。这通常是门户根（当使用带有绝对路径的 href 时，即以 / 开头）或当前内容对象（当使用带有相对路径的 href 时）。

请求

用于渲染碎片的请求。当使用规则的 href 中的碎片时，这是一个用于渲染页面的请求的克隆，但路径是碎片视图而不是原始内容对象。请注意，原始请求中的表单参数在此请求中不可用。

门户

门户根对象。

portal_url

到门户根的 URL。

您可以在这里了解有关 Zope 页面模板语法的更多信息。

碎片模块

碎片模块是与您的主题捆绑在一起的受限 Python 脚本模块。方法的可用性通过使用碎片基本名称（带有 .py 扩展名）命名模块来限制。每个模块可以包含任意数量的 Python 函数定义，这些函数定义随后作为碎片视图的实例方法提供。

例如，您可以在主题目录中创建一个名为 fragments/customnav.py 的文件，包含以下内容：

def getnav(self):
    return [{
        'Title': u'My title',
        'Description': u'My description',
        'getIcon': 'document_icon.png'
    }]

然后在您的碎片 fragments/customnav.pt 中像调用视图方法一样调用它：

<ul id="nav">
  <li tal:repeat="item view/getnav">
    <img tal:replace="structure item/getIcon" />
    <span tal:replace="item/Title" tal:attributes="titile item/Description">Title</span>
  </li>
</ul>

碎片方法

碎片方法是与您的主题捆绑在一起的受限 Python 脚本文件。方法的可用性通过在方法文件名前缀碎片名称来限制。每个脚本应包含用于单个方法的代码，并以返回模板的值结束。

例如，您可以在主题目录中创建一个名为 fragments/customnav.getnav.py 的文件，包含以下内容：

return [{
    'Title': u'My title',
    'Description': u'My description',
    'getIcon': 'document_icon.png'
}]

然后在您的碎片 fragments/customnav.pt 中像调用视图方法一样调用它：

<ul id="nav">
  <li tal:repeat="item view/getnav">
    <img tal:replace="structure item/getIcon" />
    <span tal:replace="item/Title" tal:attributes="titile item/Description">Title</span>
  </li>
</ul>

以下变量可用于用于构建碎片的碎片方法

self

碎片视图，它提供对 self.context、self.request 和其他可用碎片方法的访问，类似于文件系统浏览器视图。

args

方法调用的位置参数列表。碎片方法不支持 Zope PythonScript 定义位置命名参数的方式。

kwargs

方法调用的关键字参数字典。碎片方法不支持 Zope PythonScript 定义命名关键字参数的方式。

上下文

查找碎片的上下文。这是对 Zope PythonScript 的致敬。

container

查找碎片的上下文的容器。这是对 Zope PythonScript 的致敬。

traverse_subpath

一个空字符串。这作为对Zope PythonScript的致敬。

渲染片段

特殊的 @@theme-fragment 视图用于渲染片段。在使用它之前，您可以直接在浏览器中通过访问类似以下URL来测试它：

https://#:8080/Plone/@@theme-fragment/customnav

这将导致在 fragments/customnav.pt 中的片段被渲染，其上下文是运行在 localhost:8080 上的 Plone 网站 Plone。您可以通过调整URL来渲染任何内容对象的相对片段。

注意：片段仅适用于当前活动的主题。以这种方式在浏览器中测试片段时，请确保已启用主题！

要在主题规则中使用片段，请使用带有绝对或相对路径的 href 属性。例如

<replace css:theme="#navlist" css:content="#nav" href="/@@theme-fragment/customnav" />

将替换主题中具有 id navlist 的元素，用由主题中的 fragments/customnav.pt 模板生成的具有 id nav 的元素替换，始终以门户根作为其 context（因为 href 使用的是绝对路径，即以 / 开头）。

同样

<replace css:theme="#navlist" css:content="#nav" href="@@theme-fragment/customnav" />

将执行相同的操作，但使用当前内容项作为其 context（即 href 使用的是相对路径）。

作为视图的片段

片段还可以用作内容视图，通过将内容对象的 layout-属性设置为 ++themefragment++name 来实现，其中 name 是片段的名称。目前，无法配置片段在显示菜单中可见。

注意：片段仅适用于当前活动的主题。以这种方式在内容中使用片段时，请确保已启用主题！

片段安全

与主题HTML模拟文件一样，片段默认情况下是公开可访问的。任何可以访问网站的人都可以构造一个包含 @@theme-fragment/<name> 的URL来渲染给定的片段。

或者，可以在主题的 manifest.cfg 中为每个瓷砖定义更严格的权限，其语法为

[theme:themefragments:permissions]
basename = zope2.View

然而，无论定义了什么权限，用于构建片段的页面模板都在所谓的 受限Python 环境中执行。这意味着它们以当前用户（或 匿名，如果当前用户未登录）的身份执行。无法访问的信息（如内容项或其属性）无法渲染，并且可能导致渲染片段时出现 403 禁止 错误。

片段瓷砖

安装了 plone.tiles、plone.app.tiles 和 plone.app.blocks 后，此包提供了一个额外的安装配置文件，用于 主题片段瓷砖，可以将其用于放置主题片段。

在主题的 manifest.cfg 中可以使用以下方式定义更易于阅读的主题片段标题：

[theme:themefragments:tiles]
basename = Display title

其中 basename 是片段文件名的基名（在 .pt 之前的部分）。

瓷砖可以定义其配置架构，使用具有与其匹配的文件名结尾为 .xml 而不是 .pt 的片段特定文件中的 plone.supermodel XML。

还可以在 manifest.cfg 中指定片段特定的缓存规则集：

[theme:themefragments:caching]
basename = plone.content.feed