API Reference | Django LiveView

Complete reference for all Django LiveView functions, decorators, and classes.

Decorators

~@liveview_handler(name)~

Parameters:

name (str): The handler name that will be called from the frontend

Returns: Decorated function

Example:

from liveview import liveview_handler

@liveview_handler("my_handler")
def my_handler(consumer, content):
    pass

Functions

~send(consumer, data, broadcast=False)~

Send data to the client(s).

Parameters:

consumer (WebsocketConsumer): The WebSocket consumer instance
data (dict): Dictionary containing the update instructions
broadcast (bool, optional): If True, send to all connected clients. Default: False

Data dictionary keys:

target (str, required): CSS selector of element to update
html (str, optional): HTML content to insert
append (bool, optional): If True, append instead of replace. Default: False
remove (bool, optional): If True, remove the target element. Default: False
url (str, optional): Update browser URL (uses history.pushState)
title (str, optional): Update page title
scroll (str, optional): CSS selector to scroll to
scrollTop (bool, optional): If True, scroll to top of page
script (str, optional): JavaScript code to execute

Returns: None

Examples:

from liveview import send

# Replace content
send(consumer, {
    "target": "#container",
    "html": "<p>New content</p>"
})

# Append content
send(consumer, {
    "target": "#list",
    "html": "<li>New item</li>",
    "append": True
})

# Remove element
send(consumer, {
    "target": "#notification-123",
    "remove": True
})

# Update URL and title
send(consumer, {
    "target": "#main",
    "html": "<h1>New Page</h1>",
    "url": "/new-page/",
    "title": "New Page - My Site"
})

# Execute JavaScript
send(consumer, {
    "script": "console.log('Hello from server');"
})

# Broadcast to all users
send(consumer, {
    "target": "#notifications",
    "html": "<p>New message!</p>",
    "append": True
}, broadcast=True)

Handler Content Parameter

Every handler receives a content dictionary with the following structure:

{
    "function": str,      # Handler name that was called
    "form": dict,         # All form inputs {name: value}
    "data": dict,         # Custom data-data-* attributes
    "lang": str,          # Current language (from <html lang="">)
    "room": str           # WebSocket room identifier
}

Example access:

@liveview_handler("example")
def example(consumer, content):
    function_name = content["function"]           # "example"
    user_input = content["form"]["name"]          # From <input name="name">
    custom_id = content["data"]["item_id"]        # From data-data-item-id
    language = content["lang"]                    # "en", "es", etc.
    room_id = content["room"]                     # "user_123" or UUID

Registry

~liveview_registry~

Global registry for handlers and middleware.

Methods:

~add_middleware(middleware_func)~

Add a middleware function to run before handlers.

Parameters:

middleware_func (callable): Function with signature (consumer, content, function_name) -> bool

Returns: None

Example:

from liveview import liveview_registry

def my_middleware(consumer, content, function_name):
    # Run before handler
    print(f"Calling {function_name}")

    # Return True to continue, False to cancel
    return True

liveview_registry.add_middleware(my_middleware)

~list_functions()~

Get list of all registered handler names.

Returns: List[str]

Example:

from liveview import liveview_registry

handlers = liveview_registry.list_functions()
print(handlers)  # ['say_hello', 'load_articles', ...]

~get_handler(function_name)~

Get a specific handler by name.

Parameters:

function_name (str): Name of the handler to retrieve

Returns: Callable or None

Example:

from liveview import liveview_registry

handler = liveview_registry.get_handler("say_hello")

if handler:
    print(f"Handler found: {handler.__name__}")
else:
    print("Handler not found")

~get_all_handlers()~

Get a dictionary of all registered handlers with their functions.

Returns: Dict[str, Callable]

Example:

from liveview import liveview_registry

all_handlers = liveview_registry.get_all_handlers()

for name, func in all_handlers.items():
    print(f"Handler: {name}, Function: {func.__name__}")

~unregister(function_name)~

Remove a handler from the registry.

Parameters:

function_name (str): Name of the handler to remove

Returns: Callable or None (the removed handler, or None if not found)

Example:

from liveview import liveview_registry

# Unregister a handler
liveview_registry.unregister("old_handler")

# Verify it's gone
if liveview_registry.get_handler("old_handler") is None:
    print("Handler successfully unregistered")

~clear()~

Remove all registered handlers.

Returns: None

Example:

from liveview import liveview_registry

# Remove all handlers
liveview_registry.clear()

# Verify
print(liveview_registry.list_functions())  # []

⚠️ Warning: This clears ALL handlers. Only use in testing or when reinitializing the application.

Routing

~get_liveview_urlpatterns()~

Get URL patterns for WebSocket routing.

Returns: List of URL patterns

Example:

from liveview.routing import get_liveview_urlpatterns
from channels.routing import URLRouter

application = URLRouter(
    get_liveview_urlpatterns()
)

Frontend Attributes

HTML Attributes

~data-controller="page"~

Required on <body> element to activate Stimulus controller.

<body data-controller="page">

~data-room="room-id"~

WebSocket room identifier. Use {% liveview_room_uuid %} to generate a random UUID for each request.

{% load liveview %}
<html data-room="{% liveview_room_uuid %}">

~data-liveview-function="handler-name"~

Specifies which handler to call.

<button data-liveview-function="say_hello">Click</button>

~data-action="event->controller#action"~

Stimulus action binding.

<button data-action="click->page#run">Click</button>
<input data-action="input->page#run">
<form data-action="submit->page#run">

~data-data-*~

Custom data attributes sent to handler in content["data"].

<button data-data-user-id="123" data-data-action="delete">

Becomes:

content["data"]["user_id"]  # "123"
content["data"]["action"]   # "delete"

~data-liveview-debounce="milliseconds"~

Delay before sending request.

<input data-liveview-debounce="500" data-action="input->page#run">

~data-liveview-focus="true"~

Auto-focus element after rendering.

<input data-liveview-focus="true">

~data-liveview-init="handler-name"~

Call handler when element is first rendered.

<div data-liveview-init="initialize_chart">

~data-liveview-intersect-appear="handler-name"~

Call handler when element appears in viewport.

<div data-liveview-intersect-appear="load_more">

~data-liveview-intersect-disappear="handler-name"~

Call handler when element leaves viewport.

<div data-liveview-intersect-disappear="pause_video">

~data-liveview-intersect-threshold="pixels"~

Trigger intersection before entering viewport.

<div
    data-liveview-intersect-appear="load_more"
    data-liveview-intersect-threshold="200">

Consumer Scope

The consumer parameter provides access to connection metadata:

@liveview_handler("example")
def example(consumer, content):
    # Get authenticated user
    user = consumer.scope.get("user")

    # Get session data
    session = consumer.scope.get("session")

    # Get URL route kwargs
    url_kwargs = consumer.scope.get("url_route", {}).get("kwargs", {})

    # Get headers
    headers = dict(consumer.scope.get("headers", []))