HTML over ther Wire, or HTML over the WebSockets, is a strategy for creating real-time SPAs by creating a WebSockets connection between a client and a server. It allows JavaScript to request actions, its only responsibility is to handle events, and the backend handles the business logic as well as rendering HTML. This means you can create pages without reloading the page, without AJAX or APIs. One technology provides a secure, stable and low-delay connection for real-time web applications.
Django LiveView is a framework for creating Realtime SPAs using HTML over the Wire technology. It is inspired by Phoenix LiveView and it is built on top of Django Channels.
It allows you to create interactive web applications using only HTML, CSS and Python. JavaScript ONLY is used to capture events, send and receive strings over a WebSockets channel.
Actions are where business logic is stored. The place where you write the functions in Python instead of JavaScript. They are the ones that will be executed when the page is loaded, when a button is clicked, when a form is submitted, etc. They will render the HTML and send it to the client. They are the ones that will receive the data from the client and process it. They are the heart of Django LiveView.
In every app you can create a folder called ~actions~ and inside it a file for each page. For example, ~home.py~ for the home page. The file will have the following structure:
~update_active_nav()~ updates the class that marks the page where we are in the menu. You need update the context with the data that you want to send to the client. ~get_html()~ is a function that renders the template with the context. ~send_html()~ is a function that sends the HTML to the client.
- ~action~: The name of the action that will be executed on the client side. It is used for cache management and to know which action to execute. It will almost always be the same action that the client sent us.
- ~selector~: The selector where the HTML will be placed.
- ~html~: The HTML that will be placed in the selector.
- ~@enable_lang~: It is used to enable the language. It is necessary to use the ~gettext~ function. If you site only has one language, you can remove it.
- ~@loading~: It is used to show a loading animation while the page is being rendered. If there is no loading delay, for example the database access is very fast or you don't access anything external like an API, you can remove it.
If you want to access the database, you can use the Django ORM as you would in a normal view. The only difference is that the views are asynchronous by default. You can use the ~database_sync_to_async~ function from ~channels.db~.
Django LiveView uses the same views as Django, but the main difference is that the views are asynchronous by default.
To make a view renderable by SSR (Server Side Rendering) and by SPA (Single Page Application), you need to create a function with the following structure:
#+BEGIN_SRC python
from .actions.home import get_context as get_home_context
The ~get_home_context()~ function returns a dictionary with the context of the page present in the action. The ~settings.TEMPLATE_BASE~ is the base template that will be rendered, por example ~layouts/base.html~.
If you want to render data from a database on the template, for example:
#+BEGIN_SRC html
{% for article in articles %}
{{ article.title }}
{{ article.content }}
{% endfor %}
#+END_SRC
You will see an error: ~You cannot call this from an async context - use a thread or sync_to_async.~.
You can use the ~sync_to_async~ function from ~asgiref~.
#+BEGIN_SRC python
from asgiref.sync import sync_to_async
from .actions.blog_list import get_context as get_list_context
If you want to move from one page to another, you can use the ~page~ controller and the ~changePage~ action.
For example, you can create a link to the ~about me~ page.
#+BEGIN_SRC html
<a
data-controller="page"
data-action="click->page#changePage"
data-page="about_me"
href="{% url "about me" %}" <!-- Optional -->
role="button" <!-- Optional -->
>Ver completo</a>
#+END_SRC
- ~data-controller~: Indicates that the element is a controller. ~page~ with functions to switch between pages.
- ~data-action~: Indicates that the element is an action. ~click~ to capture the click event. ~page#changePage~ to call the ~changePage~ function of the ~page~ controller.
- ~data-page~: Indicates the name of the page to which you want to move. The name is the same as the name of the action file. For example, ~actions/about_me.py~.
- ~href~: Optional. It is recommended to use the ~href~ attribute to improve SEO or if JavaScript is disabled.
- ~role~: Optional. It is recommended to use the ~role~ attribute to improve accessibility or if JavaScript is disabled.
** Send data
If you want to send data to the next page, you can use the ~data-~ attribute. All datasets will be sent.
For example, you can create a link to the ~blog single~ page with the ~slug~ of the article.
:DESCRIPTION: History management of Django LiveView.
:END:
If you make a SPA you will have a problem with the history management system. When you go back in history, you will lose the data and the HTML of the previous page. This is because the data is removed from the DOM. It is not a problem with Django LiveView.
Django LiveView has a history management system that allows you go back in history without receive any data from the server. Every time you change the page, the data and HTML are stored in the Session Storage. You don't need to do anything, it is automatic! 😸
The only limitation is forward navigation. If you want to go forward, you need to receive the data from the server because the data is remove from the Session Storage when you go back.
You can customize the history management system by editing the ~history~ controller in ~assets/js/mixins/history.js~.
If you want to disable it, remove `startHistory();` from ~assets/js/main.js~.
:DESCRIPTION: Internationalization of Django LiveView.
:END:
Django LiveView uses the same internationalization system as Django. You can read more about it in the [[https://docs.djangoproject.com/en/dev/topics/i18n/][Django documentation]]. However, let's go deeper.
Every time that the client sends a request for action, it sends the language that the user has set in the browser.
#+BEGIN_SRC json
{
"action": "blog_list->send_page",
"data": {
"lang": "es"
}
}
#+END_SRC
The ~lang~ attribute is extracted directly from the ~<html>~ tag.
#+BEGIN_SRC html
{% load static i18n %}
<!doctype html>{% get_current_language as CURRENT_LANGUAGE %}
<html lang="{{ CURRENT_LANGUAGE }}">
#+END_SRC
You can access the language with the ~lang~ parameter of the action using the ~@enable_lang~ decorator.
Or you could read it with the ~lang~ key of the ~client_data~ parameter.
#+BEGIN_SRC python
@loading
async def send_page(consumer, client_data):
print(client_data["data"]["lang"])
#+END_SRC
You can read the tutorial [[#/tutorials/internationalize-with-subdomains/][Internationalize with subdomains]] to see how to create a multilingual website with subdomains.
It is important to note that the ~proxy_set_header~ lines are necessary for the WebSocket to work. You can see more about it in [[https://channels.readthedocs.io/en/latest/deploying.html][Channels]].
:DESCRIPTION: Frequently asked questions about Django LiveView.
:END:
** Do I need to know JavaScript to use Django LiveView?
No, you don't need. You can create SPAs without using APIs, without JavaScript, and without learning anything new. If you know Python, you know how to use Django LiveView.
** Can I use JavaScript?
Yes, you can. You can use JavaScript to capture events, send and receive strings over a WebSockets channel.
** Can I use Django's native tools?
Of course. You can still use all of Django's native tools, such as its ORM, forms, plugins, etc.
** Do I need to use React, Vue, Angular or any other frontend framework?
No. All logic, rendering and state is in the backend.
Learn how to create a Django LiveView application step by step.
- [[#/tutorials/quickstart/][Quickstart]]
- [[#/tutorials/internationalize-with-subdomains/][Internationalize with subdomains]]
* Quickstart
:PROPERTIES:
:ONE: one-custom-default-page
:CUSTOM_ID: /tutorials/quickstart/
:TITLE: Quickstart
:DESCRIPTION: Get started with Django LiveView the easy way.
:END:
Welcome to the Quickstart guide. Here you will learn how to create your first Realtime SPA using Django LiveView. I assume you have a basic understanding of Django and Python.
All the steps are applied in a [[https://github.com/Django-LiveView/minimal-template][minimalist template]].
** 1. Install Django
Install Django, create a project and an app.
** 2. Install LiveView
Install django-liveview with ~pip~.
#+BEGIN_SRC sh
pip install django-liveview
#+END_SRC
** 3. Modify the configuration
Add ~liveview~ to your installed ~INSTALLED_APPS~.
#+BEGIN_SRC python
INSTALLED_APPS = [
"daphne",
"channels",
"liveview",
]
#+END_SRC
Then indicate in which previously created App you want to implement LiveView.
#+BEGIN_SRC python
LIVEVIEW_APPS = ["website"]
#+END_SRC
** 4. Migration
Execute the migrations so that the LiveView tables are generated.
#+BEGIN_SRC python
python manage.py migrate
#+END_SRC
** 5. ASGI
Modify the ASGI file, ~asgi.py~ to add the LiveView routing. In this example it is assumed that settings.py is inside core, in your case it may be different.
Place where the functions and logic of the business logic are stored. We will start by creating an action to generate a random number and print it.
Create inside your App a folder called ~actions~, here will go all the actions for each page. Now we will create inside the folder a file named ~home.py~.
#+BEGIN_SRC python
# my-app/actions/home.py
from liveview.context_processors import get_global_context
There are several points in the above code to keep in mind.
- ~template~ is the name of the template that will be rendered.
- ~get_context()~ is a function that returns a dictionary with the context of the page.
- ~send_page()~ is the function that will be executed when the page is loaded.
- ~random_number()~ is the function that will be executed when the button is clicked.
** 7. Create the base template
Now we will create the base template, which will be the one that will be rendered when the page is loaded.
Create a folder called ~templates~, or use your template folder, inside your App and inside it create another folder called ~layouts~. Now create a file called ~base.html~.
#+BEGIN_SRC html
{# my-app/templates/layouts/base.html #}
{% load static i18n %}
<!doctype html>{% get_current_language as CURRENT_LANGUAGE %}
As you can see, we have defined a button to launch the action of generating the random number (~button~) and the place where we will print the result (~output-random-number~).
** 9. Create frontend
Now we are going to create the frontend, the part where we will manage the JavaScript events and invoke the actions.
Download [[https://github.com/Django-LiveView/assets/archive/refs/heads/main.zip][assets]] and unzip it in your static folder. You will be left with the following route: ~/static/js/~.
** 10. Create View
We will create the view that will render the page for the first time (like Server Side Rendering). The rest of the times will be rendered dynamically (like Single Page Application).
In a normal Django application we would create a view, ~views.py~, similar to the following:
#+BEGIN_SRC python
# my-app/views.py
from django.shortcuts import render
# Create your views here.
def home(request):
return render(request, "pages/home.html")
#+END_SRC
With LiveView, on the other hand, you will have the following structure.
#+BEGIN_SRC python
# my-app/views.py
from django.shortcuts import render
from .actions.home import get_context as get_home_context
:DESCRIPTION: Create a multilingual website with subdomains.
:END:
Here you will learn how to create a multilingual website using Django LiveView. We recommend using subdomains to define the language (~en.example.com~, ~es.example.com~...), instead of using prefixes in addresses (~example.com/en/blog/~, ~example.com/es/blog/~). They simplify SEO, maintain consistency in the Sitemap and are easy to test.
