django-prose-editor 0.6.2

Installation

Install the package:

venv/bin/pip install django-prose-editor

To include nh3 as optional dependency for sanitized HTML, install the extra “sanitize”:

venv/bin/pip install django-prose-editor[sanitize]

Add django_prose_editor to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django_prose_editor",
]

Replace models.TextField with ProseEditorField where appropriate:

from django_prose_editor.fields import ProseEditorField

class Project(models.Model):
    description = ProseEditorField()

Note! No migrations will be generated when switching from and to models.TextField. That’s by design. Those migrations are mostly annoying.

Security

ProseMirror does a really good job of only allowing content which confirms to a particular scheme. Of course users can submit what they want, they are not constrainted by the HTML widgets you’re using. You should still always sanitize the HTML submitted on the server side. A good way to do this is by using the sanitize argument to the ProseEditorField. You can use the following snippet to always pass HTML through nh3:

from django_prose_editor.sanitized import SanitizedProseEditorField

description = SanitizedProseEditorField()

Install django-prose-editor with the extra “sanitize” to use SanitizedProseEditorField.

Convenience

Sometimes it may be useful to show an excerpt of the HTML field; the ProseEditorField automatically adds a get_*_excerpt method to models which returns the truncated and stripped beginning of your HTML field’s content. The name would be Project.get_description_excerpt in the example above.

Customization

It’s possible to slightly customize the field or widget by passing an optional config dictionary. The default configuration is:

config = {
    "types": None,        # Allow all nodes and marks
    "history": True,      # Enable undo and redo
    "html": True,         # Add a button which allows editing the raw HTML
    "typographic": True,  # Highlight typographic characters
}

If you only want to support paragraphs, strong, emphasis, sub- and superset and no history or HTML editing you could add the following field:

text = SanitizedProseEditorField(
    config={"types": ["strong", "em", "sub", "sup"]},
)

Paragraphs cannot be removed at the moment. Note that the backend doesn’t sanitize the content to ensure that the HTML doesn’t contain only the provided tags, that’s out of scope for now.

doc, paragraph and text are always in the allowlist.

The supported node types are heading, blockquote, horizontal_rule and hard_break.

The supported mark types are link, strong, em, underline, strikethrough, sub and sup

Usage outside the Django admin

The prose editor can easily be used outside the Django admin. The form field respectively the widget includes the necessary CSS and JavaScript:

from django_prose_editor.fields import ProseEditorFormField

class Form(forms.Form):
    text = ProseEditorFormField()

Or maybe you want to use django_prose_editor.widgets.ProseEditorWidget, but why make it more complicated than necessary.

If you’re rendering the form in a template you have to include the form media:

<form method="post">
  {{ form.errors }} {# Always makes sense #}
  {{ form.media }}  {# This is the important line! #}
  {{ form.as_div }}
  <button type="submit">send</button>
</form>

Note that the form media isn’t django-prose-editor specific, that’s a Django feature.