next.dj
Usage Questions¶
This page answers questions that come up while building a project with next.dj.
How Do I Add a Page¶
Create a directory under the page root and add a page.py plus a template.djx inside it.
See Add a Page for a recipe.
How Do I Pass Data to the Template¶
Use @context("key") inside page.py to publish a value.
The template renders the value as {{ key }}.
See Context.
How Do I Capture URL Parameters¶
Name the directory [param] for a string or [type:param] for a typed value.
Inside the page module annotate the parameter with DUrl[T].
See File Router.
How Do I Render a Form¶
Register a handler with @action and render the form with {% form @action="name" %}.
See Forms and Actions.
How Do I Customise the Static Output¶
Subclass a static backend, register its dotted path in DEFAULT_STATIC_BACKENDS, and override how tags or asset URLs are produced.
See Customise Rendered Static Tags.
How Do I Test a Page¶
Use NextClient from next.testing.client.
See Testing.
How Do I Run the Development Server¶
Run uv run python manage.py runserver.
The autoreloader picks up new and changed page directories without a restart.
How Do I Deploy in Production¶
Serve the project through a WSGI or ASGI server and collect static files the same way as any Django project. See Deployment for the framework-specific checklist.
How Do I Integrate Django Admin¶
Mount admin.site.urls above include("next.urls") in config/urls.py.
See Integrate Django Admin.
How Do I Split Routes Across Applications¶
Two strategies.
Use APP_DIRS=True so every application contributes its own page tree.
Use DIRS to add project level page roots.
See File Router.
How Do I Add Context Processors to Pages¶
Add a context_processors list to the OPTIONS dict of the relevant page backend entry.
The list merges with the processors from the first TEMPLATES entry in Django settings.
Duplicates are dropped.
See Context for the merge order and a full settings example.
How Do I Keep Query Parameters After a Form Action Redirect¶
Build the redirect URL from the form’s cleaned_data inside the action handler.
The {% form %} tag posts to the framework’s action endpoint, so request.GET is empty on the POST side.
Reconstruct the query string from the validated fields instead.
from django.http import HttpResponseRedirect
from django.urls import reverse
from next.forms import action
from notes.forms import SearchForm
@action("search", form_class=SearchForm)
def search(form: SearchForm) -> HttpResponseRedirect:
q = form.cleaned_data.get("q", "")
base = reverse("next:page_notes")
return HttpResponseRedirect(f"{base}?q={q}" if q else base)
For filter forms with no side effects, use <form method="get"> directly and skip @action altogether.
The DQuery marker then reads every filter from the query string on the GET request without a round-trip through the action endpoint.
Can a Form Action Return a Custom HTTP Status Code¶
Return any HttpResponseBase subclass.
from django.http import HttpResponse
from next.forms import action
from notes.forms import NoteForm
@action("create_note", form_class=NoteForm)
def create_note(form: NoteForm) -> HttpResponse:
form.save()
return HttpResponse(status=204)
Common choices are HttpResponse(status=204) for no-content responses, HttpResponse(status=201) for created resources, and HttpResponseRedirect(url, status=303) for POST-redirect-GET flows.
How Do I Translate URLs or Templates¶
Internationalisation stays on Django’s stack.
Configure LocaleMiddleware, translation files, and i18n_patterns (or your preferred URL prefix strategy) the same way as in a stock Django project.
File routes resolve under whatever locale-aware prefix Django exposes.
next.dj does not ship a separate translation mechanism for page.py files beyond ordinary Django template translation tags.
See Django’s translation overview.
See Also¶
See also
How-To Guides for recipes. Topic Guides for in depth guides.