Repository files navigation

CKEditor (v4) is a ready-for-use HTML text editor designed to simplify web contentcreation. It's a WYSIWYG editor that brings common word processor featuresdirectly to your web pages. Enhance your website experience with our communitymaintained editor. This package aims to integrate CKEditor into django CMS asa text plugin.

Because this is a an open-source project, we welcome everyone toget involved in the project andreceive a reward 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 yourfeedback in the form of issues and pull requests. Before submitting yourpull request, please review ourcontribution guidelines.

We're grateful to all contributors who have helped create and maintain this package.Contributors are listed at thecontributorssection.

One of the easiest contributions you can make is helping to translate this addon onTransifex.

SeeREQUIREMENTS in thesetup.pyfile for additional dependencies listed in the

The current integrated Version of CKEditor is:4.17.2

For a full documentation visit:http://ckeditor.com/

This plugin requires django CMS 3.4.5 or higher to be properly installed.

For a manual install:

• runpip install djangocms-text-ckeditor
• adddjangocms_text_ckeditor to yourINSTALLED_APPS
• runpython manage.py migrate djangocms_text_ckeditor

• removecms.plugins.text fromINSTALLED_APPS
• adddjangocms_text_ckeditor toINSTALLED_APPS
• runpython manage.py migrate djangocms_text_ckeditor 0001 --fake

Inline editing allows editors to directly click on a text plugin and changethe contents in django CMS' edit mode. The CKEditor appears directly aroundthe text field and can be used normally. Changes are saved as soon as thetext field leaves focus.

Inline editing requires to encapsulate the HTML text in a<div> inedit mode. This might cause some side effects with a site's CSS, e.g. directchild rules.

To activate inline editing add the following line in your project'ssettings.py:

TEXT_INLINE_EDITING = True

This will add a toggle button to the toolbar to allow to switch inline editingon and off for the current session.

When inline editing is active the editor will save the plugin's content each time it losesfocus. If only text has changed the user can immediately continue to edit. Ifa text-enabled plugin was changed, added, or removed he page will refresh toupdate the page tree and get the correctly rendered version of the changedplugin.

If you use Django-CMS >= 3.0, you can useTextPlugin in "default_plugins"(see docs about theCMS_PLACEHOLDER_CONF setting in Django CMS 3.0).TextPlugin requires just one value:body where you write your defaultHTML content. If you want to add some "default children" to yourautomagically added plugin (i.e. aLinkPlugin), you have to put childrenreferences in the body. References are"%(_tag_child_<order>)s" with theinserted 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'                        },                    },                ]            },        ]    }}

You can override the settingCKEDITOR_SETTINGS in your settings.py:

CKEDITOR_SETTINGS = {    'language': '{{ language }}',    'toolbar': 'CMS',    'skin': 'moono-lisa',}

This is the default dict that holds allCKEditor settings.

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',}

If you useHTMLField fromdjangocms_text_ckeditor.fields in your ownmodels, 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 differentconfiguration parameter in your settings:

models.pyclass Model1(models.Model):    text = HTMLField(configuration='CKEDITOR_SETTINGS_MODEL1')class Model2(models.Model):    text = HTMLField(configuration='CKEDITOR_SETTINGS_MODEL2')settings.pyCKEDITOR_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'],    ]}

1. Add configuration='MYSETTING' to the HTMLField usage(s) you want tocustomize;
2. Define a setting parameter named as the string used in the configurationargument of the HTMLField instance with the desired configuration;

Values not specified in your custom configuration will be taken from the globalCKEDITOR_SETTINGS.

For an overview of all the available settings have a look here:

http://docs.ckeditor.com/#!/api/CKEDITOR.config

The child plugins of TextPlugin can be rendered directly inside CKEditor iftext_editor_preview isn'tFalse. However there are few important pointsto note:

• by default CKEditor doesn't load CSS of your project inside the editing areaand has specific settings regarding empty tags, which could mean that thingswill 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 theproperty "allowedContent"to containcms-plugin[*] as this custom tag iswhat allows the inline previews to be rendered

• Important note: please avoid html tags in__str__ representation of textenabled plugins - this messes up inline preview.

• If you're adding a Text Plugin as a child inside another plugin and want to style itconditionally based on the parent - you can addCMSPluginBase.child_ckeditor_body_css_classattribute to the parent class.

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 functioncreate_picture_plugin for details.

To completely disable the feature, setTEXT_SAVE_IMAGE_FUNCTION = None.

If you want to use the widget on your own model fields, you can! Just import the providedHTMLField like so:

from djangocms_text_ckeditor.fields import HTMLField

And use it in your models, just like aTextField:

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 embeddedwithinPlaceholder fields.

If you need to allow additional plugins to be embedded in a HTML field, convert theHTMLField to aPlaceholderfieldand 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

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. Insettings.py add'softhyphen'to the list ofINSTALLED_APPS.django-softhyphen also installs hyphening dictionaries for 25natural languages.

In case you already installeddjango-softhyphen but do not want to soft hyphenate, setTEXT_AUTO_HYPHENATE toFalse.

You can use this plugin as base to create your own CKEditor-based plugins.

You need to create your own plugin model extendingAbstractText:

from djangocms_text_ckeditor.models import AbstractTextclass MyTextModel(AbstractText):    title = models.CharField(max_length=100)

and a plugin class extendingTextPlugin class:

from djangocms_text_ckeditor.cms_plugins import TextPluginfrom .models import MyTextModelclass MyTextPlugin(TextPlugin):    name = _(u"My text plugin")    model = MyTextModelplugin_pool.register_plugin(MyTextPlugin)

Note that if you override the render method that is inherited from the baseTextPlugin class, any child textplugins will not render correctly. You must call the superrender method in order forplugin_tags_to_user_html()to render out all child plugins located in thebody field. For example:

from djangocms_text_ckeditor.cms_plugins import TextPluginfrom .models import MyTextModelclass 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 furthercustomize your plugin as other plugins.

If you have created a plugin that you want to use within Text plugins you can make them appear in the dropdown bymaking them text_enabled. This means that you assign the propertytext_enabled of a plugin toTrue,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 theCMS 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, readdjango-cms doc on how to do this.

djangocms-text-ckeditor useshtml5lib to sanitize HTML to avoidsecurity issues and to check for correct HTML code.Sanitisation may strip tags usesful for some use cases such asiframe;you may customize the tags and attributes allowed by overriding theTEXT_ADDITIONAL_TAGS andTEXT_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 defineyour logic into parse() method. For example, if you want to skip your donut attribute duringsanitisation, you can create a class like this:

from djangocms_text_ckeditor.sanitizer import AllowTokenParserclass DonutAttributeParser(AllowTokenParser):    def parse(self, attribute, val):        return attribute.startswith('donut-')

And add your class toALLOW_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 thefollowing parameters toCKEDITOR_SETTINGS:

...'basicEntities': False,'entities': False,...

To completely disable the feature, setTEXT_HTML_SANITIZE = False.

See thehtml5lib documentation for further information.

djangocms-text-ckeditor works well withaldryn-searchto make text content using Haystack.

The repo uses pre-commit git hooks to run tools which ensure code quality.

To utilise this, runpip install pre-commit and thenpre-commit install.

djangocms-text-ckeditor distributes a javascript bundle required for theplugin to work, which contains CKEditor itself and all the necessary plugins forfunctioning within CMS. To build the bundle you need to have to installdependencies withnpm install and then to rungulp bundle.

This command also updates the file name loaded based on the file contents.

Make sure to use the url inbuild config.

You can run tests by executing:

virtualenv envsource env/bin/activatepip install -r tests/requirements.txtpython setup.py test