========================
django CMS Text CKEditor
========================
|pypi| |coverage| |python| |django| |djangocms| |djangocms4|
.. note::
Version 5 of this package does not include a move to CKEditor version 5
CKEditor (v4) is a ready-for-use HTML text editor designed to simplify web content
creation. It's a WYSIWYG editor that brings common word processor features
directly to your web pages. Enhance your website experience with our community
maintained editor. This package aims to integrate CKEditor into django CMS as
a text plugin.
.. note::
This project is endorsed by the `django CMS Association <https://www.django-cms.org/en/about-us/>`_.
That means that it is officially accepted by the dCA as being in line with our roadmap vision and development/plugin policy.
Join us on `Slack <https://www.django-cms.org/slack/>`_.
.. WARNING::
- For django CMS 3.8.x+ use ``djangocms-text-ckeditor`` >= 4.x.x (e.g.: version 4.0.0).
- For django CMS 3.4.x+ use ``djangocms-text-ckeditor`` >= 3.2.x (e.g.: version 3.2.1).
.. image:: preview.gif
*******************************************
Contribute to this project and win rewards
*******************************************
Because this is a an open-source project, we welcome everyone to
`get involved in the project <https://www.django-cms.org/en/contribute/>`_ and
`receive a reward <https://www.django-cms.org/en/bounty-program/>`_ for their contribution.
Become part of a fantastic community and help us make django CMS the best CMS in the world.
We'll be delighted to receive your
feedback in the form of issues and pull requests. Before submitting your
pull request, please review our `contribution guidelines
<http://docs.django-cms.org/en/latest/contributing/index.html>`_.
We're grateful to all contributors who have helped create and maintain this package.
Contributors are listed at the `contributors <https://github.com/divio/djangocms-text-ckeditor/graphs/contributors>`_
section.
One of the easiest contributions you can make is helping to translate this addon on
`Transifex <https://www.transifex.com/projects/p/djangocms-text-ckeditor/>`_.
Documentation
=============
See ``REQUIREMENTS`` in the `setup.py <https://github.com/django-cms/djangocms-text-ckeditor/blob/master/setup.py>`_
file for additional dependencies listed in the
The current integrated Version of CKEditor is: **4.17.2**
For a full documentation visit: http://ckeditor.com/
Installation
------------
This plugin requires `django CMS` 3.4.5 or higher to be properly installed.
For a manual install:
* run ``pip install djangocms-text-ckeditor``
* add ``djangocms_text_ckeditor`` to your ``INSTALLED_APPS``
* run ``python manage.py migrate djangocms_text_ckeditor``
Upgrading from ``cms.plugins.text``
***********************************
* remove ``cms.plugins.text`` from ``INSTALLED_APPS``
* add ``djangocms_text_ckeditor`` to ``INSTALLED_APPS``
* run ``python manage.py migrate djangocms_text_ckeditor 0001 --fake``
Configuration
-------------
Inline editing feature
**********************
Inline editing allows editors to directly click on a text plugin and change
the contents in django CMS' edit mode. The CKEditor appears directly around
the text field and can be used normally. Changes are saved as soon as the
text field leaves focus.
Inline editing requires to encapsulate the HTML text in a ``<div>`` in
edit mode. This might cause some side effects with a site's CSS, e.g. direct
child rules.
To activate inline editing add the following line in your project's
``settings.py``::
TEXT_INLINE_EDITING = True
This will add a toggle button to the toolbar to allow to switch inline editing
on and off for the current session.
When inline editing is active the editor will save the plugin's content each time it loses
focus. If only text has changed the user can immediately continue to edit. If
a text-enabled plugin was changed, added, or removed he page will refresh to
update the page tree and get the correctly rendered version of the changed
plugin.
Default content in Placeholder
******************************
If you use Django-CMS >= 3.0, you can use ``TextPlugin`` in "default_plugins"
(see docs about the `CMS_PLACEHOLDER_CONF`_ setting in Django CMS 3.0).
``TextPlugin`` requires just one value: ``body`` where you write your default
HTML content. If you want to add some "default children" to your
automagically added plugin (i.e. a ``LinkPlugin``), you have to put children
references in the body. References are ``"%(_tag_child_<order>)s"`` with the
inserted order of children. For example::
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://www.djangoproject.com/'
},
},
{
'plugin_type':'LinkPlugin',
'values':{
'name':'django-cms',
'url':'https://www.django-cms.org'
},
},
]
},
]
}
}
.. _CMS_PLACEHOLDER_CONF: http://docs.django-cms.org/en/latest/how_to/placeholders.html?highlight=cms_placeholder_conf
CKEDITOR_SETTINGS
*****************
You can override the setting ``CKEDITOR_SETTINGS`` in your settings.py::
CKEDITOR_SETTINGS = {
'language': '{{ language }}',
'toolbar': 'CMS',
'skin': 'moono-lisa',
}
This is the default dict that holds all **CKEditor** settings.
Customizing plugin editor
#########################
To customize the plugin editor, use `toolbar_CMS` attribute, as in::
CKEDITOR_SETTINGS = {
'language': '{{ language }}',
'toolbar_CMS': [
['Undo', 'Redo'],
['cmsplugins', '-', 'ShowBlocks'],
['Format', 'Styles'],
],
'skin': 'moono-lisa',
}
Customizing HTMLField editor
############################
If you use ``HTMLField`` from ``djangocms_text_ckeditor.fields`` in your own
models, use `toolbar_HTMLField` attribute::
CKEDITOR_SETTINGS = {
'language': '{{ language }}',
'toolbar_HTMLField': [
['Undo', 'Redo'],
['ShowBlocks'],
['Format', 'Styles'],
],
'skin': 'moono-lisa',
}
You can further customize each `HTMLField` field by using different
configuration parameter in your settings::
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'],
]
}
#. Add `configuration='MYSETTING'` to the `HTMLField` usage(s) you want to
customize;
#. Define a setting parameter named as the string used in the `configuration`
argument of the `HTMLField` instance with the desired configuration;
Values not specified in your custom configuration will be taken from the global
``CKEDITOR_SETTINGS``.
For an overview of all the available settings have a look here:
http://docs.ckeditor.com/#!/api/CKEDITOR.config
Inline preview
--------------
The child plugins of TextPlugin can be rendered directly inside CKEditor if
``text_editor_preview`` isn't ``False``. However there are few important points
to note:
- by default CKEditor doesn't load CSS of your project inside the editing area
and has specific settings regarding empty tags, which could mean that things
will not look as they should until CKEditor is configured correctly.
See examples:
- `add styles and js configuration`_
- `stop CKEditor from removing empty spans`_ (useful for iconfonts)
- if you override widget default behaviour - be aware that it requires the
property "`allowedContent`_" `to contain`_ ``cms-plugin[*]`` as this custom tag is
what allows the inline previews to be rendered
- Important note: please avoid html tags in ``__str__`` representation of text
enabled plugins - this messes up inline preview.
- If you're adding a Text Plugin as a child inside another plugin and want to style it
conditionally based on the parent - you can add ``CMSPluginBase.child_ckeditor_body_css_class``
attribute to the parent class.
.. _add styles and js configuration: https://github.com/divio/django-cms-demo/blob/7a104acaa749c52a8ed4870a74898e38daf20e46/src/settings.py#L318-L324
.. _stop CKEditor from removing empty spans: https://github.com/divio/django-cms-explorer/blob/908a88afa4e1d1176e267e77eb5c61e31ef0f9e5/static/js/addons/ckeditor.wysiwyg.js#L73
.. _allowedContent: http://docs.ckeditor.com/#!/guide/dev_allowed_content_rules
.. _to contain: https://github.com/django-cms/djangocms-text-ckeditor/issues/405#issuecomment-276814197
Drag & Drop Images
------------------
In IE and Firefox based browsers it is possible to drag and drop a picture into the text editor.
This image is base64 encoded and lives in the 'src' attribute as a 'data' tag.
We detect this images, encode them and convert them to picture plugins.
If you want to overwrite this behavior for your own picture plugin:
There is a setting called::
TEXT_SAVE_IMAGE_FUNCTION = 'djangocms_text_ckeditor.picture_save.create_picture_plugin'
you can overwrite this setting in your settings.py and point it to a function that handles image saves.
Have a look at the function ``create_picture_plugin`` for details.
To completely disable the feature, set ``TEXT_SAVE_IMAGE_FUNCTION = None``.
Usage as a model field
----------------------
If you want to use the widget on your own model fields, you can! Just import the provided ``HTMLField`` like so::
from djangocms_text_ckeditor.fields import HTMLField
And use it in your models, just like a ``TextField``::
class MyModel(models.Model):
myfield = HTMLField(blank=True)
This field does not allow you to embed any other CMS plugins within the text editor. Plugins can only be embedded
within ``Placeholder`` fields.
If you need to allow additional plugins to be embedded in a HTML field, convert the ``HTMLField`` to a ``Placeholderfield``
and configure the placeholder to only accept TextPlugin. For more information on using placeholders outside of the CMS see:
http://docs.django-cms.org/en/latest/how_to/placeholders.html
Auto Hyphenate Text
-------------------
You can hyphenate the text entered into the editor, so that the HTML entity ``­`` (soft-hyphen_)
automatically is added in between words, at the correct syllable boundary.
To activate this feature, ``pip install django-softhyphen``. In ``settings.py`` add ``'softhyphen'``
to the list of ``INSTALLED_APPS``. django-softhyphen_ also installs hyphening dictionaries for 25
natural languages.
In case you already installed ``django-softhyphen`` but do not want to soft hyphenate, set
``TEXT_AUTO_HYPHENATE`` to ``False``.
.. _soft-hyphen: http://www.w3.org/TR/html4/struct/text.html#h-9.3.3
.. _django-softhyphen: https://github.com/datadesk/django-softhyphen
Extending the plugin
--------------------
.. NOTE::
Added in version 2.0.1
You can use this plugin as base to create your own CKEditor-based plugins.
You need to create your own plugin model extending ``AbstractText``::
from djangocms_text_ckeditor.models import AbstractText
class MyTextModel(AbstractText):
title = models.CharField(max_length=100)
and a plugin class extending ``TextPlugin`` class::
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)
Note that if you override the `render` method that is inherited from the base ``TextPlugin`` class, any child text
plugins will not render correctly. You must call the super ``render`` method in order for ``plugin_tags_to_user_html()``
to render out all child plugins located in the ``body`` field. For example::
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)
You can further `customize your plugin`_ as other plugins.
.. _customize your plugin: http://docs.django-cms.org/en/latest/how_to/custom_plugins.html
Adding plugins to the "CMS Plugins" dropdown
--------------------------------------------
If you have created a plugin that you want to use within Text plugins you can make them appear in the dropdown by
making them `text_enabled`. This means that you assign the property ``text_enabled`` of a plugin to ``True``,
the default value is `False`. Here is a very simple implementation::
class MyTextPlugin(TextPlugin):
name = "My text plugin"
model = MyTextModel
text_enabled = True
When the plugin is picked up, it will be available in the *CMS Plugins* dropdown, which you can find in the editor.
This makes it very easy for users to insert special content in a user-friendly Text block, which they are familiair with.
The plugin will even be previewed in the text editor. **Pro-tip**: make sure your plugin provides its own `icon_alt` method.
That way, if you have many `text_enabled`-plugins, it can display a hint about it. For example, if you created a plugin which displays prices of configurable product, it can display a tooltip with the name of that product.
For more information about extending the CMS with plugins, read `django-cms doc`_ on how to do this.
.. _django-cms doc: http://docs.django-cms.org/en/latest/reference/plugins.html#cms.plugin_base.CMSPluginBase.text_enabled
Configurable sanitizer
----------------------
``djangocms-text-ckeditor`` uses `html5lib`_ to sanitize HTML to avoid
security issues and to check for correct HTML code.
Sanitisation may strip tags usesful for some use cases such as ``iframe``;
you may customize the tags and attributes allowed by overriding the
``TEXT_ADDITIONAL_TAGS`` and ``TEXT_ADDITIONAL_ATTRIBUTES`` settings::
TEXT_ADDITIONAL_TAGS = ('iframe',)
TEXT_ADDITIONAL_ATTRIBUTES = ('scrolling', 'allowfullscreen', 'frameborder')
In case you need more control on sanitisation you can extend AllowTokenParser class and define
your logic into parse() method. For example, if you want to skip your donut attribute during
sanitisation, you can create a class like this::
from djangocms_text_ckeditor.sanitizer import AllowTokenParser
class DonutAttributeParser(AllowTokenParser):
def parse(self, attribute, val):
return attribute.startswith('donut-')
And add your class to ``ALLOW_TOKEN_PARSERS`` settings::
ALLOW_TOKEN_PARSERS = (
'mymodule.DonutAttributeParser',
)
**NOTE**: Some versions of CKEditor will pre-sanitize your text before passing it to the web server,
rendering the above settings useless. To ensure this does not happen, you may need to add the
following parameters to ``CKEDITOR_SETTINGS``::
...
'basicEntities': False,
'entities': False,
...
To completely disable the feature, set ``TEXT_HTML_SANITIZE = False``.
See the `html5lib documentation`_ for further information.
.. _html5lib: https://pypi.python.org/pypi/html5lib
.. _html5lib documentation: https://code.google.com/p/html5lib/wiki/UserDocumentation#Sanitizing_Tokenizer
Search
------
djangocms-text-ckeditor works well with `aldryn-search <https://github.com/aldryn/aldryn-search>`_
to make text content using Haystack.
Development
===========
pre-commit hooks
----------------
The repo uses pre-commit git hooks to run tools which ensure code quality.
To utilise this, run ``pip install pre-commit`` and then ``pre-commit install``.
Building the JavaScript
-----------------------
``djangocms-text-ckeditor`` distributes a javascript bundle required for the
plugin to work, which contains CKEditor itself and all the necessary plugins for
functioning within CMS. To build the bundle you need to have to install
dependencies with ``npm install`` and then to run ``gulp bundle``.
This command also updates the file name loaded based on the file contents.
Updating the CKEditor
---------------------
Make sure to use the url in `build config <https://github.com/divio/djangocms-text-ckeditor/blob/master/djangocms_text_ckeditor/static/djangocms_text_ckeditor/ckeditor/build-config.js#L16>`_.
Running Tests
-------------
You can run tests by executing::
virtualenv env
source env/bin/activate
pip install -r tests/requirements.txt
python setup.py test
.. |pypi| image:: https://badge.fury.io/py/djangocms-text-ckeditor.svg
:target: http://badge.fury.io/py/djangocms-text-ckeditor
.. |build| image:: https://travis-ci.org/divio/djangocms-text-ckeditor.svg?branch=master
:target: https://travis-ci.org/divio/djangocms-text-ckeditor
.. |coverage| image:: https://codecov.io/gh/django-cms/djangocms-text-ckeditor/branch/master/graph/badge.svg
:target: https://codecov.io/gh/django-cms/djangocms-text-ckeditor
.. |python| image:: https://img.shields.io/badge/python-3.7+-blue.svg
:target: https://pypi.org/project/djangocms-text-ckeditor/
.. |django| image:: https://img.shields.io/badge/django-2.2--5.0-blue.svg
:target: https://www.djangoproject.com/
.. |djangocms| image:: https://img.shields.io/badge/django%20CMS-3.7%2B-blue.svg
:target: https://www.django-cms.org/
.. |djangocms4| image:: https://img.shields.io/badge/django%20CMS-4-blue.svg
:target: https://www.django-cms.org/
Raw data
{
"_id": null,
"home_page": "https://github.com/django-cms/djangocms-text-ckeditor",
"name": "djangocms-text-ckeditor",
"maintainer": "Django CMS Association and contributors",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "info@django-cms.org",
"keywords": null,
"author": "Divio AG",
"author_email": "info@divio.ch",
"download_url": "https://files.pythonhosted.org/packages/44/27/425991a855b3a9e6d0b651285d7d20b8ab74af8630bc0ed8a0fac0dafa7a/djangocms_text_ckeditor-5.1.6.tar.gz",
"platform": null,
"description": "========================\ndjango CMS Text CKEditor\n========================\n\n|pypi| |coverage| |python| |django| |djangocms| |djangocms4|\n\n\n.. note::\n\n Version 5 of this package does not include a move to CKEditor version 5\n\n\nCKEditor (v4) is a ready-for-use HTML text editor designed to simplify web content\ncreation. It's a WYSIWYG editor that brings common word processor features\ndirectly to your web pages. Enhance your website experience with our community\nmaintained editor. This package aims to integrate CKEditor into django CMS as\na text plugin.\n\n.. note::\n\n This project is endorsed by the `django CMS Association <https://www.django-cms.org/en/about-us/>`_.\n That means that it is officially accepted by the dCA as being in line with our roadmap vision and development/plugin policy.\n Join us on `Slack <https://www.django-cms.org/slack/>`_.\n\n\n.. WARNING::\n\n - For django CMS 3.8.x+ use ``djangocms-text-ckeditor`` >= 4.x.x (e.g.: version 4.0.0).\n - For django CMS 3.4.x+ use ``djangocms-text-ckeditor`` >= 3.2.x (e.g.: version 3.2.1).\n\n.. image:: preview.gif\n\n\n\n*******************************************\nContribute to this project and win rewards\n*******************************************\n\nBecause this is a an open-source project, we welcome everyone to\n`get involved in the project <https://www.django-cms.org/en/contribute/>`_ and\n`receive a reward <https://www.django-cms.org/en/bounty-program/>`_ for their contribution.\nBecome part of a fantastic community and help us make django CMS the best CMS in the world.\n\nWe'll be delighted to receive your\nfeedback in the form of issues and pull requests. Before submitting your\npull request, please review our `contribution guidelines\n<http://docs.django-cms.org/en/latest/contributing/index.html>`_.\n\nWe're grateful to all contributors who have helped create and maintain this package.\nContributors are listed at the `contributors <https://github.com/divio/djangocms-text-ckeditor/graphs/contributors>`_\nsection.\n\nOne of the easiest contributions you can make is helping to translate this addon on\n`Transifex <https://www.transifex.com/projects/p/djangocms-text-ckeditor/>`_.\n\n\nDocumentation\n=============\n\nSee ``REQUIREMENTS`` in the `setup.py <https://github.com/django-cms/djangocms-text-ckeditor/blob/master/setup.py>`_\nfile for additional dependencies listed in the\n\nThe current integrated Version of CKEditor is: **4.17.2**\n\nFor a full documentation visit: http://ckeditor.com/\n\n\nInstallation\n------------\n\nThis plugin requires `django CMS` 3.4.5 or higher to be properly installed.\n\nFor a manual install:\n\n* run ``pip install djangocms-text-ckeditor``\n* add ``djangocms_text_ckeditor`` to your ``INSTALLED_APPS``\n* run ``python manage.py migrate djangocms_text_ckeditor``\n\n\nUpgrading from ``cms.plugins.text``\n***********************************\n\n* remove ``cms.plugins.text`` from ``INSTALLED_APPS``\n* add ``djangocms_text_ckeditor`` to ``INSTALLED_APPS``\n* run ``python manage.py migrate djangocms_text_ckeditor 0001 --fake``\n\n\nConfiguration\n-------------\n\nInline editing feature\n**********************\n\nInline editing allows editors to directly click on a text plugin and change\nthe contents in django CMS' edit mode. The CKEditor appears directly around\nthe text field and can be used normally. Changes are saved as soon as the\ntext field leaves focus.\n\nInline editing requires to encapsulate the HTML text in a ``<div>`` in\nedit mode. This might cause some side effects with a site's CSS, e.g. direct\nchild rules.\n\nTo activate inline editing add the following line in your project's\n``settings.py``::\n\n TEXT_INLINE_EDITING = True\n\nThis will add a toggle button to the toolbar to allow to switch inline editing\non and off for the current session.\n\nWhen inline editing is active the editor will save the plugin's content each time it loses\nfocus. If only text has changed the user can immediately continue to edit. If\na text-enabled plugin was changed, added, or removed he page will refresh to\nupdate the page tree and get the correctly rendered version of the changed\nplugin.\n\nDefault content in Placeholder\n******************************\n\nIf you use Django-CMS >= 3.0, you can use ``TextPlugin`` in \"default_plugins\"\n(see docs about the `CMS_PLACEHOLDER_CONF`_ setting in Django CMS 3.0).\n``TextPlugin`` requires just one value: ``body`` where you write your default\nHTML content. If you want to add some \"default children\" to your\nautomagically added plugin (i.e. a ``LinkPlugin``), you have to put children\nreferences in the body. References are ``\"%(_tag_child_<order>)s\"`` with the\ninserted order of children. For example::\n\n CMS_PLACEHOLDER_CONF = {\n 'content': {\n 'name' : _('Content'),\n 'plugins': ['TextPlugin', 'LinkPlugin'],\n 'default_plugins':[\n {\n 'plugin_type':'TextPlugin',\n 'values':{\n 'body':'<p>Great websites : %(_tag_child_1)s and %(_tag_child_2)s</p>'\n },\n 'children':[\n {\n 'plugin_type':'LinkPlugin',\n 'values':{\n 'name':'django',\n 'url':'https://www.djangoproject.com/'\n },\n },\n {\n 'plugin_type':'LinkPlugin',\n 'values':{\n 'name':'django-cms',\n 'url':'https://www.django-cms.org'\n },\n },\n ]\n },\n ]\n }\n }\n\n.. _CMS_PLACEHOLDER_CONF: http://docs.django-cms.org/en/latest/how_to/placeholders.html?highlight=cms_placeholder_conf\n\n\nCKEDITOR_SETTINGS\n*****************\n\nYou can override the setting ``CKEDITOR_SETTINGS`` in your settings.py::\n\n CKEDITOR_SETTINGS = {\n 'language': '{{ language }}',\n 'toolbar': 'CMS',\n 'skin': 'moono-lisa',\n }\n\nThis is the default dict that holds all **CKEditor** settings.\n\n\nCustomizing plugin editor\n#########################\n\nTo customize the plugin editor, use `toolbar_CMS` attribute, as in::\n\n CKEDITOR_SETTINGS = {\n 'language': '{{ language }}',\n 'toolbar_CMS': [\n ['Undo', 'Redo'],\n ['cmsplugins', '-', 'ShowBlocks'],\n ['Format', 'Styles'],\n ],\n 'skin': 'moono-lisa',\n }\n\n\nCustomizing HTMLField editor\n############################\n\nIf you use ``HTMLField`` from ``djangocms_text_ckeditor.fields`` in your own\nmodels, use `toolbar_HTMLField` attribute::\n\n CKEDITOR_SETTINGS = {\n 'language': '{{ language }}',\n 'toolbar_HTMLField': [\n ['Undo', 'Redo'],\n ['ShowBlocks'],\n ['Format', 'Styles'],\n ],\n 'skin': 'moono-lisa',\n }\n\n\nYou can further customize each `HTMLField` field by using different\nconfiguration parameter in your settings::\n\n models.py\n\n class Model1(models.Model):\n text = HTMLField(configuration='CKEDITOR_SETTINGS_MODEL1')\n\n class Model2(models.Model):\n text = HTMLField(configuration='CKEDITOR_SETTINGS_MODEL2')\n\n settings.py\n\n CKEDITOR_SETTINGS_MODEL1 = {\n 'toolbar_HTMLField': [\n ['Undo', 'Redo'],\n ['ShowBlocks'],\n ['Format', 'Styles'],\n ['Bold', 'Italic', 'Underline', '-', 'Subscript', 'Superscript', '-', 'RemoveFormat'],\n ]\n }\n\n CKEDITOR_SETTINGS_MODEL2 = {\n 'toolbar_HTMLField': [\n ['Undo', 'Redo'],\n ['Bold', 'Italic', 'Underline', '-', 'Subscript', 'Superscript', '-', 'RemoveFormat'],\n ]\n }\n\n#. Add `configuration='MYSETTING'` to the `HTMLField` usage(s) you want to\n customize;\n#. Define a setting parameter named as the string used in the `configuration`\n argument of the `HTMLField` instance with the desired configuration;\n\nValues not specified in your custom configuration will be taken from the global\n``CKEDITOR_SETTINGS``.\n\nFor an overview of all the available settings have a look here:\n\nhttp://docs.ckeditor.com/#!/api/CKEDITOR.config\n\n\nInline preview\n--------------\n\nThe child plugins of TextPlugin can be rendered directly inside CKEditor if\n``text_editor_preview`` isn't ``False``. However there are few important points\nto note:\n\n- by default CKEditor doesn't load CSS of your project inside the editing area\n and has specific settings regarding empty tags, which could mean that things\n will not look as they should until CKEditor is configured correctly.\n\n See examples:\n\n - `add styles and js configuration`_\n - `stop CKEditor from removing empty spans`_ (useful for iconfonts)\n\n- if you override widget default behaviour - be aware that it requires the\n property \"`allowedContent`_\" `to contain`_ ``cms-plugin[*]`` as this custom tag is\n what allows the inline previews to be rendered\n\n- Important note: please avoid html tags in ``__str__`` representation of text\n enabled plugins - this messes up inline preview.\n\n- If you're adding a Text Plugin as a child inside another plugin and want to style it\n conditionally based on the parent - you can add ``CMSPluginBase.child_ckeditor_body_css_class``\n attribute to the parent class.\n\n.. _add styles and js configuration: https://github.com/divio/django-cms-demo/blob/7a104acaa749c52a8ed4870a74898e38daf20e46/src/settings.py#L318-L324\n.. _stop CKEditor from removing empty spans: https://github.com/divio/django-cms-explorer/blob/908a88afa4e1d1176e267e77eb5c61e31ef0f9e5/static/js/addons/ckeditor.wysiwyg.js#L73\n.. _allowedContent: http://docs.ckeditor.com/#!/guide/dev_allowed_content_rules\n.. _to contain: https://github.com/django-cms/djangocms-text-ckeditor/issues/405#issuecomment-276814197\n\n\nDrag & Drop Images\n------------------\n\nIn IE and Firefox based browsers it is possible to drag and drop a picture into the text editor.\nThis image is base64 encoded and lives in the 'src' attribute as a 'data' tag.\n\nWe detect this images, encode them and convert them to picture plugins.\nIf you want to overwrite this behavior for your own picture plugin:\n\nThere is a setting called::\n\n TEXT_SAVE_IMAGE_FUNCTION = 'djangocms_text_ckeditor.picture_save.create_picture_plugin'\n\nyou can overwrite this setting in your settings.py and point it to a function that handles image saves.\nHave a look at the function ``create_picture_plugin`` for details.\n\nTo completely disable the feature, set ``TEXT_SAVE_IMAGE_FUNCTION = None``.\n\n\nUsage as a model field\n----------------------\n\nIf you want to use the widget on your own model fields, you can! Just import the provided ``HTMLField`` like so::\n\n from djangocms_text_ckeditor.fields import HTMLField\n\nAnd use it in your models, just like a ``TextField``::\n\n class MyModel(models.Model):\n myfield = HTMLField(blank=True)\n\nThis field does not allow you to embed any other CMS plugins within the text editor. Plugins can only be embedded\nwithin ``Placeholder`` fields.\n\nIf you need to allow additional plugins to be embedded in a HTML field, convert the ``HTMLField`` to a ``Placeholderfield``\nand configure the placeholder to only accept TextPlugin. For more information on using placeholders outside of the CMS see:\n\nhttp://docs.django-cms.org/en/latest/how_to/placeholders.html\n\n\nAuto Hyphenate Text\n-------------------\n\nYou can hyphenate the text entered into the editor, so that the HTML entity ``­`` (soft-hyphen_)\nautomatically is added in between words, at the correct syllable boundary.\n\nTo activate this feature, ``pip install django-softhyphen``. In ``settings.py`` add ``'softhyphen'``\nto the list of ``INSTALLED_APPS``. django-softhyphen_ also installs hyphening dictionaries for 25\nnatural languages.\n\nIn case you already installed ``django-softhyphen`` but do not want to soft hyphenate, set\n``TEXT_AUTO_HYPHENATE`` to ``False``.\n\n.. _soft-hyphen: http://www.w3.org/TR/html4/struct/text.html#h-9.3.3\n.. _django-softhyphen: https://github.com/datadesk/django-softhyphen\n\n\nExtending the plugin\n--------------------\n\n.. NOTE::\n Added in version 2.0.1\n\nYou can use this plugin as base to create your own CKEditor-based plugins.\n\nYou need to create your own plugin model extending ``AbstractText``::\n\n from djangocms_text_ckeditor.models import AbstractText\n\n class MyTextModel(AbstractText):\n title = models.CharField(max_length=100)\n\nand a plugin class extending ``TextPlugin`` class::\n\n from djangocms_text_ckeditor.cms_plugins import TextPlugin\n from .models import MyTextModel\n\n\n class MyTextPlugin(TextPlugin):\n name = _(u\"My text plugin\")\n model = MyTextModel\n\n plugin_pool.register_plugin(MyTextPlugin)\n\nNote that if you override the `render` method that is inherited from the base ``TextPlugin`` class, any child text\nplugins will not render correctly. You must call the super ``render`` method in order for ``plugin_tags_to_user_html()``\nto render out all child plugins located in the ``body`` field. For example::\n\n from djangocms_text_ckeditor.cms_plugins import TextPlugin\n from .models import MyTextModel\n\n\n class MyTextPlugin(TextPlugin):\n name = _(u\"My text plugin\")\n model = MyTextModel\n\n def render(self, context, instance, placeholder):\n context.update({\n 'name': instance.name,\n })\n # Other custom render code you may have\n return super().render(context, instance, placeholder)\n\n plugin_pool.register_plugin(MyTextPlugin)\n\nYou can further `customize your plugin`_ as other plugins.\n\n.. _customize your plugin: http://docs.django-cms.org/en/latest/how_to/custom_plugins.html\n\n\nAdding plugins to the \"CMS Plugins\" dropdown\n--------------------------------------------\n\nIf you have created a plugin that you want to use within Text plugins you can make them appear in the dropdown by\nmaking them `text_enabled`. This means that you assign the property ``text_enabled`` of a plugin to ``True``,\nthe default value is `False`. Here is a very simple implementation::\n\n class MyTextPlugin(TextPlugin):\n name = \"My text plugin\"\n model = MyTextModel\n text_enabled = True\n\nWhen the plugin is picked up, it will be available in the *CMS Plugins* dropdown, which you can find in the editor.\nThis makes it very easy for users to insert special content in a user-friendly Text block, which they are familiair with.\n\nThe plugin will even be previewed in the text editor. **Pro-tip**: make sure your plugin provides its own `icon_alt` method.\nThat way, if you have many `text_enabled`-plugins, it can display a hint about it. For example, if you created a plugin which displays prices of configurable product, it can display a tooltip with the name of that product.\n\nFor more information about extending the CMS with plugins, read `django-cms doc`_ on how to do this.\n\n.. _django-cms doc: http://docs.django-cms.org/en/latest/reference/plugins.html#cms.plugin_base.CMSPluginBase.text_enabled\n\n\nConfigurable sanitizer\n----------------------\n\n``djangocms-text-ckeditor`` uses `html5lib`_ to sanitize HTML to avoid\nsecurity issues and to check for correct HTML code.\nSanitisation may strip tags usesful for some use cases such as ``iframe``;\nyou may customize the tags and attributes allowed by overriding the\n``TEXT_ADDITIONAL_TAGS`` and ``TEXT_ADDITIONAL_ATTRIBUTES`` settings::\n\n TEXT_ADDITIONAL_TAGS = ('iframe',)\n TEXT_ADDITIONAL_ATTRIBUTES = ('scrolling', 'allowfullscreen', 'frameborder')\n\nIn case you need more control on sanitisation you can extend AllowTokenParser class and define\nyour logic into parse() method. For example, if you want to skip your donut attribute during\nsanitisation, you can create a class like this::\n\n from djangocms_text_ckeditor.sanitizer import AllowTokenParser\n\n\n class DonutAttributeParser(AllowTokenParser):\n\n def parse(self, attribute, val):\n return attribute.startswith('donut-')\n\nAnd add your class to ``ALLOW_TOKEN_PARSERS`` settings::\n\n ALLOW_TOKEN_PARSERS = (\n 'mymodule.DonutAttributeParser',\n )\n\n**NOTE**: Some versions of CKEditor will pre-sanitize your text before passing it to the web server,\nrendering the above settings useless. To ensure this does not happen, you may need to add the\nfollowing parameters to ``CKEDITOR_SETTINGS``::\n\n ...\n 'basicEntities': False,\n 'entities': False,\n ...\n\nTo completely disable the feature, set ``TEXT_HTML_SANITIZE = False``.\n\nSee the `html5lib documentation`_ for further information.\n\n.. _html5lib: https://pypi.python.org/pypi/html5lib\n.. _html5lib documentation: https://code.google.com/p/html5lib/wiki/UserDocumentation#Sanitizing_Tokenizer\n\n\nSearch\n------\n\ndjangocms-text-ckeditor works well with `aldryn-search <https://github.com/aldryn/aldryn-search>`_\nto make text content using Haystack.\n\n\nDevelopment\n===========\n\npre-commit hooks\n----------------\n\nThe repo uses pre-commit git hooks to run tools which ensure code quality.\n\nTo utilise this, run ``pip install pre-commit`` and then ``pre-commit install``.\n\nBuilding the JavaScript\n-----------------------\n\n``djangocms-text-ckeditor`` distributes a javascript bundle required for the\nplugin to work, which contains CKEditor itself and all the necessary plugins for\nfunctioning within CMS. To build the bundle you need to have to install\ndependencies with ``npm install`` and then to run ``gulp bundle``.\n\nThis command also updates the file name loaded based on the file contents.\n\n\nUpdating the CKEditor\n---------------------\n\nMake sure to use the url in `build config <https://github.com/divio/djangocms-text-ckeditor/blob/master/djangocms_text_ckeditor/static/djangocms_text_ckeditor/ckeditor/build-config.js#L16>`_.\n\n\nRunning Tests\n-------------\n\nYou can run tests by executing::\n\n virtualenv env\n source env/bin/activate\n pip install -r tests/requirements.txt\n python setup.py test\n\n\n.. |pypi| image:: https://badge.fury.io/py/djangocms-text-ckeditor.svg\n :target: http://badge.fury.io/py/djangocms-text-ckeditor\n.. |build| image:: https://travis-ci.org/divio/djangocms-text-ckeditor.svg?branch=master\n :target: https://travis-ci.org/divio/djangocms-text-ckeditor\n.. |coverage| image:: https://codecov.io/gh/django-cms/djangocms-text-ckeditor/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/django-cms/djangocms-text-ckeditor\n.. |python| image:: https://img.shields.io/badge/python-3.7+-blue.svg\n :target: https://pypi.org/project/djangocms-text-ckeditor/\n.. |django| image:: https://img.shields.io/badge/django-2.2--5.0-blue.svg\n :target: https://www.djangoproject.com/\n.. |djangocms| image:: https://img.shields.io/badge/django%20CMS-3.7%2B-blue.svg\n :target: https://www.django-cms.org/\n.. |djangocms4| image:: https://img.shields.io/badge/django%20CMS-4-blue.svg\n :target: https://www.django-cms.org/\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Text Plugin for django CMS with CKEditor support",
"version": "5.1.6",
"project_urls": {
"Homepage": "https://github.com/django-cms/djangocms-text-ckeditor"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eaa983559f1b4c13468f2beb93be9343c29f3c236f275c7845551353ea2112d8",
"md5": "8180a7ace2fd1d6d78fda8ec97a72f07",
"sha256": "a2bc1b5e5a3e7febf0413e82e9f3f06a82e4bfdbd36b0071fdb334b29a466846"
},
"downloads": -1,
"filename": "djangocms_text_ckeditor-5.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8180a7ace2fd1d6d78fda8ec97a72f07",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 2090276,
"upload_time": "2024-09-18T08:19:20",
"upload_time_iso_8601": "2024-09-18T08:19:20.056052Z",
"url": "https://files.pythonhosted.org/packages/ea/a9/83559f1b4c13468f2beb93be9343c29f3c236f275c7845551353ea2112d8/djangocms_text_ckeditor-5.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4427425991a855b3a9e6d0b651285d7d20b8ab74af8630bc0ed8a0fac0dafa7a",
"md5": "ca46a7eef183a83478ca0c0345981d52",
"sha256": "a30d92e052643b4dfb4149007f71617959763b805a2f0d4f492095441865457d"
},
"downloads": -1,
"filename": "djangocms_text_ckeditor-5.1.6.tar.gz",
"has_sig": false,
"md5_digest": "ca46a7eef183a83478ca0c0345981d52",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 1751615,
"upload_time": "2024-09-18T08:19:21",
"upload_time_iso_8601": "2024-09-18T08:19:21.608402Z",
"url": "https://files.pythonhosted.org/packages/44/27/425991a855b3a9e6d0b651285d7d20b8ab74af8630bc0ed8a0fac0dafa7a/djangocms_text_ckeditor-5.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-18 08:19:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "django-cms",
"github_project": "djangocms-text-ckeditor",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "djangocms-text-ckeditor"
}
JSON
