Wagtail Hallo - 富文本编辑器

这是Wagtail CMS的遗留富文本编辑器。基于Hallo.js。

有关Wagtail 2.0，hallo.js编辑器已弃用。

状态 此软件包应与Wagtail 2.17及更早版本兼容。但是，它将不再接收错误修复或积极维护。将接受拉取请求，如果维护者希望在核心Wagtail团队之外支持它，请提出问题以进行讨论。

使用此软件包的主要风险

• 请注意，如果您想继续使用它，请了解已知的hallo.js问题。
• hallo.js对HTML和编辑器输入的处理不恰当——它不可靠，具有浏览器特定的不一致行为，用户体验不佳，且不可访问。
• 此包是安全问题的来源（XSS注入，不兼容CSP）并允许注入不受欢迎的内容或格式（例如，标题中的图片或列表中的标题）。
• 无法保证此包将超出上述支持的版本与Wagtail兼容。

发布说明

• 请参阅变更日志。

支持版本

• Python 3.7, 3.8, 3.9
• Django 3.2, 4.0
• Wagtail 2.15, 2.16, 3.0

安装Hallo编辑器

• pip install wagtail-hallo
• 将'wagtail_hallo'添加到您的settings.py中的INSTALLED_APPS。

要在Wagtail 2.x上使用wagtail-hallo，请将以下内容添加到您的设置中

WAGTAILADMIN_RICH_TEXT_EDITORS = {
    'hallo': {
        'WIDGET': 'wagtail_hallo.hallo.HalloRichTextArea'
    }
}

在RichTextField中使用Hallo编辑器

# models.py
from wagtail.admin.edit_handlers import FieldPanel
from wagtail.core.fields import RichTextField
from wagtail.core.models import Page

class MyHalloPage(Page):
    body = RichTextField(editor='hallo')

    content_panels = Page.content_panels + [
        FieldPanel('body', classname='full'),
    ]

{% extends "base.html" %}
{% load wagtailcore_tags wagtailimages_tags %}

{% block content %}
    {% include "base/include/header.html" %}
    <div class="container">
        <div class="row">
            <div class="col-md-7">{{ page.body|richtext }}</div>
        </div>
    </div>
{% endblock content %}

通过RichTextBlock在StreamField中使用Hallo编辑器

# models.py
from wagtail.core.models import Page
from wagtail.core.blocks import CharBlock, RichTextBlock
from wagtail.admin.edit_handlers import StreamFieldPanel
from wagtail.core.fields import StreamField

class MyOtherHalloPage(Page):
    body = StreamField([
        ('heading', CharBlock(form_classname="full title")),
        ('paragraph', RichTextBlock(editor='hallo')),
    ], blank=True)

    content_panels = Page.content_panels + [
        StreamFieldPanel('body'),
    ]

{% extends "base.html" %}
{% load wagtailcore_tags wagtailimages_tags %}

{% block content %}
    {% include "base/include/header.html" %}
    <div class="container">
        <div class="row">
            <div class="col-md-7">{{ page.body }}</div>
        </div>
    </div>
{% endblock content %}

扩展Hallo编辑器

可以通过插件扩展遗留的hallo.js编辑器的功能。有关开发自定义hallo.js插件的详细信息，请参阅项目的页面：https://github.com/bergie/hallo。

创建插件后，应通过功能注册器的register_editor_plugin(editor, feature_name, plugin)方法进行注册。对于hallo.js插件，editor参数应始终为'hallo'。

一个名为halloblockquote的插件，实现于myapp/js/hallo-blockquote.js，它增加了对<blockquote>标签的支持，将如下注册在功能名称block-quote下

    from wagtail.core import hooks
    from wagtail_hallo.plugins import HalloPlugin

    @hooks.register('register_rich_text_features')
    def register_embed_feature(features):
        features.register_editor_plugin(
            'hallo', 'block-quote',
            HalloPlugin(
                name='halloblockquote',
                js=['myapp/js/hallo-blockquote.js'],
            )
        )

HalloPlugin的构造函数接受以下关键字参数

• name - JavaScript代码中定义的插件名称。 hallo.js插件名称以"IKS."命名空间为前缀，但此处传递的名称应不带前缀。
• options - 一个字典（或其他可序列化为JSON的对象），包含要在初始化时传递给JavaScript插件代码的选项
• js - 一个JavaScript文件列表，用于导入此插件，其定义方式与Django表单媒体定义相同
• css - 一个CSS文件字典，用于导入此插件，其定义方式与Django表单媒体定义相同
• order - 一个索引数字（默认100），指定插件应列出的顺序，这进而确定工具栏中按钮的顺序

在编写插件的前端代码时，Wagtail的Hallo实现提供了两个扩展点

• 在JavaScript中，使用[data-hallo-editor]属性选择器来定位编辑器，例如var editor = document.querySelector('[data-hallo-editor]');。
• 在CSS中，使用.halloeditor类选择器。

白名单富文本元素

在扩展编辑器以支持新的HTML元素后，您需要将其添加到允许元素的白名单中——Wagtail的标准行为是删除未识别的元素，以防止编辑器插入开发人员未考虑到的样式和脚本（无论是故意还是意外地通过复制粘贴）。

可以通过功能注册器的register_converter_rule(converter, feature_name, ruleset)方法将元素添加到白名单中。当使用hallo.js编辑器时，converter参数应始终为'editorhtml'。

以下代码将在block-quote功能激活时将<blockquote>元素添加到白名单

    from wagtail.admin.rich_text.converters.editor_html import WhitelistRule
    from wagtail.core.whitelist import allow_without_attributes

    @hooks.register('register_rich_text_features')
    def register_blockquote_feature(features):
        features.register_converter_rule('editorhtml', 'block-quote', [
            WhitelistRule('blockquote', allow_without_attributes),
        ])

WhitelistRule传递元素名称，以及一个在遇到元素时执行某种类型操作的调用函数。此调用函数接收元素作为BeautifulSoup Tag对象。

《wagtail.core.whitelist》模块提供了一些辅助函数来帮助定义这些处理程序：`allow_without_attributes`，这是一个处理程序，它保留元素但删除其所有属性；以及`attribute_rule`，它接受一个字典，指定如何处理每个属性，并返回一个处理程序函数。这个字典将映射属性名称到True（表示应该保留该属性）、False（表示应该删除该属性）或一个可调用对象（它接受初始属性值并返回该属性的最终值，或返回None以删除该属性）。

贡献

欢迎所有贡献，因为Wagtail核心团队将不再积极维护此项目。

开发说明

• 要更改此项目，首先克隆此仓库：`git clone git@github.com:wagtail/wagtail-hallo.git`。

Python (Django / Wagtail)

• `pip3 install -e ../path/to/wagtail-hallo/` -> 将该软件包作为可编辑安装本地安装。
• 确保将`'wagtail_hallo'`添加到您的`settings.py`中的`INSTALLED_APPS`。
• 您需要有一个测试应用程序（例如Bakery Demo）和一个Page模型来工作，以及一个模板。
  • 参考模型请见test/testapp/models.py
  • 参考模板请见test/testapp/templates/hallo_test_page.html
• 创建模型后，请记住运行python manage.py makemigrations和python manage.py migrate。
• 运行测试：python testmanage.py test
• 为测试模型运行迁移：django-admin makemigrations --settings=wagtail_hallo.test.settings
• 运行代码风格检查：flake8 wagtail_hallo
• 运行格式化：black wagtail_hallo

JavaScript & CSS (前端)

目前前端工具基于Node & NPM，仅用于格式化和检查代码。此仓库有意不使用任何构建工具，因此JavaScript和CSS必须在不满足该要求的情况下编写。

• nvm use - 确保您处于正确的Node版本。
• npm install --no-save - 安装NPM包。
• npm run fix - 解析JS/CSS文件并修复任何可以修复的内容。
• npm run lint - 运行代码风格检查。
• npm run format - 在大多数文件上运行Prettier格式化（非Python文件）。
• npm test - 运行测试（Jest）。
• npm run preflight - 运行所有代码风格检查/格式化/Jest检查，必须在提交代码之前完成。

发布清单

• 在wagtail_hallo/__init__.py中更新VERSION。
• 使用新的支持的Python、Django或Wagtail版本更新tox.ini、setup.py、README.md、package.json和workflows/ci.yml。
• 运行npm install以确保package-lock.json已更新。
• 更新分类器（例如在setup.py中基于状态（#为数字）的"Development Status :: # - Alpha"更新）。
• 在setup.py中使用新发布版本更新。
• 在CHANGELOG.md中更新发布日期。
• 推送到PyPI。
  • 安装twine：pip install twine
  • 清理并打包：python3 setup.py clean --all sdist bdist_wheel
  • 上传到PyPI：twine upload dist/* <-- 推送到PyPI
• 创建稳定发布分支（例如stable/1.0.x）。
• 在GitHub上创建发布（例如v1.0.0）。

感谢

非常感谢所有支持者、贡献者和基于惊人的Hallo.js编辑器构建的Wagtail用户。我们感谢Wagtail核心团队和Torchbox的开发者赞助了大部分初始开发。感谢LB将Hallo.js集成从Wagtail转移到wagtail-hallo软件包。还要特别感谢Hallo.js编辑器的原始创建者。感谢。