Skip to content

Commit 6a99175

Browse files
ArchmongerArchmonger
committed
Clean up readme
1 parent 5cdbd07 commit 6a99175

File tree

1 file changed

+67
-119
lines changed

1 file changed

+67
-119
lines changed

‎README.md

+67-119
Original file line numberDiff line numberDiff line change
@@ -27,65 +27,53 @@ interfaces in pure Python.
2727
src="https://mybinder.org/badge_logo.svg"/>
2828
</a>
2929

30-
# Install Django IDOM
30+
# Quick Example
3131

32-
```bash
33-
pip install django-idom
34-
```
32+
## `example_app/components.py`
3533

36-
# Django Integration
34+
This is where you'll define your [IDOM](https://github.com/idom-team/idom) components. Ultimately though, you should
35+
feel free to organize your component modules you wish. Any components created will ultimately be referenced
36+
by Python dotted path in `your-template.html`.
3737

38-
To integrate IDOM into your application you'll need to modify or add the following files to `your_project`:
38+
```python
39+
import idom
3940

40-
```
41-
your_project/
42-
├── __init__.py
43-
├── asgi.py
44-
├── settings.py
45-
├── urls.py
46-
└── example_app/
47-
├── __init__.py
48-
├── components.py
49-
├── templates/
50-
│ └── your-template.html
51-
└── urls.py
41+
@idom.component
42+
def Hello(websocket, greeting_recipient): # Names are CamelCase by ReactJS convention
43+
return idom.html.header(f"Hello {greeting_recipient}!")
5244
```
5345

54-
## `asgi.py`
46+
## `example_app/templates/your-template.html`
5547

56-
Follow the [`channels`](https://channels.readthedocs.io/en/stable/)
57-
[installation guide](https://channels.readthedocs.io/en/stable/installation.html) in
58-
order to create ASGI websockets within Django. Then, we will add a path for IDOM's
59-
websocket consumer using `IDOM_WEBSOCKET_PATH`.
48+
In your templates, you may add IDOM components into your HTML by using the `idom_component`
49+
template tag. This tag requires the dotted path to the component function. Additonally, you can
50+
pass in keyworded arguments into your component function.
6051

61-
_Note: If you wish to change the route where this websocket is served from, see the
62-
available [settings](#settingspy)._
52+
In context this will look a bit like the following...
6353

64-
```python
54+
```jinja
55+
{% load idom %}
6556
66-
import os
57+
<!DOCTYPE html>
58+
<html>
59+
<body>
60+
...
61+
{% idom_component "my_django_project.example_app.components.Hello" greeting_recipient="World" %}
62+
</body>
63+
</html>
64+
```
6765

68-
from django.core.asgi import get_asgi_application
66+
# Installation
6967

70-
from django_idom import IDOM_WEBSOCKET_PATH
68+
Install `django-idom` via pip.
7169

72-
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "test_app.settings")
70+
```bash
71+
pip install django-idom
72+
```
7373

74-
# Fetch ASGI application before importing dependencies that require ORM models.
75-
http_asgi_app = get_asgi_application()
74+
---
7675

77-
from channels.auth import AuthMiddlewareStack
78-
from channels.routing import ProtocolTypeRouter, URLRouter
79-
80-
application = ProtocolTypeRouter(
81-
{
82-
"http": http_asgi_app,
83-
"websocket": SessionMiddlewareStack(
84-
AuthMiddlewareStack(URLRouter([IDOM_WEBSOCKET_PATH]))
85-
),
86-
}
87-
)
88-
```
76+
You'll also need to modify a few files in your Django project...
8977

9078
## `settings.py`
9179

@@ -100,110 +88,70 @@ INSTALLED_APPS = [
10088
]
10189
```
10290

103-
You may configure additional options as well:
91+
You may configure additional options as well...
10492

10593
```python
106-
# the base URL for all IDOM-releated resources
107-
IDOM_BASE_URL: str = "_idom/"
108-
109-
# Set cache size limit for loading JS files for IDOM.
110-
# Only applies when not using Django's caching framework (see below).
111-
IDOM_WEB_MODULE_LRU_CACHE_SIZE: int | None = None
112-
113-
# Maximum seconds between two reconnection attempts that would cause the client give up.
114-
# 0 will disable reconnection.
115-
IDOM_WS_MAX_RECONNECT_DELAY: int = 604800
116-
11794
# Configure a cache for loading JS files
11895
CACHES = {
11996
# Configure a cache for loading JS files for IDOM
12097
"idom_web_modules": {"BACKEND": ...},
12198
# If the above cache is not configured, then we'll use the "default" instead
12299
"default": {"BACKEND": ...},
123100
}
101+
102+
# If your project has no caching configured, django-idom will use an in-memory
103+
# LRU cache for caching JavaScript.
104+
IDOM_WEB_MODULE_LRU_CACHE_SIZE: int | None = None
105+
106+
# Maximum seconds between two reconnection attempts that would cause the client give up.
107+
# 0 will disable reconnection.
108+
IDOM_WS_MAX_RECONNECT_DELAY: int = 604800
109+
110+
# The URL for IDOM to serve its Websockets
111+
IDOM_WEBSOCKET_URL: str = "idom/"
124112
```
125113

126114
## `urls.py`
127115

128-
You'll need to include IDOM's static web modules path using `IDOM_WEB_MODULES_PATH`.
129-
Similarly to the `IDOM_WEBSOCKET_PATH`. If you wish to change the route where this
130-
websocket is served from, see the available [settings](#settings.py).
116+
Add Django-IDOM http URLs to your `urlpatterns`.
131117

132118
```python
133-
from django_idom import IDOM_WEB_MODULES_PATH
134-
135119
urlpatterns = [
136-
IDOM_WEB_MODULES_PATH,
120+
path("idom/", include("django_idom.http.urls")),
137121
...
138122
]
139123
```
140124

141-
## `example_app/components.py`
142-
143-
This is where, by a convention similar to that of
144-
[`views.py`](https://docs.djangoproject.com/en/3.2/topics/http/views/), you'll define
145-
your [IDOM](https://github.com/idom-team/idom) components. Ultimately though, you should
146-
feel free to organize your component modules you wish. The components created here will
147-
ultimately be referenced by name in `your-template.html`. `your-template.html`.
148-
149-
```python
150-
import idom
151-
152-
@idom.component
153-
def Hello(websocket, greeting_recipient): # component names are camelcase by convention
154-
return idom.html.header(f"Hello {greeting_recipient}!")
155-
```
156-
157-
## `example_app/templates/your-template.html`
158-
159-
In your templates, you may inject a view of an IDOM component into your templated HTML
160-
by using the `idom_component` template tag. This tag which requires the name of a component
161-
to render (of the form `module_name.ComponentName`) and keyword arguments you'd like to
162-
pass it from the template.
163-
164-
```python
165-
idom_component module_name.ComponentName param_1="something" param_2="something-else"
166-
```
125+
## `asgi.py`
167126

168-
In context this will look a bit like the following...
127+
If you do not have an `asgi.py`, first follow the [`channels` installation guide](https://channels.readthedocs.io/en/stable/installation.html) in
128+
order to create websockets within Django.
169129

170-
```jinja
171-
{% load idom %}
130+
We will add IDOM's websocket consumer path using `IDOM_WEBSOCKET_PATH`.
172131

173-
<!DOCTYPE html>
174-
<html>
175-
<body>
176-
...
177-
{% idom_component "your_project.example_app.components.Hello" greeting_recipient="World" %}
178-
</body>
179-
</html>
180-
```
181-
182-
## `example_app/views.py`
183-
184-
You can then serve `your-template.html` from a view just
185-
[like any other](https://docs.djangoproject.com/en/3.2/intro/tutorial03/#write-views-that-actually-do-something).
132+
_Note: If you wish to change the route where this websocket is served from, see the
133+
available [settings](#settingspy)._
186134

187135
```python
188-
from django.shortcuts import render
189-
190-
def your_view(request):
191-
context = {}
192-
return render(request, "your-template.html", context)
193-
```
194136

195-
## `example_app/urls.py`
137+
import os
138+
from django.core.asgi import get_asgi_application
139+
from django_idom import IDOM_WEBSOCKET_PATH
196140

197-
Include your view in the list of urlpatterns
141+
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "test_app.settings")
142+
http_asgi_app = get_asgi_application()
198143

199-
```python
200-
from django.urls import path
201-
from .views import your_view # define this view like any other HTML template view
144+
from channels.auth import AuthMiddlewareStack
145+
from channels.routing import ProtocolTypeRouter, URLRouter
202146

203-
urlpatterns = [
204-
path("", your_view),
205-
...
206-
]
147+
application = ProtocolTypeRouter(
148+
{
149+
"http": http_asgi_app,
150+
"websocket": SessionMiddlewareStack(
151+
AuthMiddlewareStack(URLRouter([IDOM_WEBSOCKET_PATH]))
152+
),
153+
}
154+
)
207155
```
208156

209157
# Developer Guide

0 commit comments

Comments
 (0)