nti.contentratings 1.2.0

默认类别

此包的默认配置提供了两个评分类别。一个用于用户评分，一个用于编辑评分。它们分别注册为标记接口< cite>IUserRatable和< cite>IEditorRatable。用于确定它们何时应用的TALES表达式旨在与Zope 2 CMF应用程序中的对象（主要用于与旧版本的< cite>contentratings保持向后兼容，该版本使用了直接权限检查）一起使用。除非它们想允许所有用户设置和读取评分，否则其他应用程序将需要定义具有自定义条件的类别。

让我们演示如何使用这些类别。我们需要创建一些内容，并用我们的标记接口标记它

>>> from contentratings.tests import SampleContainer
>>> content = SampleContainer()
>>> from contentratings.interfaces import IUserRatable
>>> from zope.interface import alsoProvides
>>> alsoProvides(content, IUserRatable)

现在我们可以使用IUserRating接口将其适配到评分类别

>>> from contentratings.interfaces import IUserRating
>>> adapted = IUserRating(content)
>>> adapted.title
u'User Rating'
>>> float(adapted.averageRating)
0.0
>>> rating = adapted.rate(7.0)
>>> float(adapted.averageRating)
7.0
>>> adapted.numberOfRatings
1
>>> rating = adapted.rate(8.0, 'me')
>>> float(adapted.averageRating)
7.5
>>> adapted.numberOfRatings
2

有关IUserRating API的更多详细信息，请参阅< cite>tests/userstorage.txt。

编辑评分类似，但实现要简单得多

>>> from contentratings.interfaces import IEditorRatable, IEditorialRating
>>> alsoProvides(content, IEditorRatable)
>>> adapted = IEditorialRating(content)
>>> adapted.title
u'Editor Rating'
>>> adapted.rating is None
True
>>> adapted.rating = 6.0
>>> float(adapted.rating)
6.0
>>> adapted.rating = 8.0
>>> float(adapted.rating)
8.0

有关IEditorialRating API的详细信息，请参阅< cite>tests/editorialstorage.txt。

现在让我们删除这些标记，以便我们可以检查自定义类别

>>> from zope.interface import noLongerProvides
>>> noLongerProvides(content, IUserRatable)
>>> noLongerProvides(content, IEditorRatable)
>>> IUserRatable(content) # doctest: +ELLIPSIS
Traceback (most recent call last):
...
TypeError: ('Could not adapt', ...)
>>> IEditorialRating(content) # doctest: +ELLIPSIS
Traceback (most recent call last):
...
TypeError: ('Could not adapt', ...)

自定义评分类别

有两种方法可以创建新的评分类别，一种是声明性地使用ZCML，另一种是直接从Python使用类别工厂。让我们首先看看ZCML方法。要使其生效，我们需要启用zcml指令

>>> from zope.configuration import xmlconfig
>>> import contentratings
>>> context = xmlconfig.file('meta.zcml', contentratings)

加载包配置将自动执行上述操作。

现在我们使用< cite>contentratings:category指令注册我们的评分类别

>>> context = xmlconfig.string("""
... <configure
...    xmlns:contentratings="http://namespaces.plone.org/contentratings">
...  <contentratings:category
...      for="zope.container.sample.SampleContainer"
...      title="My Rating Category"
...      />
... </configure>""", context=context)

在这里，我们使用了所有类别默认值。因此，我们注册了一个使用默认ZODB存储和< cite>IUserRating API的类别，没有限制谁可以获取和设置评分。我们可以很容易地验证这一点，因为类别只是提供由（默认）存储提供的评分接口的适配器

>>> from contentratings.interfaces import IUserRating
>>> content = SampleContainer()
>>> adapted = IUserRating(content)
>>> IUserRating.providedBy(adapted)
True
>>> adapted.context is content
True
>>> adapted.title
u'My Rating Category'

请注意，因为我们没有在配置中提供名称，因此适配器被注册为默认的（未命名的）适配器。类别的名称是适配器注册的名称，并存储在类别的name属性中

>>> adapted.name
''

要提供多个类别，只需使用唯一名称注册它们

>>> context = xmlconfig.string("""
... <configure
...    xmlns:contentratings="http://namespaces.plone.org/contentratings">
...  <contentratings:category
...      for="zope.container.sample.SampleContainer"
...      title="My Other Rating Category"
...      name="other"
...      />
... </configure>""", context=context)
>>> from zope.component import getAdapter
>>> adapted = getAdapter(content, IUserRating, name=u'other')
>>> adapted.title
u'My Other Rating Category'
>>> adapted.name
u'other'

如果我们想以编程方式完成同样的事情，我们可以直接实例化工厂并将其注册为适配器

>>> from contentratings.category import RatingsCategoryFactory
>>> category = RatingsCategoryFactory(title=u'Another Title', name=u'another')
>>> from zope.component import provideAdapter
>>> provideAdapter(category, adapts=(SampleContainer,), provides=IUserRating,
...                name=u'another')
>>> adapted = getAdapter(content, IUserRating, name=u'another')
>>> adapted.title
u'Another Title'
>>> adapted.name
u'another'

这涉及一些冗余，因为存储提供的接口必须显式声明，类别名称必须提供两次。否则它们是等效的。

请注意，类别是适配器，适配器只能以相同名称在不同接口/类下注册。通常，对于给定的名称，将选择注册在最具体接口上的适配器。

评分视图

每个类别都有一个相关的 view_name，这只是一个为评分接口（例如IUserRating）注册的视图的名称，用于在UI中渲染类别。这些在评分管理器中查找，可以访问 IRatingManager API，以及由管理器提供的受保护的评分存储API（例如IUserRating）。

在 browser/basic.py 中提供了评分视图的可重用基类（BasicUserRatingView 和 BasicEditorialRatingView）。这些视图使用命名词汇来验证输入，并使用IRatingManager API来确定谁可以和不能对内容进行评分。默认情况下，包配置提供了一些评分视图。

ratings_view (default):  A rating using 1-5 large (25px) stars
small_stars: A rating using 1-5 small (10px) stars
three_small_stars: A rating using 1-3 small (10px) stars

这些都可以通过CSS进行高度自定义。它们都注册为IUserRating。此外，还有一个 rating_view 为IEditorialRating注册。

视图负责查找评分词汇，验证用户输入，以及渲染用户界面。安全性由视图使用的 评分管理器 强制执行，但是视图可以直接从评分管理器访问存储以覆盖表达式检查（例如，显示用户自己的评分，尽管他们看不到别人的）。创建新的视图（例如，非星级评分）非常简单。

提供了一个通用方式有效地确定可重用会话键的实用工具。这可以用来防止匿名用户重复投票。实现自己的匿名会话跟踪机制的应用程序可以在需要时在本地覆盖此实用工具。

聚合视图

还有其他视图，它们找到正在查看的内容对象上所有可用的评分类别，按顺序渲染它们。这些旨在在视图小部件、模块、宏或类似内容中使用。用户评分的聚合视图称为 user-ratings，而编辑评分的聚合视图称为 editorial-ratings。

作者

• Alec Mitchell <apm13@columbia.edu>

贡献者

• Maurizio Delmonte

（如果您做出了重大贡献，请自由地在上面的名称中添加您的名字）

感谢以下人员

• Geoff Davis，ATRatings的作者，从其中借鉴了图标和想法。

• Philipp von Weitershausen，Web Component Development with Zope 3的作者，它提供了一个基于注释的评分产品的良好示例，这是本实现的开端。

• Kai Diefenbach，iqpp.plone.rating的作者，从中借鉴了其他图标和UI想法。

• 一些图标来自Mark James的Silk icon set 1.3

• 星级评分基于CSS Star Rating Redux，通过iqpp.plone.rating。