Skip to content

Beginner friendly readme #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jan 31, 2022
Merged

Beginner friendly readme #58

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
eb46c35
readme cleanup
Archmonger Jan 30, 2022
b0736ec
minor changes
Archmonger Jan 30, 2022
c404cdf
more robust html example
Archmonger Jan 30, 2022
051708c
remove HR
Archmonger Jan 30, 2022
41e8640
minor wordsmithing
Archmonger Jan 30, 2022
bb6b9f9
Update README.md
rmorshea Jan 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 29 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,17 +25,18 @@ by Python dotted path in `your-template.html`.
from idom import component, html
from django_idom import IdomWebsocket


# Components are CamelCase by ReactJS convention
@component
def Hello(websocket: IdomWebsocket, greeting_recipient: str): # Names are CamelCase by ReactJS convention
def Hello(websocket: IdomWebsocket, greeting_recipient: str):
return html.header(f"Hello {greeting_recipient}!")
```

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

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

Additonally, you can pass in keyworded arguments into your component function.

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

Expand All @@ -44,8 +45,11 @@ In context this will look a bit like the following...

<!DOCTYPE html>
<html>
<head>
<title>Example Project</title>
</head>

<body>
...
{% idom_component "my_django_project.example_app.components.Hello" greeting_recipient="World" %}
</body>
</html>
Expand All @@ -59,27 +63,27 @@ Install `django-idom` via pip.
pip install django-idom
```

---

You'll also need to modify a few files in your Django project...
You'll also need to modify a few files in your Django project.

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

In your settings you'll need to add `django_idom` to the
[`INSTALLED_APPS`](https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-INSTALLED_APPS)
list:
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).

```python
INSTALLED_APPS = [
...,
"channels",
"django_idom",
]

# Ensure ASGI_APPLICATION is set properly based on your project name!
ASGI_APPLICATION = "my_django_project.asgi.application"
```

You may configure additional options as well...
**Optional:** You can also configure IDOM settings.

```python
# If "idom" cache is not configured, then we'll use the "default" instead
# If "idom" cache is not configured, then we'll use "default" instead
CACHES = {
"idom": {"BACKEND": ...},
}
Expand All @@ -88,15 +92,17 @@ CACHES = {
# 0 will disable reconnection.
IDOM_WS_MAX_RECONNECT_DELAY: int = 604800

# The URL for IDOM to serve its Websockets
# The URL for IDOM to serve websockets
IDOM_WEBSOCKET_URL: str = "idom/"
```

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

Add Django-IDOM http URLs to your `urlpatterns`.
Add IDOM HTTP paths to your `urlpatterns`.

```python
from django.urls import include, path

urlpatterns = [
path("idom/", include("django_idom.http.urls")),
...
Expand All @@ -105,29 +111,27 @@ urlpatterns = [

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

If you do not have an `asgi.py`, first follow the [`channels` installation guide](https://channels.readthedocs.io/en/stable/installation.html) in
order to create websockets within Django.

We will add IDOM's websocket consumer path using `IDOM_WEBSOCKET_PATH`.
Register IDOM's websocket using `IDOM_WEBSOCKET_PATH`.

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

```python

import os
from django.core.asgi import get_asgi_application
from django_idom import IDOM_WEBSOCKET_PATH

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "test_app.settings")
http_asgi_app = get_asgi_application()
# Ensure DJANGO_SETTINGS_MODULE is set properly based on your project name!
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "my_django_project.settings")
django_asgi_app = get_asgi_application()

from channels.auth import AuthMiddlewareStack
from channels.routing import ProtocolTypeRouter, URLRouter
from channels.sessions import SessionMiddlewareStack
from django_idom import IDOM_WEBSOCKET_PATH

application = ProtocolTypeRouter(
{
"http": http_asgi_app,
"http": django_asgi_app,
"websocket": SessionMiddlewareStack(
AuthMiddlewareStack(URLRouter([IDOM_WEBSOCKET_PATH]))
),
Expand Down