Core Concepts

Understanding the fundamental concepts behind djust's reactive server-side rendering.

Architecture

djust connects browser interactions to server-side state through WebSocket or HTTP. The client (Browser (Client)) contains DOM (HTML) and djust.js (~29KB gz), communicating via WebSocket/HTTP with the server (Server (Django)).

LiveView

A LiveView is a Django view that maintains state between requests and updates the UI reactively. Unlike traditional request-response views, LiveViews stay connected and can push updates to the client in real-time.

Lifecycle Methods

Method	When Called	Purpose
`mount(request, **kwargs)`	Initial page load	Initialize state
`render()`	After any state change	Return HTML (auto-called)
`handle_params(params)`	URL params change	React to URL changes
`terminate()`	Session ends	Cleanup resources

Example LiveView

views.py
from djust import LiveView, event_handler

class CounterView(LiveView):
    template_name = 'counter.html'

    def mount(self, request, **kwargs):
        """Called when the view first loads."""
        self.count = 0

    @event_handler
    def increment(self):
        """Event handler for increment button."""
        self.count += 1

    @event_handler
    def decrement(self):
        """Event handler for decrement button."""
        self.count -= 1

Example Template

templates/counter.html
<div dj-liveview>
    <h1>Count: {{ count }}</h1>

    <button dj-click="decrement">-</button>
    <button dj-click="increment">+</button>
</div>

Events

Events connect user interactions to server-side handlers. Use dj-* attributes in your templates to bind events.

Event Bindings

Attribute	Description	Example
`dj-click`	Handle click events	`<button dj-click="increment">+1</button>`
`dj-input`	Handle input on every keystroke	`<input dj-input="search" value="{{ search }}">`
`dj-change`	Handle input on blur (leaving field)	`<input dj-change="update_email" value="{{ email }}">`
`dj-submit`	Handle form submission	`<form dj-submit="create_user">...</form>`
`dj-keydown`	Handle keyboard events	`<input dj-keydown="handle_key" dj-key="Enter">`

Key Concepts

Server-Side State - All state lives on the server. No client-side state management needed.
Reactive Updates - When state changes, only the changed parts of the DOM are updated.
VDOM Diffing - Rust-powered virtual DOM calculates minimal patches for efficient updates.
Event Handlers - Any method can handle events. Use @event_handler decorator for explicit marking.

VDOM Architecture

djust uses a Rust-powered Virtual DOM for efficient updates. Instead of re-sending the entire page, only the differences (patches) are sent.

1. Server renders HTML template
2. Rust parses HTML into VDOM tree
3. Client receives initial HTML
4. On state change:
   a. Server re-renders template
   b. Rust diffs old vs new VDOM
   c. Only differences sent to client
   d. Client patches DOM surgically

Performance Benefit

Approach	Update 1 item in 1000-item list
Full re-render	Send ~50KB, replace entire DOM
djust VDOM	Send ~100 bytes, patch 1 element

Next Steps

Components - Explore the component library
State Management - Deep dive into state
API Reference - Complete API documentation

Learn djust Inside & Out.