Skip to content

Commit 2e71572

Browse files
ArchmongerArchmonger
committed
docs cleanup
1 parent 2cc8073 commit 2e71572

4 files changed

Lines changed: 712 additions & 622 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ src/reactpy_django/static/reactpy_django/index.js
33
src/reactpy_django/static/reactpy_django/index.js.map
44
src/reactpy_django/static/reactpy_django/pyscript
55
src/reactpy_django/static/reactpy_django/morphdom
6+
tmp/*
67

78
# Django #
89
logs

‎docs/mkdocs.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,9 @@
22
nav:
33
- Home: index.md
44
- Get Started:
5-
- Add ReactPy to a Django Project: learn/add-reactpy-to-a-django-project.md
6-
- Add ReactPy to a Django Project (with Jinja): learn/add-reactpy-to-a-django-project-with-jinja.md
5+
- Add ReactPy to your...:
6+
- Django Project: learn/add-reactpy-to-a-django-project.md
7+
- Django Project (with Jinja): learn/add-reactpy-to-a-django-project-with-jinja.md
78
- Your First Component: learn/your-first-component.md
89
- Reference:
910
- Components: reference/components.md

‎docs/src/learn/add-reactpy-to-a-django-project-with-jinja.md‎

Lines changed: 137 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -12,19 +12,50 @@ If you use **Jinja2 templates** in your Django project and want to add ReactPy i
1212

1313
---
1414

15-
## Step 1: Install `jinja2`
15+
## Step 1: Install from PyPI
1616

17-
Jinja2 is a Python dependency you must install in your environment to use this feature.
17+
Run the following command to install [`reactpy-django`](https://pypi.org/project/reactpy-django/) and [`jinja2`](https://pypi.org/project/Jinja2/) in your Python environment.
1818

1919
```bash linenums="0"
20-
pip install jinja2
20+
pip install reactpy-django jinja2
2121
```
2222

23-
---
23+
## Step 2: Configure `settings.py`
24+
25+
Add `#!python "reactpy_django"` to [`INSTALLED_APPS`](https://docs.djangoproject.com/en/stable/ref/settings/#std:setting-INSTALLED_APPS) in your [`settings.py`](https://docs.djangoproject.com/en/stable/topics/settings/) file.
26+
27+
=== "settings.py"
28+
29+
```python
30+
{% include "../../examples/python/configure_installed_apps.py" %}
31+
```
32+
33+
??? warning "Enable ASGI and Django Channels (Required)"
34+
35+
ReactPy-Django requires Django ASGI and [Django Channels](https://github.com/django/channels) WebSockets.
36+
37+
If you have not enabled ASGI on your **Django project** yet, here is a summary of the [`django`](https://docs.djangoproject.com/en/stable/howto/deployment/asgi/) and [`channels`](https://channels.readthedocs.io/en/stable/installation.html) installation docs:
2438

25-
## Step 2: Configure the Jinja2 template engine
39+
1. Install `channels[daphne]`
40+
2. Add `#!python "daphne"` to `#!python INSTALLED_APPS`.
2641

27-
Add a Jinja2 backend entry to your `TEMPLATES` list in [`settings.py`](https://docs.djangoproject.com/en/stable/topics/settings/).
42+
```python linenums="0"
43+
{% include "../../examples/python/configure_channels_installed_app.py" %}
44+
```
45+
46+
3. Set your `#!python ASGI_APPLICATION` variable.
47+
48+
```python linenums="0"
49+
{% include "../../examples/python/configure_channels_asgi_app.py" %}
50+
```
51+
52+
??? info "Configure ReactPy settings (Optional)"
53+
54+
ReactPy's has additional configuration available to fit a variety of use cases.
55+
56+
See the [ReactPy settings](../reference/settings.md) documentation to learn more.
57+
58+
Also add a Jinja2 backend entry to your `TEMPLATES` list:
2859

2960
The backend must include:
3061

@@ -34,23 +65,13 @@ The backend must include:
3465
=== "settings.py"
3566

3667
```python
68+
import os
69+
3770
TEMPLATES = [
38-
{
39-
"BACKEND": "django.template.backends.django.DjangoTemplates",
40-
"DIRS": [],
41-
"APP_DIRS": True,
42-
"OPTIONS": {
43-
"context_processors": [
44-
"django.template.context_processors.debug",
45-
"django.template.context_processors.request",
46-
"django.contrib.auth.context_processors.auth",
47-
"django.contrib.messages.context_processors.messages",
48-
],
49-
},
50-
},
71+
... ,
5172
{
5273
"BACKEND": "django.template.backends.jinja2.Jinja2",
53-
"DIRS": [],
74+
"DIRS": [os.path.join(BASE_DIR, "templates")],
5475
"OPTIONS": {
5576
"environment": "myproject.jinja_env.environment",
5677
"context_processors": [
@@ -64,9 +85,43 @@ The backend must include:
6485
]
6586
```
6687

67-
---
88+
## Step 3: Configure `urls.py`
89+
90+
Add ReactPy HTTP paths to your `#!python urlpatterns` in your [`urls.py`](https://docs.djangoproject.com/en/stable/topics/http/urls/) file.
91+
92+
=== "urls.py"
93+
94+
```python
95+
{% include "../../examples/python/configure_urls.py" %}
96+
```
97+
98+
## Step 4: Configure `asgi.py`
99+
100+
Register ReactPy's WebSocket using `#!python REACTPY_WEBSOCKET_ROUTE` in your [`asgi.py`](https://docs.djangoproject.com/en/stable/howto/deployment/asgi/) file.
101+
102+
=== "asgi.py"
103+
104+
```python
105+
{% include "../../examples/python/configure_asgi.py" %}
106+
```
68107

69-
## Step 3: Create a Jinja2 environment module
108+
??? info "Add `#!python AuthMiddlewareStack` (Optional)"
109+
110+
There are many situations where you need to access the Django `#!python User` or `#!python Session` objects within ReactPy components. For example, if you want to:
111+
112+
1. Access the `#!python User` that is currently logged in
113+
3. Access Django's `#!python Session` object
114+
2. Login or logout the current `#!python User`
115+
116+
In these situations will need to ensure you are using `#!python AuthMiddlewareStack`.
117+
118+
{% include "../../includes/auth-middleware-stack.md" %}
119+
120+
??? question "Where is my `asgi.py`?"
121+
122+
If you do not have an `asgi.py`, follow the [`channels` installation guide](https://channels.readthedocs.io/en/stable/installation.html).
123+
124+
## Step 5: Register the Jinja2 Extension
70125

71126
Create a `jinja_env.py` module that registers the `ReactPyExtension`:
72127

@@ -83,54 +138,79 @@ Create a `jinja_env.py` module that registers the `ReactPyExtension`:
83138
return env
84139
```
85140

86-
---
141+
## Step 6: Run database migrations
87142

88-
## Step 4: Use ReactPy components in Jinja2 templates
143+
Run Django's [`migrate` command](https://docs.djangoproject.com/en/stable/topics/migrations/) to initialize ReactPy-Django's database table.
89144

90-
With the extension registered, you can call ReactPy functions directly inside any Jinja2 template:
145+
```bash linenums="0"
146+
python manage.py migrate
147+
```
91148

92-
=== "templates/example.html.jinja"
149+
## Step 7: Check your configuration
93150

94-
```html
95-
<!DOCTYPE html>
96-
<html>
97-
<head>
98-
<title>ReactPy + Jinja2</title>
99-
</head>
100-
<body>
101-
<h1>Server-side component</h1>
102-
{{ component("my_app.components.hello_world", recipient="World") }}
151+
Run Django's [`check` command](https://docs.djangoproject.com/en/stable/ref/django-admin/#check) to verify everything is set up correctly.
103152

104-
<h1>Client-side PyScript component</h1>
105-
{{ pyscript_component("my_app/components/my_app.py") }}
153+
```bash linenums="0"
154+
python manage.py check
155+
```
106156

107-
{{ pyscript_setup() }}
108-
</body>
109-
</html>
110-
```
157+
## Step 8: Create your first component
111158

112-
!!! info "Template tag vs Jinja2 function syntax"
159+
The [next page](./your-first-component.md) will show you how to create your first ReactPy component.
113160

114-
Unlike Django templates which require `{% load reactpy %}` and `{% component "..." %}`, Jinja2 allows you to call component functions directly using the `{{ component(...) }}` syntax. The registered functions are:
161+
Prefer a quick summary? Read the **At a Glance** section below.
115162

116-
| Function | Description |
117-
|---|---|---|
118-
| `{{ component(dotted_path, *args, **kwargs) }}` | Render a server-side ReactPy component. Equivalent to `{% component %}`. |
119-
| `{{ pyscript_component(*file_paths, initial, root) }}` | Render a client-side PyScript component. Equivalent to `{% pyscript_component %}`. |
120-
| `{{ pyscript_setup(*extra_py, extra_js, config) }}` | Render PyScript setup configuration. Equivalent to `{% pyscript_setup %}`. |
163+
!!! info "At a Glance"
121164

122-
---
165+
With the extension registered, you can call ReactPy functions directly inside any Jinja2 template:
123166

124-
## Step 5: Verify your configuration
167+
=== "templates/example.jinja"
125168

126-
Run Django's [`check` command](https://docs.djangoproject.com/en/stable/ref/django-admin/#check) to verify everything is set up correctly.
169+
```jinja
170+
<!DOCTYPE html>
171+
<html>
172+
<head>
173+
<title>ReactPy + Jinja2</title>
174+
</head>
175+
<body>
176+
<h1>Server-side component</h1>
177+
{{ component("my_app.components.hello_world", recipient="World") }}
127178

128-
```bash linenums="0"
129-
python manage.py check
130-
```
179+
<h1>Client-side PyScript component</h1>
180+
{{ pyscript_component("my_app/components/my_app.py") }}
131181

132-
---
182+
{{ pyscript_setup() }}
183+
</body>
184+
</html>
185+
```
186+
187+
---
188+
189+
<font size="5">**`my_app/components.py`**</font>
190+
191+
{% include-markdown "../../../README.md" start="<!--py-header-start-->" end="<!--py-code-end-->" %}
192+
193+
---
194+
195+
<font size="5">**`my_app/templates/my_template.jinja`**</font>
196+
197+
In your Jinja2 template, call the `component` function directly with the dotted path to your component:
198+
199+
```jinja
200+
<!DOCTYPE html>
201+
<html>
202+
<body>
203+
{{ component("my_app.components.hello_world", recipient="World") }}
204+
</body>
205+
</html>
206+
```
207+
208+
??? info "Template tag vs Jinja2 function syntax"
133209

134-
## Next steps
210+
Unlike Django templates which require `{% load reactpy %}` and `{% component "..." %}`, Jinja2 allows you to call component functions directly using the `{{ component(...) }}` syntax. The registered functions are:
135211

136-
Now you're ready to [create your first component](./your-first-component.md).
212+
| Function | Description |
213+
|---|---|
214+
| `{{ component(dotted_path, *args, **kwargs) }}` | Render a server-side ReactPy component. Equivalent to `{% component ... %}`. |
215+
| `{{ pyscript_component(*file_paths, initial, root) }}` | Render a client-side PyScript component. Equivalent to `{% pyscript_component ... %}`. |
216+
| `{{ pyscript_setup(*extra_py, extra_js, config) }}` | Render PyScript setup configuration. Equivalent to `{% pyscript_setup ... %}`. |

0 commit comments

Comments
 (0)