Wonderful rich text for Django
Project description
Django Prose
Django Prose provides your Django applications with wonderful rich-text editing.
Requirements
- Python 3.6.2 or later
- Django 2.2 or later
- Bleach 4.0 or later
Getting started
To get started with Django Prose, first make sure to install it. We use and suggest using Poetry, although Pipenv and pip will work seamlessly as well
poetry add django-prose
Then, add prose
in Django's installed apps (example: prose_example/prose_example/settings.py
):
INSTALLED_APPS = [
# Django stock apps (e.g. 'django.contrib.admin')
'prose',
# your application's apps
]
Last, run migrations so you can use Django Prose's Document model:
python manage.py migrate prose
Now, you are ready to go 🚀.
Usage
There are different ways to use Django prose according to your needs. We will examine all of them here.
Small rich-text information
You might want to add rich-text information in a model that is just a few characters (e.g. 140), like an excerpt from an article. In that case we suggest using the RichTextField
. Example:
from django.db import models
from prose.fields import RichTextField
class Article(models.Model):
excerpt = RichTextField()
Then you can display the article excerpt in your HTML templates by marking it as safe
<div class="article-excerpt">{{ article.excerpt | safe}}</div>
Large rich-text information
In case you want to store large rich-text information, like the content of an article, which can span to quite a few thousand characters, we suggest you use the AbstractDocument
model. This will save large rich-text information in a separate database table, which is better for performance. Example:
from django.db import models
from prose.fields import RichTextField
from prose.models import AbstractDocument
class ArticleContent(AbstractDocument):
pass
class Article(models.Model):
excerpt = RichTextField()
body = models.OneToOneField(ArticleContent, on_delete=models.CASCADE)
Similarly here you can display the article's body by marking it as safe
<div class="article-body">{{ article.body.content | safe}}</div>
Attachments
Django Prose can also handle uploading attachments with drag and drop. To set this up, first you need to:
- Set up the
MEDIA_ROOT
of your Django project (example inprose_example/prose_example/settings.py
)) - Include the Django Prose URLs (example in
prose_example/prose_example/urls.py
) - (Optional) Set up a different Django storage to store your files (e.g. S3)
🔒 A note on security
As you can see in the examples above, what Django Prose does is provide you with a user friendly editor (Trix) for your rich text content and then store it as HTML in your database. Since you will mark this HTML as safe in order to use it in your templates, it needs to be sanitised, before it gets stored in the database.
For this reason Django Prose is using Bleach to only allow the following tags and attributes:
- Allowed tags:
p
,ul
,ol
,li
,strong
,em
,div
,span
,a
,blockquote
,pre
,figure
,figcaption
,br
,code
,h1
,h2
,h3
,h4
,h5
,h6
,picture
,source
,img
- Allowed attributes:
alt
,class
,id
,src
,srcset
,href
,media
Screenshots
Django Prose Documents in Django Admin
Development for Django Prose
If you plan to contribute code to Django Prose, this section is for you. All development tooling for Django Prose has been set up with Docker. To get started run these commands in the provided order:
docker compose run --rm migrate
docker compose run --rm createsuperuser
docker compose up
🦄 Built with ❤️ by LOGIC. 🦄
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
Hashes for django_prose-1.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1e8107bb1fdb1d6ea03129fa36c76cae742654606ca381f4d392ee7285afaf1a |
|
MD5 | ebcde97ce1f6721b3902a8e42c507ef8 |
|
BLAKE2b-256 | 26862bf4697cd6f889ca00a2914b6a939c5bfee9a7e40416013279ee65ce5925 |