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. * 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_)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':'

Great websites : %(_tag_child_1)s and %(_tag_child_2)s

' }, '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) 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) You can further customize your plugin as other plugins: 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/