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:
INSTALLED_APPS += '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.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
Built Distributions
Hashes for django_richtextfield-1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fe0f9ab86d29c0ea84f6592184b30dd588151310509216d4afee91d78810da48 |
|
MD5 | 2d98b9f330aefd61630a991785db2a1b |
|
BLAKE2b-256 | 0141ef91965e501b07abb377f9228dfb5e4f5218815c347ee3ecb6044c4f152b |
Hashes for django_richtextfield-1.1-py2-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5536864526b8a6e44ac9c8b9a2a65b05d0410110661376ea3caa71385349454f |
|
MD5 | 4d9eb19dc4bb5def23c03fe12e24287a |
|
BLAKE2b-256 | cdd317e76d8d9a260e404268d956a66ecbfcbd4b28d0e6e85a6d89bc6890b6e9 |