A Django model field and widget that renders a customizable WYSIWYG/rich text editor
Project description
A Django model field and widget that renders a customizable rich text/WYSIWYG widget. Tested with TinyMCE and CKEditor. Designed to be easily extended to use other editors.
Quickstart
Install django-richtextfield and add it to your Django project’s INSTALLED_APPS, django.contrib.admin must also be in INSTALLED_APPS:
INSTALLED_APPS = [ 'django.contrib.admin', ... 'djrichtextfield' ]
Add the urls to the project’s urlpatterns:
url(r'^djrichtextfield/', include('djrichtextfield.urls'))
Configure django-richtextfield in settings.py:
DJRICHTEXTFIELD_CONFIG = { 'js': ['//tinymce.cachefly.net/4.1/tinymce.min.js'], 'init_template': 'djrichtextfield/init/tinymce.js', 'settings': { 'menubar': False, 'plugins': 'link image', 'toolbar': 'bold italic | link image | removeformat', 'width': 700 } }
Now you’re ready to use the field in your models:
from djrichtextfield.models import RichTextField class Post(models.Model): content = RichTextField()
or forms:
from djrichtextfield.widgets import RichTextWidget class CommentForm(forms.ModelForm): content = forms.CharField(widget=RichTextWidget())
Configuration
Define the DJRICHTEXTFIELD_CONFIG dictionary in your project settings. This dictionary can have the following keys:
- 'js'
A list of required javascript files. These can be URLs to a CDN or paths relative to your STATIC_URL e.g.:
'js': ['//cdn.ckeditor.com/4.4.4/standard/ckeditor.js']
or:
'js': ['path/to/editor.js', 'path/to/plugin.js']
- 'init_template'
Path to the init template for your editor. Currently django-richtextfield ships with two templates, either:
'init_template': 'djrichtextfield/init/tinymce.js'
or:
'init_template': 'djrichtextfield/init/ckeditor.js'
- 'settings'
A Python dictionary with the default configuration data for your editor e.g.:
{ # TinyMCE 'menubar': False, 'plugins': 'link image', 'toolbar': 'bold italic | link image | removeformat', 'width': 700 }
or:
{ # CKEditor 'toolbar': [ {'items': ['Format', '-', 'Bold', 'Italic', '-', 'RemoveFormat']}, {'items': ['Link', 'Unlink', 'Image', 'Table']}, {'items': ['Source']} ], 'format_tags': 'p;h1;h2;h3', 'width': 700 }
- 'profiles'
This is an optional configuration key. Profiles are “named” custom settings used to configure specific type of fields. You can configure profiles like this:
'profiles': { 'basic': { 'toolbar': 'bold italic | removeformat' }, 'advanced': { 'plugins': 'link image table code', 'toolbar': 'formatselect | bold italic | removeformat |' ' link unlink image table | code' } }
Field & Widget settings
You can override the default settings per field:
class CommentForm(forms.ModelForm): content = forms.CharField(widget=RichTextWidget()) content.widget.field_settings = {'your': 'custom', 'settings': True}
or:
class Post(models.Model): content = RichTextField(field_settings={'your': 'custom', 'settings': True})
It’s recommended to use profiles, they make it easier to switch configs or even editors on a later date. You use a profile like this:
class CommentForm(forms.ModelForm): content = forms.CharField(widget=RichTextWidget(field_settings='basic'))
or:
class Post(models.Model): content = RichTextField(field_settings='advanced')
Custom init / Using another editor
This is uncharted territory, but in theory it’s fairly easy. Just configure DJRICHTEXTFIELD_CONFIG to load the right Javascript files and create an init template.
DJRICHTEXTFIELD_CONFIG = { 'js': ['path/to/editor.js'], 'init_template': 'path/to/init/template.js', 'settings': {'some': 'configuration'} }
Init template
The init template is a Django template (so it should be in the template and not in the static directory). It contains a tiny bit of Javascript that’s called to initialize each editor. For example, the init template for CKEditor looks like this:
if (!CKEDITOR.instances[id]) { CKEDITOR.replace(id, settings); }
The init template has the following Javascript variables available from the outer scope:
- $e
jQuery wrapped textarea to be replaced
- id
The id attribute of the textarea
- default_settings
DJRICHTEXTFIELD_CONFIG['settings'] as a JS object
- custom_settings
The field_settings as a JS object
- settings
Merge of default_settings and custom_settings
Handling uploads & other advanced features
django-richtextfield built to be editor agnostic. This means that it’s up to you to handle file uploads, show content previews and support other “advanced” features.
History
1.2.1 (2018-01-18)
Add [‘admin/js/vendor/jquery/jquery.min.js’, ‘admin/js/jquery.init.js’] to RichTextWidget.media.js. This makes the widget usable outside of the admin (but still requires django.contrib.admin to be in INSTALLED_APPS) and prevents javascript errors inside the admin in certain edge cases.
1.2 (2017-12-04)
Remove support for Django < 1.11
Add support for Django 2.0
1.1 (2016-01-14)
Remove support for Django < 1.8
Tested with Django 1.8 & Django 1.9
1.0.1 (2014-11-13)
Fix unicode error
1.0 (2014-09-30)
First release
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
Hashes for django-richtextfield-1.2.1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 11d42b9dfd029feb2174ac4bc385cfd1f8ac556f2118c1026534167030447bd9 |
|
MD5 | 163cd42c936a72ed83d534e5509103f2 |
|
BLAKE2b-256 | f32e35aacf187dbae1c7241d7c367b4a2d366bc8da5874e223960306efd4b04e |