Skip to main content

Text Plugin for django CMS with CKEditor support

Project description

Text Plugin for django-cms with CK-Editor

Installation

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

  • In your projects virtualenv, run pip install djangocms-text-ckeditor.

  • Add 'djangocms_text_ckeditor' to your INSTALLED_APPS setting BEFORE the cms entry.

  • Run 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

Usage

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 chidren. 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'
                        },
                    },
                ]
            },
        ]
    }
}

CKEDITOR_SETTINGS

You can override the setting CKEDITOR_SETTINGS in your settings.py:

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

This is the default dict that holds all CKEditor settings. If you want to use the CKEditor in your own models, then use the HTMLField from djangocms_text_ckeditor.fields and replace 'toolbar': 'CMS' with 'toolbar': 'HTMLField' in the above settings, in order to add an

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

http://docs.cksource.com/ckeditor_api/symbols/CKEDITOR.config.html

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 overwirite 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.

Translations

If you want to help translate the plugin please do it on transifex:

https://www.transifex.com/projects/p/django-cms/resource/djangocms-text-ckeditor/

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)

Extending the plugin

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

You need to create your own plugin model extending AbstractClass:

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)

You can further customize your plugin as other plugins: http://django-cms.readthedocs.org/en/latest/extending_cms/custom_plugins.html

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_TAGS = ('scrolling', 'allowfullscreen', 'frameborder')

See the html5lib documentation for further information.

About CKEditor

The current integrated Version of CKeditor is 4.3. For a full documentation visit: http://ckeditor.com/

Release history Release notifications | RSS feed

This version

2.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

djangocms-text-ckeditor-2.1.tar.gz (1.2 MB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page