Text Plugin for django CMS with CKEditor support
Project description
Text Plugin for django-cms with CK-Editor
Installation
This plugin requires django CMS 3.0 or higher to be properly installed.
In your projects virtualenv, run pip install djangocms-text-ckeditor.
If upgrading from previous djangocms_text_ckeditor, be aware that the names of the migration modules have changed:
Django 1.6: djangocms_text_ckeditor.migrations to djangocms_text_ckeditor.south_migrations
Django 1.7: djangocms_text_ckeditor.migrations_django to djangocms_text_ckeditor.migrations
If using Django 1.6 add 'djangocms_text_ckeditor': 'djangocms_text_ckeditor.south_migrations', to SOUTH_MIGRATION_MODULES (or define SOUTH_MIGRATION_MODULES if it does not exists);
If using Django 1.7 and you were using version prior to 2.5, remove djangocms_text_ckeditor from MIGRATION_MODULES;
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:
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
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.
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 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(MyTextPlugin, self).render(context, instance, placeholder) plugin_pool.register_plugin(MyTextPlugin)
You can further customize your plugin as other plugins.
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.
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')
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.
About CKEditor
The current integrated Version of CKeditor is 4.4. For a full documentation visit: http://ckeditor.com/
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file djangocms-text-ckeditor-2.5.0b1.tar.gz
.
File metadata
- Download URL: djangocms-text-ckeditor-2.5.0b1.tar.gz
- Upload date:
- Size: 1.2 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 67994339edf19af38c984ca9adda5f1cf42b9740bb076baac6fbbce451930645 |
|
MD5 | 4bda8ea1b7ad6f509f50b87523d00e7a |
|
BLAKE2b-256 | 70cc45596488f980e81d8264f8ee9d418a664455a97d60a21a869f722b02c794 |
File details
Details for the file djangocms_text_ckeditor-2.5.0b1-py2.py3-none-any.whl
.
File metadata
- Download URL: djangocms_text_ckeditor-2.5.0b1-py2.py3-none-any.whl
- Upload date:
- Size: 1.6 MB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 13c5dab71d6c476857f6cf17c2dc582cf290cd511db5e01086b32e04bb30b737 |
|
MD5 | 1279f3c11d04658756190d35e6c5b7d4 |
|
BLAKE2b-256 | 51fb442afe9e99f4e4d5855c508453dce738eb190e5d389327d35c8a72cf8e01 |