Reusable Shell

This section covers utilities for encapsulating and orchestrating reusable application shells across both function-based and class-based views.

Shell Renderer (htmx_nav.shell)

Create ShellRenderers, a reusable wrapper around a render_nav.

Allows the definition of a shell (e.g. sidebar and breadcrumbs) as the regions that need to always be synced in htmx requests for that endpoint.

class htmx_nav.shell.ShellRenderer(*args, **kwargs)

Bases: Protocol

Callable signature for renderers produced by make_shell_renderer.

htmx_nav.shell.make_shell_renderer(swaps, *, partial=<object object>)

Create a renderer that always includes a fixed set of Swaps.

Parameters:

• swaps (Swap | list[Swap] | tuple[Swap, ...] | None | Callable[[HttpRequest], Swap | list[Swap] | tuple[Swap, ...] | None]) – Swaps included on each request, or a callable receiving request and returning Swaps.

• partial (str | Callable[[HttpRequest], str | None] | Mapping[str | PartialResolver, str | Callable[[HttpRequest], bool] | bool] | PartialResolver | None | object) – Default PartialSpec for views rendered through this shell, overridable per call. When omitted, HTMX_NAV_DEFAULT_PARTIAL ("#content") applies, read on each request.

Return type:

ShellRenderer

Returns:

A render_shell function matching the ShellRenderer protocol.

Example

def build_shell_swaps(request):
    return [
        Swap("nav/_sidebar.html", sidebar_context(request), target_id="sidebar"),
        Swap("nav/_breadcrumbs.html", crumbs_context(request), target_id="breadcrumbs"),
    ]

render_shell = make_shell_renderer(build_shell_swaps)

def project_detail(request, pk):
    project = get_object_or_404(Project, pk=pk)
    return render_shell(request, "app/project_detail.html", {"project": project})

View Mixins (htmx_nav.views)

htmx_nav.views.make_shell_view_mixin(render=None, *, default_swaps=None, default_partial=<object object>)

Create a class mixin that routes CBV rendering through a shell renderer.

Parameters:

• render (ShellRenderer | None) – Optional renderer from make_shell_renderer. When omitted, the mixin calls render_nav directly.

• default_swaps (Swap | list[Swap] | tuple[Swap, ...] | None) – Swaps applied to every view using this mixin.

• default_partial (str | Callable[[HttpRequest], str | None] | Mapping[str | PartialResolver, str | Callable[[HttpRequest], bool] | bool] | PartialResolver | None | object) – Partial used unless a view overrides get_partial(). When omitted, the renderer’s own default applies, or HTMX_NAV_DEFAULT_PARTIAL ("#content") without a renderer.

Return type:

type

Returns:

A mixin class. Place it before the Django view class in the bases so its render_to_response wins.

Notes

Override points on the resulting view class:

• get_extra_swaps(): Returns per-view swaps (runs with self.object available).

• get_title() or title: Page title override.

• get_partial(): Overrides default_partial for the view.

• get_shell_template_name(): Defaults to get_template_names()[0].

• get_template_names(): Django’s own hook. Only the first entry

  is rendered, since partial resolution needs one concrete name.

Example

ShellViewMixin = make_shell_view_mixin()

class TicketListView(ShellViewMixin, ListView):
    template_name = "pages/project.html"

    def get_extra_swaps(self):
        return [sidebar_swap, breadcrumb_swap]

Request Helpers (htmx_nav.helpers)

htmx_nav.helpers.cache_on_request(request, key, builder)

Cache and return a computed value on the Django request object.

Parameters:

• request (HttpRequest) – The Django HTTP request.

• key (str) – The attribute name to store the cached value under.

• builder (Callable[[], TypeVar(T)]) – A callable that generates the value if not already cached.

Return type:

TypeVar(T)

Returns:

The cached or newly computed value.