plone.app.registry 2.0.5

创建记录

一旦你决定你需要特定的记录，你需要回答两个问题

1. 该记录应该叫什么名字？

2. 它应该保存什么类型的数据？

假设你想要创建一个名为my.package.timeout的记录，存储一个整数。整数由字段类型plone.registry.field.Int描述。几乎所有你在zope.schema中找到的标准字段在plone.registry.field中都有一个等效的字段。唯一的例外是Object，它不受支持。此外，Choice字段仅支持由字符串名称或字符串值列表给出的词汇表。最后，你无法使用constraint属性设置验证函数，尽管其他验证（如最小/最大值）将正常工作。

要安装此类记录，你可以在产品的GenericSetup配置文件中添加一个registry.xml步骤，如下所示

<registry>

    <record name="my.package.timeout">
        <field type="plone.registry.field.Int">
            <title>Timeout</title>
            <min>0</min>
        </field>
        <value>100</value>
    </record>

</registry>

让我们更详细地看看这个例子

• 声明了一条记录。名称在name属性中给出。

• 在记录中，我们首先通过给出字段类的完整点名称来定义字段类型。除非你已经安装了提供额外持久字段的第三方包，否则这将是位于plone.registry.field中的一个类，它对应于zope.schema中的一个相应的类。

• <field />元素内部，我们列出字段的任何必需或可选属性。这使用plone.supermodel语法。从本质上讲，每个允许的字段属性都由一个标签表示（因此可以使用<title />标签设置title属性），属性值作为标签内容给出。如果属性对于字段是必需的，则在这里需要相应的标签。

• 然后我们设置值。这显然必须是字段类型的有效值。

请注意，<value />是可选的。如果没有给出，字段将默认为它的missing_value，直到它被设置。如果记录已经在其他地方初始化，则<field />是可选的。

大多数字段属性都是如上所示这样的简单标签，字段名称用作标签名称，值字符串用作标签内容。但是，集合字段要复杂一些。一个集合字段（如List或Tuple）有一个包含另一个字段的value_type属性。它们的值和默认值是序列。让我们看看一个例子

<record name="my.package.animals">
    <field type="plone.registry.field.Tuple">
        <title>Animals</title>
        <description>A list of cool animals</description>
        <value_type type="plone.registry.field.TextLine" />
    </field>
    <value>
        <element>Dog</element>
        <element>Cat</element>
        <element>Elephant</element>
    </value>
</record>

注意，<value_type/> 标签和外部 <field/> 标签一样，都包含一个 type 属性。在这里，我们展示了没有选项的值类型，但如果需要，可以在 <value_type/> 标签内放置额外的字段属性标签。

还要注意值的表示方式。序列（本例中为元组）中的每个元素都由一个 <element/> 标签表示，元素值作为该标签的内容。

Dict 字段也有 <key_type/> 和键/值对元素。可以按照以下方式配置

<record name="my.package.animalFood">
    <field type="plone.registry.field.Dict">
        <title>Food eaten by animals</title>
        <key_type type="plone.registry.field.TextLine" />
        <value_type type="plone.registry.field.TextLine" />
    </field>
    <value>
        <element key="Dog">Dog food</element>
        <element key="Cat">Cat food</element>
        <element key="Elephant">Squirrels</element>
    </value>
</record>

使用多个注册表 XML 文件

您可以将注册条目存储在单个大型 registry.xml 文件中，而不是使用通用设置从多个文件加载和处理注册条目。这使得管理和组织应用程序和附加组件提供的注册条目更加容易。

您的附加组件应在其配置文件文件夹中包含一个名为 registry 的文件夹，例如 profiles/default/registry。该文件夹中的任何 XML 文件都将按照读取和处理 profiles/default 文件夹中的单个 registry.xml 文件的方式由注册处理。

例如，查看 Castle CMS 在其 profiles/default/registry 文件夹中使用多个 XML 文件。

如果两者都存在，注册将处理 registry.xml 文件和 registry 文件夹的内容。

条件记录

在 registry.xml 中的可导入记录可以使用 condition 属性标记为条件，该属性支持以下条件值

• installed my.package，这会导致仅在 python 模块 my.package 可用于导入时导入记录。

• not-installed my.package，这会导致仅在 python 模块 my.package 不可用于导入时导入记录

• have my-feature，这会导致仅在 ZCML 功能标志 my-feature 已注册（仅 Zope2）时导入记录

• not-have my-feature，这会导致仅在 ZCML 功能标志 my-feature 未注册（仅 Zope2）时导入记录

例如，以下位于您的策略产品通用设置配置文件中的 registry.xml 步骤，仅在模块 my.package 可用时导入记录

<registry>
  <records interface="my.package.interfaces.IZooSettings"
           condition="installed my.package">
    <value key="entryPrice">40</value>
    <value key="messageOfTheDay">We've got lions and tigers!</value>
  </records>
</registry>

字段引用

可以定义记录以使用另一个记录的字段。如果您希望一个记录作为另一个记录的可选覆盖使用，这通常很有用。例如

<registry>

    <record name="my.package.timeout">
        <field type="plone.registry.field.Int">
            <title>Timeout</title>
            <min>0</min>
        </field>
        <value>100</value>
    </record>

    <record name="my.package.timeout.slowconnection">
        <field ref="my.package.timeout" />
        <value>300</value>
    </record>

</registry>

在这个例子中，我们定义了具有整数字段的 my.package.timeout 记录。然后我们有一个单独的记录，具有不同的值，称为 my.package.timeout.slowconnection，它使用相同的字段（具有相同的数据类型、验证、标题、描述等）。这避免了需要明确重新定义整个字段。

注意：在这种情况下，该字段实际上是一个 FieldRef 对象。有关详细信息，请参阅 plone.registry 文档。

设置值

一旦定义了记录，就可以使用通用设置如下设置或更新其值

<record name="my.package.animalFood">
    <value purge="false">
        <element key="Squirrel">Nuts</element>
        <element key="Piranha">Other piranha</element>
    </value>
</record>

如果在一个包中定义了记录，而在另一个包中进行了追加或定制，这通常很有用。

在上述示例中，我们使用了 purge 属性。当设置多值字段（如元组、列表、集合或字典）的值时，将此属性设置为 false 会导致列表中的值被添加到现有集合中，而不是完全覆盖集合，就像将 purge 属性设置为 true 或省略时会发生的情况一样。

删除记录

要删除记录，请使用 remove 属性。

<record name="my.package.animalFood" remove="true" />

如果记录不存在，将记录警告，但处理会继续。

根据接口创建记录

在上述示例中，我们直接在注册表中创建单个记录。有时，使用将几个相关字段组合在一起的传统模式接口更容易。正如我们下面将看到的，plone.registry 和 plone.app.registry 为从接口创建的记录组提供了一些额外的功能。

例如，我们可以有一个这样的接口

from zope.interface import Interface
from zope import schema

class IZooSettings(Interface):

    entryPrice = schema.Decimal(title=u"Admission charge")
    messageOfTheDay = schema.TextLine(title=u"A banner message", default=u"Welcome!")

注意我们如何使用标准的 zope.schema 字段。当注册表被填充时，这些字段将被转换为持久字段（通过适配到 plone.registry 的 IPersistentField）。如果不可能，则在导入时将发生错误。

要注册这些记录，我们只需将以下内容添加到 registry.xml

<records interface="my.package.interfaces.IZooSettings" />

这将为每个字段创建一个记录。记录名称是字段的完整点分名称，因此在这种情况下，它们将是 my.package.interfaces.IZooSettings.entryPrice 和 my.package.interfaces.IZooSettings.messageOfTheDay。

如果您只想使用接口作为模板，则可以提供 prefix 属性

<records interface="my.package.interfaces.IZooSettings" prefix="my.zoo" />

这将生成名为 my.zoo.entryPrice 和 my.zoo.messageOfTheDay 的字段。

要设置由 指令创建的字段的值，您必须提供与接口上的字段对应的键的 value 条目，如下所示

<records interface="my.package.interfaces.IZooSettings" prefix="my.zoo">
    <value key="entryPrice">40</value>
    <value key="messageOfTheDay">We've got lions and tigers!</value>
</records>

值可以使用上述方法设置，也可以显式声明我们正在设置一个绑定到接口的记录，如下所示

<record interface="my.package.interfaces.IZooSettings" field="entryPrice">
    <value>10.0</value>
</record>

这与以下内容等效

<record name="my.package.interfaces.IZooSettings.entryPrice">
    <value>10.0</value>
</record>

您还可以使用 interface/field 语法从单个字段注册新记录。

最后，如果接口包含不能或不应设置的字段，则可以省略

<records interface="my.package.interfaces.IZooSettings">
    <omit>someField</omit>
</records>

可以重复使用 <omit /> 标签来排除多个字段。

根据接口删除记录

要根据接口删除一组记录，请使用 remove 属性

<records interface="my.package.interfaces.IZooSettings" remove="true" />

如果接口字段中任何记录不存在，将记录警告，但处理会继续。

如果您不想删除，或想排除某些字段，则可以省略

<records interface="my.package.interfaces.IZooSettings" remove="true">
    <omit>someField</omit>
</records>

可以重复使用 <omit /> 标签来排除多个字段。

访问注册表

要获取或设置记录的值，我们首先必须查找注册表本身。注册表注册为本地实用工具，因此我们可以使用以下方式查找它

from zope.component import getUtility
from plone.registry.interfaces import IRegistry

registry = getUtility(IRegistry)

现在可以使用简单的字典语法读取或设置值

timeout = registry['my.package.timeout']

我们还可以使用 get() 在条件性获取值，以及使用 in 检查测试注册表是否包含特定记录。

返回值将与给定名称的记录字段类型一致。它可以以相同的方式设置。

registry['my.package.timeout'] = 120

如果您需要访问底层记录，请使用records属性。

timeoutRecord = registry.records['my.package.timeout']

返回的记录符合plone.registry.interfaces.IRecord接口，并有两个主要属性：value是当前记录值，而field是持久化字段实例。如果记录是从接口创建的，它还将提供IInterfaceAwareRecord，并具有三个附加属性：interfaceName，接口的字符串名称；interface，接口实例本身，以及fieldName，创建此记录的接口中的字段名称。

您可以使用Python的del语句程序性地删除整个记录。

del registry.records['my.package.timeout']

在单元测试中，可能需要程序性地创建一个新的记录。您可以这样操作

from plone.registry.record import Record
from plone.registry import field

registry.records['my.record'] = Record(field.TextLine(title=u"A record"), u"Test")

构造函数接受持久化字段和初始值作为参数。

要程序性地注册接口的记录，我们可以这样做

registry.registerInterface(IZooSettings)

您可以通过传递一个包含省略字段名称的序列的omit参数来省略字段。

有关如何程序性地内省和操作注册记录的详细信息，请参阅plone.registry。

在页面模板中访问注册表

您还可以从页面模板中访问注册表。示例TALES表达式

python:context.portal_registry['plone.app.theming.interfaces.IThemeSettings.enabled']

使用记录代理

在上面的示例中，我们使用了字典语法来访问单个记录和值。这始终有效，但对于所谓的接口感知记录（例如，使用<records />语法从接口创建的记录），我们还有另一个选项：记录代理。这允许我们同时查找属于特定接口的所有记录，返回一个提供给定接口并可以像对象一样操作的代理对象，同时仍然连接到底层注册表。

要查找我们的IZooSettings接口的记录代理，我们可以这样做

zooSettings = registry.forInterface(IZooSettings)

现在zooSettings对象提供了IZooSettings。值可以通过属性表示法读取和设置。

zooSettings.messageOfTheDay = u"New message"
currentEntryPrice = zooSettings.entryPrice

在设置值时，它将立即进行验证并写入注册表。如果值不被对应记录的字段允许，则可能引发验证错误异常。

在获取记录代理时，plone.registry将默认验证接口中的每个字段都有记录，如果这不是这种情况，将引发错误。要禁用此检查，您可以进行以下操作

zooSettings = registry.forInterface(IZooSettings, check=False)

在某些情况下这可能很有用，例如当不确定注册表是否已初始化时。您还可以通过传递一个包含字段名称的元组作为omit参数来省略对单个字段的检查。

删除记录

删除记录就像这样简单

del registry.records['plone.app.theming.interfaces.IThemeSettings.enabled']

注册表事件

注册表在修改时发出事件。

• plone.registry.interfaces.IRecordAddedEvent在记录已添加到注册表时触发。

• plone.registry.interfaces.IRecordRemovedEvent在记录从注册表中删除时触发。

• plone.registry.interfaces.IRecordModifiedEvent在记录的值被修改时触发。

您可以注册订阅者以捕获对注册表的任何更改。此外，您可以注册一个只监听与特定接口关联的记录更改的事件处理器。例如

from zope.component import adapter
from plone.registry.interfaces import IRecordModifiedEvent

from logging import getLogger
log = getLogger('my.package')

@adapter(IZooSettings, IRecordModifiedEvent)
def detectPriceChange(settings, event):
    if record.fieldName == 'entryPrice':
        log.warning("Someone change the price from %d to %d" % (event.oldValue, event.newValue,))

有关这些事件类型的详细信息，请参阅plone.registry。

通过控制面板查看和编辑记录

此包在 Plone 的“站点设置”中提供了“配置注册表”控制面板。在这里，您可以查看所有注册表记录，可以使用大小写敏感的过滤器字段搜索记录，并可以根据其前缀（例如“IDiscussionSettings”，“plone.app.caching”）选择记录集。

显示注册表记录的名称、标题、描述、数据类型和当前值。

如果您点击一个记录，将出现一个编辑表单，允许您更改其值。

通过控制面板导出和导入记录

您可以使用配置注册表控制面板的“导出”选项卡将整个注册表导出到单个 XML 文件。当您点击“立即导出”按钮时，名为 registry.xml 的文件将被下载到您的计算机。

要导入注册表条目，请使用配置注册表控制面板的“导入”选项卡，使用“选择文件”按钮从您的计算机中选择包含注册表条目的 XML 文件，然后按“导入文件”按钮。

通过控制面板添加和删除记录

您可以使用配置注册表控制面板的“添加新记录”选项卡添加单个注册表记录。

输入注册表记录的名称、（可读）标题、选择数据类型，并根据需要勾选“必需”框（如果记录必须具有值）。然后按“添加字段”按钮。