Skip to content

Commit 293393e

Browse files
Archmongerrmorshea
Archmonger
and
rmorshea
authored
Beginner friendly readme (#58)
Co-authored-by: Ryan Morshead <ryan.morshead@gmail.com>
1 parent 6ddab71 commit 293393e

File tree

1 file changed

+29
-25
lines changed

1 file changed

+29
-25
lines changed

‎README.md

+29-25
Original file line numberDiff line numberDiff line change
@@ -25,17 +25,18 @@ by Python dotted path in `your-template.html`.
2525
from idom import component, html
2626
from django_idom import IdomWebsocket
2727

28-
28+
# Components are CamelCase by ReactJS convention
2929
@component
30-
def Hello(websocket: IdomWebsocket, greeting_recipient: str): # Names are CamelCase by ReactJS convention
30+
def Hello(websocket: IdomWebsocket, greeting_recipient: str):
3131
return html.header(f"Hello {greeting_recipient}!")
3232
```
3333

3434
## [`example_app/templates/your-template.html`](https://docs.djangoproject.com/en/dev/topics/templates/)
3535

3636
In your templates, you may add IDOM components into your HTML by using the `idom_component`
37-
template tag. This tag requires the dotted path to the component function. Additonally, you can
38-
pass in keyworded arguments into your component function.
37+
template tag. This tag requires the dotted path to the component function.
38+
39+
Additonally, you can pass in keyworded arguments into your component function.
3940

4041
In context this will look a bit like the following...
4142

@@ -44,8 +45,11 @@ In context this will look a bit like the following...
4445
4546
<!DOCTYPE html>
4647
<html>
48+
<head>
49+
<title>Example Project</title>
50+
</head>
51+
4752
<body>
48-
...
4953
{% idom_component "my_django_project.example_app.components.Hello" greeting_recipient="World" %}
5054
</body>
5155
</html>
@@ -59,27 +63,27 @@ Install `django-idom` via pip.
5963
pip install django-idom
6064
```
6165

62-
---
63-
64-
You'll also need to modify a few files in your Django project...
66+
You'll also need to modify a few files in your Django project.
6567

6668
## [`settings.py`](https://docs.djangoproject.com/en/dev/topics/settings/)
6769

68-
In your settings you'll need to add `django_idom` to the
69-
[`INSTALLED_APPS`](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-INSTALLED_APPS)
70-
list:
70+
In your settings you'll need to add `channels` and `django_idom` to [`INSTALLED_APPS`](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-INSTALLED_APPS).
7171

7272
```python
7373
INSTALLED_APPS = [
7474
...,
75+
"channels",
7576
"django_idom",
7677
]
78+
79+
# Ensure ASGI_APPLICATION is set properly based on your project name!
80+
ASGI_APPLICATION = "my_django_project.asgi.application"
7781
```
7882

79-
You may configure additional options as well...
83+
**Optional:** You can also configure IDOM settings.
8084

8185
```python
82-
# If "idom" cache is not configured, then we'll use the "default" instead
86+
# If "idom" cache is not configured, then we'll use "default" instead
8387
CACHES = {
8488
"idom": {"BACKEND": ...},
8589
}
@@ -88,15 +92,17 @@ CACHES = {
8892
# 0 will disable reconnection.
8993
IDOM_WS_MAX_RECONNECT_TIMEOUT: int = 604800
9094

91-
# The URL for IDOM to serve its Websockets
95+
# The URL for IDOM to serve websockets
9296
IDOM_WEBSOCKET_URL: str = "idom/"
9397
```
9498

9599
## [`urls.py`](https://docs.djangoproject.com/en/dev/topics/http/urls/)
96100

97-
Add Django-IDOM http URLs to your `urlpatterns`.
101+
Add IDOM HTTP paths to your `urlpatterns`.
98102

99103
```python
104+
from django.urls import include, path
105+
100106
urlpatterns = [
101107
path("idom/", include("django_idom.http.urls")),
102108
...
@@ -105,29 +111,27 @@ urlpatterns = [
105111

106112
## [`asgi.py`](https://docs.djangoproject.com/en/dev/howto/deployment/asgi/)
107113

108-
If you do not have an `asgi.py`, first follow the [`channels` installation guide](https://channels.readthedocs.io/en/stable/installation.html) in
109-
order to create websockets within Django.
110-
111-
We will add IDOM's websocket consumer path using `IDOM_WEBSOCKET_PATH`.
114+
Register IDOM's websocket using `IDOM_WEBSOCKET_PATH`.
112115

113-
_Note: If you wish to change the route where this websocket is served from, see the
114-
available [settings](#settingspy)._
116+
_Note: If you do not have an `asgi.py`, follow the [`channels` installation guide](https://channels.readthedocs.io/en/stable/installation.html)._
115117

116118
```python
117119

118120
import os
119121
from django.core.asgi import get_asgi_application
120-
from django_idom import IDOM_WEBSOCKET_PATH
121122

122-
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "test_app.settings")
123-
http_asgi_app = get_asgi_application()
123+
# Ensure DJANGO_SETTINGS_MODULE is set properly based on your project name!
124+
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "my_django_project.settings")
125+
django_asgi_app = get_asgi_application()
124126

125127
from channels.auth import AuthMiddlewareStack
126128
from channels.routing import ProtocolTypeRouter, URLRouter
129+
from channels.sessions import SessionMiddlewareStack
130+
from django_idom import IDOM_WEBSOCKET_PATH
127131

128132
application = ProtocolTypeRouter(
129133
{
130-
"http": http_asgi_app,
134+
"http": django_asgi_app,
131135
"websocket": SessionMiddlewareStack(
132136
AuthMiddlewareStack(URLRouter([IDOM_WEBSOCKET_PATH]))
133137
),

0 commit comments

Comments
 (0)