django-idom
allows you to integrate IDOM into
Django applications. IDOM is a pure Python library inspired by
ReactJS for creating responsive web interfaces.
You can try IDOM now in a Jupyter Notebook:
pip install django-idom
To integrate IDOM into your application you'll need to modify or add the following files to your_project
:
your_project/
├── __init__.py
├── asgi.py
├── settings.py
├── urls.py
└── example_app/
├── __init__.py
├── idom.py
├── templates/
│ └── your-template.html
└── urls.py
Follow the channels
installation guide in
order to create ASGI websockets within Django. Then, we will add a path for IDOM's
websocket consumer using IDOM_WEBSOCKET_PATH
.
Note: If you wish to change the route where this websocket is served from, see the available settings.
import os
from django.core.asgi import get_asgi_application
from django_idom import IDOM_WEB_MODULES_PATH
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "test_app.settings")
# Fetch ASGI application before importing dependencies that require ORM models.
http_asgi_app = get_asgi_application()
from channels.routing import ProtocolTypeRouter, URLRouter
application = ProtocolTypeRouter(
{
"http": http_asgi_app,
"websocket": URLRouter(
# add a path for IDOM's websocket
[IDOM_WEB_MODULES_PATH]
),
}
)
In your settings you'll need to add django_idom
to the
INSTALLED_APPS
list:
INSTALLED_APPS = [
...,
"django_idom",
]
You may configure additional options as well:
# the base URL for all IDOM-releated resources
IDOM_BASE_URL: str = "_idom/"
# Set cache size limit for loading JS files for IDOM.
# Only applies when not using Django's caching framework (see below).
IDOM_WEB_MODULE_LRU_CACHE_SIZE: int | None = None
# Configure a cache for loading JS files
CACHES = {
# Configure a cache for loading JS files for IDOM
"idom_web_modules": {"BACKEND": ...},
# If the above cache is not configured, then we'll use the "default" instead
"default": {"BACKEND": ...},
}
You'll need to include IDOM's static web modules path using IDOM_WEB_MODULES_PATH
.
Similarly to the IDOM_WEBSOCKET_PATH
. If you wish to change the route where this
websocket is served from, see the available settings.
from django_idom import IDOM_WEB_MODULES_PATH
urlpatterns = [
IDOM_WEB_MODULES_PATH,
...
]
This is where, by a convention similar to that of
views.py
, you'll define
your IDOM components. Ultimately though, you should
feel free to organize your component modules you wish. The components created here will
ultimately be referenced by name in your-template.html
. your-template.html
.
import idom
@idom.component
def Hello(greeting_recipient): # component names are camelcase by convention
return Header(f"Hello {greeting_recipient}!")
In your templates, you may inject a view of an IDOM component into your templated HTML
by using the idom_component
template tag. This tag which requires the name of a component
to render (of the form module_name.ComponentName
) and keyword arguments you'd like to
pass it from the template.
idom_component module_name.ComponentName param_1="something" param_2="something-else"
In context this will look a bit like the following...
<!-- don't forget your load statements -->
{% load static %}
{% load idom %}
<!DOCTYPE html>
<html>
<body>
...
{% idom_component "your_project.example_app.components.Hello" greeting_recipient="World" %}
</body>
</html>
You can then serve your-template.html
from a view just
like any other.
from django.http import HttpResponse
from django.template import loader
def your_view(request):
context = {}
return HttpResponse(
loader.get_template("your-template.html").render(context, request)
)
Include your view in the list of urlpatterns
from django.urls import path
from .views import your_view # define this view like any other HTML template view
urlpatterns = [
path("", your_view),
...
]
If you plan to make code changes to this repository, you'll need to install the following dependencies first:
- NPM for installing and managing Javascript
- ChromeDriver for testing with Selenium
Once done, you should clone this repository:
git clone https://github.com/idom-team/django-idom.git
cd django-idom
Then, by running the command below you can:
-
Install an editable version of the Python code
-
Download, build, and install Javascript dependencies
pip install -e . -r requirements.txt
Finally, to verify that everything is working properly, you'll want to run the test suite.
This repo uses Nox to run scripts which can
be found in noxfile.py
. For a full test of available scripts run nox -l
. To run the full test suite simple execute:
nox -s test
To run the tests using a headless browser:
nox -s test -- --headless