Plone文本字段在渲染时应用到的HTML转换
项目描述
简介
plone.outputfilters 提供了一个框架，用于注册应用于渲染文本时的过滤器。
默认情况下，这些过滤器通过 PortalTransforms 机制在文本从 text/html MIME 类型转换为 text/x-html-safe MIME 类型时应用。
在 plone.app.textfield 的 RichText 字段中，这种转换通常在首次访问字段值时应用。转换的结果随后被缓存在一个易失性属性中，持续一小时或直到值被替换。
包含的过滤器
包含一个默认过滤器，提供以下功能：
解析基于 UID 的链接
为图像添加标题
（这些功能实现为一个过滤器，以避免解析 HTML 两次的开销。）
这些功能以前由 Products.kupu 和 Products.TinyMCE 中的类似转换提供。这些编辑器的新的版本正在准备中，它们依赖于 plone.outputfilters 中的转换，这样就不需要在多个地方修复错误。
解析基于 UID 的链接
内部链接可以插入 UID 引用而不是链接项的实际路径。例如，一个链接可能看起来像这样：
<a href="resolveuid/6992f1f6-ae36-11df-9adf-001ec2a8cdf1">
这样的 URL 可以通过 resolveuid 观察器解析，该观察器将 UID 解析为对象，然后重定向到其 URL。然而，以这种方式解析链接需要在重定向后进行额外的请求。resolveuid 过滤器通过在渲染链接时用对象的实际完整绝对 URL 替换此类 URL 来避免这种情况。
UID 使用 plone.app.uuid.utils.uuidToURL 解析。
如果至少有一个 plone.outputfilters.filters.resolveuid_and_caption.IResolveUidsEnabler 实用工具的 available 属性返回 True，则启用 resolveuid 过滤器。这种机制存在是为了与 TinyMCE 和 kupu 兼容，它们都提供自己的控制面板设置来启用按 UID 链接的功能。
图像标题
具有“captioned”类和 src 属性，且该属性解析到站内图像对象的图像标签将被包裹在一个定义列表（DL）标签中，其中包含基于图像的 description 字段值的标题，如果有的话。
例如，这个图像标签
<img src="path/to/image" class="captioned"/>
可能被转换成
<dl class="captioned"> <dt><img src="path/to/image"/></dt> <dd class="image-caption">Caption text</dd> </dl>
假设在“path/to/image”找到的图像的描述是“标题文本”。
如果至少有一个 plone.outputfilters.filters.resolveuid_and_caption.IImageCaptioningEnabler 实用工具的 available 属性返回 True，则启用标题过滤器。这种机制存在是为了与 TinyMCE 和 kupu 兼容，它们都提供自己的控制面板设置来启用标题功能。
图像的标题版本是通过 @@plone.outputfilters_captioned_image 观察器渲染的，该观察器可以被覆盖以自定义标题。此观察器传递以下 kwargs
- class
图像上的 CSS 类。
- originalwidth
图像标签的 width 属性。
- originalalt
图像标签的 alt 属性。
- url_path
图像的路径，相对于站点根目录。
- caption
图像的描述。
- image
（可能是缩放的）图像对象。
- fullimage
原始未缩放的图像对象。
- tag
显示图像的完整 HTML 标签。
- isfullsize
如果 image 是 fullimage，则为 True。
- width
image 的宽度。
添加自定义过滤器
例如，以下过滤器将所有重复的短横线（”–”）替换为破折号（”-“）。（不要逐字使用此示例，因为它不会解析HTML以仅应用于文本节点，因此会破坏HTML注释。）
过滤器是一个可调用对象，它接受UTF-8编码的HTML字符串作为输入，并返回修改后的UTF-8编码的HTML字符串。可以使用None作为返回值来指示输入不应被修改。
示例
import re
from zope.interface import implementer
from plone.outputfilters.interfaces import IFilter
@implementer(IFilter)
class EmDashAdder(object):
order = 1000
def __init__(self, context, request):
pass
def is_enabled(self):
return True
pattern = re.compile(r'--')
def __call__(self, data):
return self.pattern.sub('—', data)
可以使用order属性来影响应用过滤器的顺序（值较高的过滤器在后面运行）。is_enabled方法应返回一个布尔值，指示是否应用过滤器。
过滤器在ZCML中注册为上下文和请求到IFilter的命名多适配器
>>> from Zope2.App import zcml
>>> import Products.Five
>>> configure = """
... <configure
... xmlns="http://namespaces.zope.org/zope">
...
... <adapter
... name="em_dash_adder"
... provides="plone.outputfilters.interfaces.IFilter"
... for="* *"
... factory="plone.outputfilters.filters.example.EmDashAdder"
... />
...
... </configure>
... """
>>> zcml.load_config("configure.zcml", Products.Five)
>>> zcml.load_string(configure)
现在当文本从text/html转换为text/x-html-safe时，将应用过滤器
>>> app = layer['app']
>>> portal = layer['portal']
>>> str(portal.portal_transforms.convertTo('text/x-html-safe',
... 'test--test', mimetype='text/html', context=portal))
'test—test'
它是如何工作的
plone.outputfilters通过安装以下内容连接到PortalTransforms机制：
一个新的MIME类型（“text/x-plone-outputfilters-html”）
从text/html到text/x-plone-outputfilters-html的转换
从text/x-plone-outputfilters-html回text/html的空转换
text/x-html-safe MIME类型的“转换策略”，该策略表示在转换到text/x-html-safe之前必须先转换为text/x-plone-outputfilters-html
在执行步骤#2的转换期间查找并应用过滤器适配器。
这应被视为一个实现细节，并且可能在未来的某个时刻发生变化。
变更日志
5.0.4 (2023-07-13)
修复错误
每次过滤器而不是每个img标签调用一次注册表。[gotcha] (less_call_to_registry)
内部
更新配置文件。[plone开发者] (7723aeaf)
5.0.3 (2023-06-16)
修复错误
如果resolveuid视图调用时没有uuid，则返回404 Not Found响应。[davisagli (#43)]
5.0.2 (2023-04-14)
内部
更新配置文件。[plone开发者] (535edb14)
5.0.1 (2023-03-21)
内部
更新配置文件。[plone开发者] (243ca9ec)
5.0.0 (2022-11-17)
修复错误
使用我们从plone.app.uuid.utils的新版本uuidToObject()。[anirudhhkashyap (#52)]
5.0.0b3 (2022-09-30)
修复错误
在图片变体过滤器后不要返回格式化后的soup。这可以防止添加不必要的换行符。[petschki] (#56)
5.0.0b2 (2022-09-10)
修复错误
isort, black, pyupgrade, 手动six移除。[jensens] (#53)
5.0.0b1 (2022-06-23)
新功能
添加image_srcset输出过滤器，将IMG标签转换为具有在图像控制面板中定义的多个源定义的PICTURE标签。[MrTango] (#49)
4.1.0 (2022-02-23)
新功能
在SOURCE和IFRAME元素的SRC=属性中解析UID。[#47]
4.0.2 (2020-09-28)
修复错误
修复当在标签中包装全尺寸图像时抛出 AttributeError: ‘NoneType’ object has no attribute ‘unwrap’ 异常。[flipmcf] (#39)
修复html_quote的弃用警告。[maurits] (#3130)
4.0.1 (2020-04-21)
修复错误
小型的打包更新。[#1]
4.0.0 (2020-03-13)
重大变更
将图像标题模板更改为使用<figure>和<figcaption>。[thet]
新功能
添加一个ImageCaptioningEnabler实用工具，该实用工具可以通过门户注册设置plone.image_captioning启用。[thet]
修复错误
在测试中不要检查硬编码的图像大小。[agitator]
修复了Python 3.6在未设置系统区域设置时可能出现的包安装错误。请参阅coredev问题642。[maurits]
3.1.2 (2019-03-21)
修复错误
修复了当uid链接的图像标题或描述中包含非ascii字符时的UnicodeDecodeError。[petschki]
3.1.1 (2019-01-07)
修复错误
修复了由没有href属性的元素引起的KeyError错误。[ajung]
3.1.0 (2018-11-02)
新功能
移除弃用的sgmllib并移动到BeautifulSoup4。[tobiasherp, petschki]
3.0.5 (2018-06-04)
修复错误
允许解析具有绝对路径和主机的链接。[tomgross]
将plone.namedfile作为硬依赖项。[tomgross]
3.0.4 (2018-02-02)
修复错误
添加Python 2/3兼容性。[pbauer]
3.0.3 (2017-08-04)
修复错误
更新测试以反映PortalTransforms的变化。[MrTango]
3.0.2 (2017-07-03)
修复错误
移除unittest2依赖项。[kakshay21]
3.0.1 (2017-02-05)
修复错误
在script标签内部不要转换a和img标签。[gotcha]
3.0.0 (2016-08-19)
重大变更
放弃对具有旧式接口的PortalTransforms 1.x的支持。[jensens]
修复错误
处理img属性中的Unicode错误。[vangheem]
清理：utf8-headers，isort，pep8 [jensens]
使用 zope.interface 装饰器。 [gforcada]
2.1.5 (2016-06-07)
修复错误
使测试与旧的和新的安全HTML转换工作。 [tomgross]
2.1.4 (2016-05-10)
修复
明确排除 mailto: 链接进行 UID 解析。 [thet]
修复测试隔离问题。 [thet]
2.1.3 (2016-03-07)
新功能
将 tel: 添加到忽略的链接类型中。 [julianhandl]
2.1.2 (2015-12-15)
修复
修复了当对象没有绝对_url 方法时 uid 解析的错误。 [Gagaro]
2.1.1 (2015-11-25)
修复
修复了在解析 img 标签时使用 unicode，而 (un)restrictedTraverse 不与 unicode 一起工作的情况。 [vangheem]
2.1 (2015-07-18)
删除 kupu BBB 代码。 [gforcada]
2.0 (2015-03-13)
对于全尺寸（非缩放）的 plone.app.contenttypes 图像，保留 img 标签属性中指定的宽度和高度。 [davisagli]
将测试转换为 plone.app.testing [tomgross]
1.14 (2014-04-22)
对于 plone 5，始终解析uids [vangheem]
1.13 (2014-04-13)
问题 #12783：img 标签引用不存在的缩放导致转换错误 [anthonygerrard]
1.12 (2014-01-27)
尚未有任何更改。
1.11.1 (2013-07-19)
修复 README rst。 [gotcha]
1.11 (2013-07-19)
img unicode 问题：修复 resolve_image 以避免它返回 unicode [gotcha]
处理 img 标签可能为 unicode 的情况，以防止 unicode 错误 [vangheem]
1.10 (2013-05-23)
绕过 SGMLParser 中的错误以正确处理单例标签。 [tom_gross]
1.9 (2013-04-06)
如果有一个图像描述，它应该放入 img 标签的 alt 文本中 [ale-rt]
1.8 (2012-12-10)
修复打包问题。 [esteele]
1.7 (2012-12-09)
在解析图像时，如果遍历的图像不是内容项（即缩放），则仅向上查找完整的图像。 [davisagli, datakurre]
还转换了 FCKeditor 创建的“resolveUid/”（大写“U”）链接。 [hacklschorsch]
还转义双引号，修复 #13219 [maartenkling]
1.6 (2012-08-16)
如果由于某种原因 @@images 缩放无法解析，则不要中断。 [davisagli]
1.5 (2012-08-15)
当 plone.outputfilters 存在时，恢复与 Plone 4.0 的兼容性。 [davisagli]
1.4 (2012-08-04)
修复与 plone.namedfile 的不兼容性 [do3cc]
1.3 (2012-05-25)
通过将 README.rst 的一部分移动到 plone/outputfilters/README.txt 修复了测试错误。 [maurits]
小的 pep8 更新 [pbdiode]
1.2 - 2012-04-09
防止将链接转换为同一页面的锚点。 [davisagli]
修复 resolveuid 视图中的 kupu_resolveuid_hook 分支中的未定义 uuid 变量。 [vincentfretin]
确保通过 resolveuid 视图解析过期的对象的链接。 [davisagli]
如果未使用 tinymce uid 链接，img 标签上的 alt/title 属性将不存在 [iElectric]
在将相对 URI 绝对化时，如果上下文不是文件夹状，则使用父级作为相对根。修复了 Plone 3 的相对 URL 在 Plone 4 中使用默认页面作为文件夹时出现错误的问题。 [rossp]
修复了打包时缺少 README.rst 的测试错误。 [maurits]
1.1 - 2011-11-21
修复了 AT 内容中受保护对象的解析。 [tom_gross]
修复了相对 ../resolveuid/… 链接的解析。 [tom_gross]
尊重 Python 2.4 和 Python 2.6 sgmlparser 中的实现差异。 [tom_gross]
修复了受保护文件夹中图像的标题中的解析。 [mj]
1.0 - 2011-05-13
最终版本 1.0。 [esteele]
添加 MANIFEST.in。 [WouterVH]
1.0b5 - 2011-03-24
使字幕和链接与新式图像缩放一起工作。 [elro]
链接解析的通用重构。 [elro]
1.0b4 - 2011-03-22
向图像添加 alt 和 title 标签。 [elro]
从 imaging 视图中获取各种图像属性以更好地与 Dexterity 一起工作。 [elro]
小的修复，使其可以在不需要 REQUEST 或模拟它的需要的情况下创建对象。 [garbas]
1.0b3 - 2011-02-24
解析以正斜杠开头的图像路径相对于 Plone 网站根。 [davisagli]
支持使用 @@images 视图对新式图像缩放进行图像字幕。 [davisagli]
1.0b2 - 2011-01-11
修复 resolveuid，使 uid 解析在身份验证之后发生。 [elro]
请记住在提交之前运行测试！ [elro]
修复了解析具有子路径的链接导致子路径颠倒的问题。 [elro]
1.0b1 - 2011-01-25
修复解析resolveuid链接子路径的问题。这解决了 http://dev.plone.org/plone/ticket/11426 [davisagli]
1.0a1 - 2011-01-03
初始实现。[davisagli]
下载文件
下载适用于您平台的文件。如果您不确定选择哪个，请了解更多关于安装包的信息。
