You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Django Prose provides your Django applications with wonderful rich-text editing.
5
+
Django Prose provides your Django applications with wonderful rich-text editing capabilities.
6
6
7
7
## Requirements
8
8
9
-
- Python 3.6.2 or later
10
-
- Django 2.2 or later
9
+
- Python 3.8 or later
10
+
- Django 3.2 or later
11
11
- Bleach 4.0 or later
12
12
13
13
## Getting started
@@ -18,7 +18,7 @@ To get started with Django Prose, first make sure to install it. We use and sugg
18
18
poetry add django-prose
19
19
```
20
20
21
-
Then, add `prose` in Django's installed apps (example: [`prose_example/prose_example/settings.py`](https://github.com/withlogicco/django-prose/blob/55fb9319e55d873afe43968817a2f5ea3f055d11/prose_example/prose_example/settings.py#L46)):
21
+
Then, add `prose` in Django's installed apps (example: [`example/example/settings.py`](https://github.com/withlogicco/django-prose/blob/9e24cc794eae6db48818dd15a483d106d6a99da0/example/example/settings.py#L46)):
22
22
23
23
```python
24
24
INSTALLED_APPS= [
@@ -42,9 +42,17 @@ Now, you are ready to go 🚀.
42
42
43
43
There are different ways to use Django prose according to your needs. We will examine all of them here.
44
44
45
-
### Small rich-text information
45
+
### Rendering rich-text in templates
46
46
47
-
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:
47
+
Rich text content essentially is HTML. For this reason it needs to be manually marked as [`safe`](https://docs.djangoproject.com/en/4.2/ref/templates/builtins/#safe), when rendered in Django templates. Example:
48
+
49
+
```django
50
+
{{ document.content | safe}}
51
+
```
52
+
53
+
### Small rich-text content
54
+
55
+
You might want to add rich-text content 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:
48
56
49
57
```py
50
58
from django.db import models
@@ -54,15 +62,15 @@ class Article(models.Model):
54
62
excerpt = RichTextField()
55
63
```
56
64
57
-
Then you can display the article excerpt in your HTML templates by marking it as [`safe`](https://docs.djangoproject.com/en/4.0/ref/templates/builtins/#safe)
65
+
As mentioned above, you need to mark the article excerpt as `safe`, in order to render it:
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:
73
+
In case you want to store large rich-text content, like the body 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 content in a separate database table, which is better for performance. Example:
66
74
67
75
```py
68
76
from django.db import models
@@ -77,7 +85,7 @@ class Article(models.Model):
77
85
body = models.OneToOneField(ArticleContent, on_delete=models.CASCADE)
78
86
```
79
87
80
-
Similarly here you can display the article's body by marking it as `safe`
88
+
Similarly here as well, you need to mark the article's body as `safe`, in order to render it:
@@ -104,10 +112,14 @@ The same is true also, if you are rendering the forms field manually.
104
112
105
113
Django Prose can also handle uploading attachments with drag and drop. To set this up, first you need to:
106
114
107
-
-[x] Set up the `MEDIA_ROOT` of your Django project (example in [`prose_example/prose_example/settings.py`](https://github.com/withlogicco/django-prose/blob/55fb9319e55d873afe43968817a2f5ea3f055d11/prose_example/prose_example/settings.py#L132)))
108
-
-[x] Include the Django Prose URLs (example in [`prose_example/prose_example/urls.py`](https://github.com/withlogicco/django-prose/blob/9073d713f8d3febe5c50705976dbb31063270886/prose_example/prose_example/urls.py#L9-L10))
115
+
-[x] Set up the `MEDIA_ROOT`and `MEDIA_URL`of your Django project (example in [`example/example/settings.py`](https://github.com/withlogicco/django-prose/blob/9e24cc794eae6db48818dd15a483d106d6a99da0/example/example/settings.py#L130-L131)))
116
+
-[x] Include the Django Prose URLs (example in [`example/example/urls.py`](https://github.com/withlogicco/django-prose/blob/9e24cc794eae6db48818dd15a483d106d6a99da0/example/example/urls.py#L13-L14))
109
117
-[x] (Optional) Set up a different Django storage to store your files (e.g. S3)
110
118
119
+
### Full example
120
+
121
+
You can find a full example of a blog, built with Django Prose in the [`example`](./example/) directory.
122
+
111
123
## 🔒 A note on security
112
124
113
125
As you can see in the examples above, what Django Prose does is provide you with a user friendly editor ([Trix](https://trix-editor.org/)) 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.
@@ -121,21 +133,30 @@ For this reason Django Prose is using [Bleach](https://bleach.readthedocs.io/en/
121
133
122
134
### Django Prose Documents in Django Admin
123
135
124
-
125
136
126
137
138
+
## Real world use cases
139
+
-**Remote Work Café**: Used to edit location pagess, like [Amsterdam | Remote Work Café](https://remotework.cafe/locations/amsterdam/)
140
+
- In production by multiple clients of [LOGIC](https://withlogic.co), from small companies to the public sector.
141
+
142
+
If you are using Django Prose in your application too, feek free to open a [Pull Request](https://github.com/withlogicco/django-prose/pulls) to include it here. We would love to have it.
143
+
127
144
## Development for Django Prose
128
145
129
-
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:
146
+
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 and Development Containers.
147
+
148
+
To get started run these commands in the provided order:
130
149
131
150
```console
132
151
docker compose run --rm migrate
133
152
docker compose run --rm createsuperuser
134
153
docker compose up
135
154
```
136
155
156
+
If you are using Visual Studio code, just open this repository in a container using the [`Dev Containers: Open Folder in Container`](https://code.visualstudio.com/docs/devcontainers/containers#_quick-start-open-an-existing-folder-in-a-container).
157
+
137
158
---
138
159
139
160
<palign="center">
140
-
<i>🦄 Built with ❤️ by <ahref="https://withlogic.co/">LOGIC</a>. 🦄</i>
161
+
<i>🦄 Built with <ahref="https://withlogic.co/">LOGIC</a>. 🦄</i>
0 commit comments