支持CKEditor的django CMS文本插件
项目描述
CKEditor（v4）是一个现成的HTML文本编辑器，旨在简化网络内容创建。它是一个所见即所得编辑器，将常见的文字处理功能直接带到您的网页上。使用我们社区维护的编辑器增强您的网站体验。此软件包旨在将CKEditor集成到django CMS作为文本插件。
为此项目做出贡献并赢取奖励
由于这是一个开源项目，我们欢迎每个人参与项目并获得奖励。成为这个出色社区的一员，帮助我们使django CMS成为世界上最好的CMS。
我们很高兴收到您的反馈，形式为问题和拉取请求。在提交您的拉取请求之前，请审查我们的贡献指南。
我们感谢所有帮助创建和维护此软件包的贡献者。贡献者名单在贡献者部分。
您可以做出的最简单贡献之一是帮助将此插件翻译成Transifex。
文档
请参阅setup.py文件中的REQUIREMENTS以获取列出的其他依赖项
当前集成的CKEditor版本为：4.17.2
有关完整文档，请访问：https://ckeditor.npmjs.net.cn/
安装
此插件需要正确安装3.4.5或更高版本的django CMS。
对于手动安装
运行pip install djangocms-text-ckeditor
将djangocms_text_ckeditor添加到您的INSTALLED_APPS
运行python manage.py migrate djangocms_text_ckeditor
从cms.plugins.text升级
从INSTALLED_APPS中删除cms.plugins.text
将djangocms_text_ckeditor添加到INSTALLED_APPS
运行python manage.py migrate djangocms_text_ckeditor 0001 --fake
配置
内联编辑功能
内联编辑允许编辑器直接点击文本插件并更改django CMS编辑模式中的内容。CKEditor直接出现在文本字段周围并可正常使用。更改将在文本字段失去焦点时立即保存。
行内编辑需要将HTML文本封装在编辑模式下的<div>中。这可能会对网站的CSS造成一些副作用，例如直接子规则。
要启用行内编辑，请将以下行添加到您项目的settings.py
TEXT_INLINE_EDITING = True
这将添加一个切换按钮到工具栏，允许切换当前会话的行内编辑。
当行内编辑处于活动状态时，编辑器会在每次失去焦点时保存插件的內容。如果只有文本已更改，则用户可以立即继续编辑。如果更改了文本启用的插件，添加或删除了插件，页面将刷新以更新页面树并获取更改插件的正确渲染版本。
占位符中的默认内容
如果您使用Django-CMS >= 3.0，您可以在“default_plugins”中使用TextPlugin（有关Django CMS 3.0中的CMS_PLACEHOLDER_CONF设置文档，请参阅Django CMS 3.0）。TextPlugin只需要一个值：在body中写入您默认的HTML内容。如果您想为您自动添加的插件添加一些“默认子元素”（例如，一个LinkPlugin），您必须在body中放置子元素引用。引用是"%(_tag_child_<order>)s"，带有插入的子元素顺序。例如
CMS_PLACEHOLDER_CONF = {
'content': {
'name' : _('Content'),
'plugins': ['TextPlugin', 'LinkPlugin'],
'default_plugins':[
{
'plugin_type':'TextPlugin',
'values':{
'body':'<p>Great websites : %(_tag_child_1)s and %(_tag_child_2)s</p>'
},
'children':[
{
'plugin_type':'LinkPlugin',
'values':{
'name':'django',
'url':'https://django.ac.cn/'
},
},
{
'plugin_type':'LinkPlugin',
'values':{
'name':'django-cms',
'url':'https://www.django-cms.org'
},
},
]
},
]
}
}
CKEDITOR_SETTINGS
您可以在settings.py中覆盖CKEDITOR_SETTINGS设置
CKEDITOR_SETTINGS = {
'language': '{{ language }}',
'toolbar': 'CMS',
'skin': 'moono-lisa',
}
这是包含所有CKEditor设置的默认字典。
自定义插件编辑器
要自定义插件编辑器，请使用toolbar_CMS属性，如下所示
CKEDITOR_SETTINGS = {
'language': '{{ language }}',
'toolbar_CMS': [
['Undo', 'Redo'],
['cmsplugins', '-', 'ShowBlocks'],
['Format', 'Styles'],
],
'skin': 'moono-lisa',
}
自定义HTMLField编辑器
如果您在自己的模型中使用djangocms_text_ckeditor.fields中的HTMLField，请使用toolbar_HTMLField属性
CKEDITOR_SETTINGS = {
'language': '{{ language }}',
'toolbar_HTMLField': [
['Undo', 'Redo'],
['ShowBlocks'],
['Format', 'Styles'],
],
'skin': 'moono-lisa',
}
您可以通过在设置中使用不同的配置参数进一步自定义每个HTMLField字段
models.py
class Model1(models.Model):
text = HTMLField(configuration='CKEDITOR_SETTINGS_MODEL1')
class Model2(models.Model):
text = HTMLField(configuration='CKEDITOR_SETTINGS_MODEL2')
settings.py
CKEDITOR_SETTINGS_MODEL1 = {
'toolbar_HTMLField': [
['Undo', 'Redo'],
['ShowBlocks'],
['Format', 'Styles'],
['Bold', 'Italic', 'Underline', '-', 'Subscript', 'Superscript', '-', 'RemoveFormat'],
]
}
CKEDITOR_SETTINGS_MODEL2 = {
'toolbar_HTMLField': [
['Undo', 'Redo'],
['Bold', 'Italic', 'Underline', '-', 'Subscript', 'Superscript', '-', 'RemoveFormat'],
]
}
将configuration=’MYSETTING’添加到您想要自定义的HTMLField使用中；
定义一个与HTMLField实例的configuration参数中使用的字符串相同的设置参数，并使用所需的配置；
未在您的自定义配置中指定的值将从全局CKEDITOR_SETTINGS中获取。
有关所有可用设置的概述，请参阅此处
行内预览
如果text_editor_preview不是False，则TextPlugin的子插件可以直接在CKEditor中渲染。但是，有几个重要点需要注意
默认情况下，CKEditor不会在编辑区域加载您项目的CSS，并具有有关空标签的特定设置，这意味着除非CKEditor配置正确，否则事情可能不会如您所愿。
请参阅示例
阻止CKEditor删除空span（对图标字体很有用）
如果您覆盖了小部件的默认行为，请注意这需要属性“allowedContent”包含cms-plugin[*]，因为这个自定义标签允许行内预览被渲染
重要提示：请避免在文本启用的插件的__str__表示中使用HTML标签 - 这会破坏行内预览。
如果您想在另一个插件内部作为子插件添加文本插件，并根据父插件有条件地对其进行样式设置，您可以将 CMSPluginBase.child_ckeditor_body_css_class 属性添加到父类中。
拖放图片
在 IE 和基于 Firefox 的浏览器中，可以将图片拖放到文本编辑器中。这张图片是 base64 编码的，并以 'data' 标签的形式存在于 'src' 属性中。
我们将检测这些图片，对它们进行编码，并将它们转换为图片插件。如果您想为您自己的图片插件覆盖此行为
有一个名为
TEXT_SAVE_IMAGE_FUNCTION = 'djangocms_text_ckeditor.picture_save.create_picture_plugin'
的设置，您可以在 settings.py 中覆盖此设置，并将其指向处理图片保存的函数。有关详细信息，请查看函数 create_picture_plugin。
要完全禁用此功能，请将 TEXT_SAVE_IMAGE_FUNCTION = None。
作为模型字段的使用
如果您想在您的模型字段中使用此小部件，可以这样做！只需像这样导入提供的 HTMLField
from djangocms_text_ckeditor.fields import HTMLField
并在您的模型中使用它，就像使用 TextField 一样
class MyModel(models.Model):
myfield = HTMLField(blank=True)
此字段不允许您在文本编辑器中嵌入任何其他 CMS 插件。插件只能嵌入在 Placeholder 字段中。
如果您需要在 HTML 字段中嵌入其他插件，请将 HTMLField 转换为 Placeholderfield，并配置占位符以仅接受 TextPlugin。有关在 CMS 之外使用占位符的更多信息，请参阅
http://docs.django-cms.org/en/latest/how_to/placeholders.html
自动连字符文本
您可以将输入到编辑器中的文本进行连字符处理，这样就可以在正确的音节边界处自动添加 HTML 实体 ­（软连字符）。
要激活此功能，请运行 pip install django-softhyphen。在 settings.py 中，将 'softhyphen' 添加到 INSTALLED_APPS 列表中。 django-softhyphen 还为 25 种自然语言安装了连字符字典。
如果您已经安装了 django-softhyphen 但不想进行软连字符处理，请将 TEXT_AUTO_HYPHENATE 设置为 False。
扩展插件
您可以使用此插件作为基础来创建您自己的基于 CKEditor 的插件。
您需要创建自己的插件模型，它扩展了 AbstractText
from djangocms_text_ckeditor.models import AbstractText
class MyTextModel(AbstractText):
title = models.CharField(max_length=100)
以及一个扩展 TextPlugin 类的插件类
from djangocms_text_ckeditor.cms_plugins import TextPlugin
from .models import MyTextModel
class MyTextPlugin(TextPlugin):
name = _(u"My text plugin")
model = MyTextModel
plugin_pool.register_plugin(MyTextPlugin)
请注意，如果您覆盖了从基础 TextPlugin 类继承的 render 方法，任何子文本插件都将无法正确渲染。您必须调用 super render 方法，以便 plugin_tags_to_user_html() 能够渲染 body 字段中定位的所有子插件。例如
from djangocms_text_ckeditor.cms_plugins import TextPlugin
from .models import MyTextModel
class MyTextPlugin(TextPlugin):
name = _(u"My text plugin")
model = MyTextModel
def render(self, context, instance, placeholder):
context.update({
'name': instance.name,
})
# Other custom render code you may have
return super().render(context, instance, placeholder)
plugin_pool.register_plugin(MyTextPlugin)
您还可以像其他插件一样进一步 自定义您的插件。
将插件添加到“CMS 插件”下拉菜单
如果您已经创建了一个您想在文本插件中使用并希望在下拉菜单中显示的插件，您可以通过将插件的 text_enabled 属性设置为 True（默认值为 False）来实现。这意味着您将插件的属性 text_enabled 设置为 True。以下是一个非常简单的实现示例
class MyTextPlugin(TextPlugin):
name = "My text plugin"
model = MyTextModel
text_enabled = True
当插件被选中时，它将出现在 CMS 插件 下拉菜单中，您可以在编辑器中找到它。这使得用户可以轻松地在熟悉的文本块中插入特殊内容。
插件甚至可以在文本编辑器中预览。 专业提示：请确保您的插件提供自己的 icon_alt 方法。这样，如果您有很多 text_enabled 插件，它可以显示有关它的提示。例如，如果您创建了一个显示可配置产品价格的插件，它可以显示包含该产品名称的工具提示。
有关使用插件扩展CMS的更多信息，请参阅 django-cms文档 了解如何进行此操作。
可配置的清理器
djangocms-text-ckeditor 使用 html5lib 清理HTML以避免安全问题并检查HTML代码的正确性。清理可能会删除一些用例（如 iframe）中使用的标签；您可以通过覆盖 TEXT_ADDITIONAL_TAGS 和 TEXT_ADDITIONAL_ATTRIBUTES 设置来自定义允许的标签和属性
TEXT_ADDITIONAL_TAGS = ('iframe',)
TEXT_ADDITIONAL_ATTRIBUTES = ('scrolling', 'allowfullscreen', 'frameborder')
如果您需要更多对清理的控制，可以扩展 AllowTokenParser 类并在 parse() 方法中定义您的逻辑。例如，如果您想在清理过程中跳过您的甜甜圈属性，您可以创建一个类似于以下内容的类
from djangocms_text_ckeditor.sanitizer import AllowTokenParser
class DonutAttributeParser(AllowTokenParser):
def parse(self, attribute, val):
return attribute.startswith('donut-')
并将您的类添加到 ALLOW_TOKEN_PARSERS 设置中
ALLOW_TOKEN_PARSERS = (
'mymodule.DonutAttributeParser',
)
注意：某些版本的CKEditor在将文本传递到Web服务器之前会预先清理文本，这使得上述设置无效。为了确保不会发生这种情况，您可能需要将以下参数添加到 CKEDITOR_SETTINGS
... 'basicEntities': False, 'entities': False, ...
要完全禁用此功能，请设置 TEXT_HTML_SANITIZE = False。
有关更多信息，请参阅 html5lib文档。
搜索
djangocms-text-ckeditor与 aldryn-search 一起工作得很好，用于使用Haystack进行文本内容。
开发
预提交钩子
该存储库使用预提交git钩子来运行确保代码质量的工具。
要利用此功能，请运行 pip install pre-commit 然后运行 pre-commit install。
构建JavaScript
djangocms-text-ckeditor 分发了插件正常运行所需的javascript包，其中包含CKEditor本身以及所有在CMS中运行的必要插件。要构建此包，您需要使用 npm install 安装依赖项，然后运行 gulp bundle。
此命令还会根据文件内容更新加载的文件名。
更新CKEditor
请确保使用 构建配置 中的URL。
运行测试
您可以通过执行以下操作来运行测试
virtualenv env source env/bin/activate pip install -r tests/requirements.txt python setup.py test
djangocms_text_ckeditor-5.1.6.tar.gz的散列值
| 算法 | 散列摘要 | |
|---|---|---|
| SHA256 | a30d92e052643b4dfb4149007f71617959763b805a2f0d4f492095441865457d |
|
| MD5 | ca46a7eef183a83478ca0c0345981d52 |
|
| BLAKE2b-256 | 4427425991a855b3a9e6d0b651285d7d20b8ab74af8630bc0ed8a0fac0dafa7a |
djangocms_text_ckeditor-5.1.6-py3-none-any.whl的散列值
| 算法 | 散列摘要 | |
|---|---|---|
| SHA256 | a2bc1b5e5a3e7febf0413e82e9f3f06a82e4bfdbd36b0071fdb334b29a466846 |
|
| MD5 | 8180a7ace2fd1d6d78fda8ec97a72f07 |
|
| BLAKE2b-256 | eaa983559f1b4c13468f2beb93be9343c29f3c236f275c7845551353ea2112d8 |
