djangocms-text-ckeditor 2.3.0

Text Plugin for django CMS with CKEditor support

djangocms-text-ckeditor
=======================

Text Plugin for django-cms with CK-Editor

.. WARNING::
``cms.plugins.text`` and ``djangocms-text-ckeditor`` can't be used at the same time.

.. WARNING::
For django CMS 2.3 and 2.4 use ``djangocms-text-ckeditor`` < 2 (e.g.: version 1.0.10).

``djangocms-text-ckeditor`` >= 2 is compatible with django CMS 3 only.


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.
* If using Django 1.7 add ``'djangocms_text_ckeditor': 'djangocms_text_ckeditor.migrations_django',``
to ``MIGRATION_MODULES`` (or define ``MIGRATION_MODULES`` if it does not exists);
when django CMS 3.1 will be released, migrations for Django 1.7 will be moved
to the standard location and the south-style ones to ``south_migrations``.
* 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.

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

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


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 desidered 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


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)

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://django-cms.readthedocs.org/en/latest/extending_cms/placeholders.html


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 ``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)

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(MyTextPlugin, self).render(context, instance, placeholder)

plugin_pool.register_plugin(MyTextPlugin)

You can further `customize your plugin`_ as other plugins.

.. _customize your plugin: http://django-cms.readthedocs.org/en/latest/extending_cms/custom_plugins.html

Adding plugins to the "CMS Plugins" dropdown
--------------------------------------------

If you have another plugin that you want to use inside texts you can make them appear in the dropdown by making them text_enabled.
Check in `django-cms doc`_ how to do this.

.. _django-cms doc: http://django-cms.readthedocs.org/en/develop/extending_cms/custom_plugins.html#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_TAGS = ('scrolling', 'allowfullscreen', 'frameborder')

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

About CKEditor
--------------

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