django-richtextfield 1.0.1

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

class CommentForm(forms.ModelForm):
    content = forms.CharField(widget=RichTextWidget())
    content.widget.field_settings = {'your': 'custom', 'settings': True}

class Post(models.Model):
    content = RichTextField(field_settings={'your': 'custom', 'settings': True})

class CommentForm(forms.ModelForm):
    content = forms.CharField(widget=RichTextWidget(field_settings='basic'))

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

if (!CKEDITOR.instances[id]) {
    CKEDITOR.replace(id, 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