Configuration¶

Point dj-hyperview at templates owned by your Django project:

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

HYPERVIEW = {
    "TEMPLATE_DIRS": [BASE_DIR / "hyperview"],
    "SOURCES": [
        {"BACKEND": "dj_hyperview.sources.FileSystemSource"},
    ],
}

Resolve a canonical relative POSIX name through the public API:

from dj_hyperview import TemplateResolver

template = TemplateResolver.from_settings().resolve("screens/home.xml")

Sources are queried in order and the first hit wins. Absolute paths, traversal, backslashes, empty path segments, control characters, and surrogates are rejected. Omitting CACHE keeps caching disabled and avoids cache backend initialization.

DummyCache is not a valid Hyperview cache backend because it cannot preserve generation state. To disable caching, omit CACHE instead of selecting a dummy cache alias.

FileBasedCache and its subclasses are rejected with dj_hyperview.E018, even when CACHE.FAILURE_MODE is bypass: their non-atomic add() cannot protect template generations. Select a backend with atomic add and coherent reads, or omit CACHE. This is a configuration error, not a recoverable backend outage.

Settings reference¶

All keys are optional except the fields inside each configured source. Cache defaults apply only when CACHE is a non-empty mapping; omitting it or using an empty mapping disables Hyperview caching.

Raw-source size, encoding, and forbidden-declaration checks cannot be disabled by VALIDATION.MODE. Final parsing, depth, node, and schema checks run only for render and publish_and_render.

Hyperview XSD 1.1 validation¶

Install the optional schema profile and select the bundled validator:

uv add "dj-hyperview[schema]"

HYPERVIEW = {
    "EXTRA_SCHEMAS": [BASE_DIR / "schema" / "hypertodo.xsd"],
    "VALIDATION": {
        "SCHEMA": "dj_hyperview.validate_hyperview_schema",
    },
}

The validator uses the versioned Hyperview 0.110.0 XSD registry included in the wheel. Project schemas can declare namespaced custom elements and import the Hyperview namespace. Includes, imports, and redefines may reference only local files below the configured schema's own directory. Remote references, paths that escape that directory, percent-encoded reference locations, and arbitrary xs:override declarations are rejected. Reference locations must use plain local paths so the guard and compiler resolve the same file. Each extra schema may reference at most 256 distinct files, including its root; include cycles are visited once and symlink escapes are rejected.

Schema registries and custom completion catalogs use the same complete transitive dependency fingerprints: resolved paths, file sizes, nanosecond modification times, and selected profile. References are checked for safety before cache hits, including after a dependency changes. Changes to HYPERVIEW clear both caches. Saving a referenced local schema refreshes validation and editor suggestions on their next request without restarting Django.

Opt in to compatible percentage margins¶

The default upstream-0.110.0 profile preserves the original XSD behavior. Choose the narrowly scoped compatibility profile only when the client uses percentage margins:

HYPERVIEW = {
    "SCHEMA_PROFILE": "compatible-0.110.0",
    "VALIDATION": {
        "SCHEMA": "dj_hyperview.validate_hyperview_schema",
    },
}

This accepts signed decimal percentages such as margin="50%" and marginTop="-12.5%", while retaining integer and auto values. The only broadened attributes are margin, marginBottom, marginHorizontal, marginLeft, marginRight, marginTop, marginEnd, marginStart, and marginVertical. Types for letterSpacing, outlineWidth, flexGrow, and all other attributes remain upstream-defined; this is not general client/XSD parity. Selecting a profile does not enable final schema validation by itself: keep the VALIDATION.SCHEMA callable shown above.

The package uses one fixed trusted overlay and leaves upstream XSD files and catalog.json unchanged. Both profiles reuse that completion catalog; tests prove the overlay generates identical suggestions. get_hyperview_catalog() includes the selected schema_profile alongside schema_version. The public get_hyperview_schema_path() and build_hyperview_catalog() functions always inspect upstream resources, independently of Django settings.

Follow Add custom HXML elements for the complete namespace, registration, validation, and autocomplete workflow. Its custom component schema example defines app:swipe-row and app:swipe-action.

Admin editor¶

The enhanced editor is deliberately separate from database storage:

uv add "dj-hyperview[editor]"

INSTALLED_APPS = [
    "django_ace",
    "dj_hyperview",
    "dj_hyperview.contrib.database",
]

HYPERVIEW = {
    "ADMIN": {
        "EDITOR": True,
        "PERMISSION": "sample_app.permissions.can_edit_hyperview",
    },
}

Enabling the setting without the extra, or without django_ace in INSTALLED_APPS, produces an actionable Django system-check error. When the setting is false, the standard Django textarea remains unchanged.

Stored templates are executable Django template source, so mutations default to superusers even when a staff user holds the model's ordinary add, change, or delete permissions. A project can replace that policy with an inline callable:

HYPERVIEW = {
    "ADMIN": {
        "PERMISSION": lambda request: request.user.is_superuser,
    },
}

For reusable and testable production configuration, prefer a dotted path:

# sample_app/permissions.py
from django.http import HttpRequest


def can_edit_hyperview(request: HttpRequest) -> bool:
    """Return whether the current user may mutate stored HXML templates."""
    return request.user.has_perm("dj_hyperview_database.change_hyperviewtemplate")

HYPERVIEW = {
    "ADMIN": {
        "PERMISSION": "sample_app.permissions.can_edit_hyperview",
    },
}

The callback is authoritative for all three mutation operations rather than an additional Django model-permission check. Admin-site access still requires an active staff user. Standard model view permission continues to govern read-only access. Missing paths, non-callables, and callbacks that cannot accept one request fail Django system checks; runtime exceptions and non-boolean return values fail closed.

Source backend options¶

OPTIONS is an optional mapping. The resolver passes its entries to the configured backend constructor as keyword arguments. The bundled backends support the following options:

template_dirs must be a list or tuple of roots. Do not pass a single string, Path, generator, set, or other iterable: only reusable ordered collections are accepted. A root that is temporarily unavailable emits a system-check warning; resolution continues through later roots.

For example, one filesystem source can override the global roots:

HYPERVIEW = {
    "TEMPLATE_DIRS": [BASE_DIR / "hyperview"],
    "SOURCES": [
        {
            "BACKEND": "dj_hyperview.sources.FileSystemSource",
            "OPTIONS": {
                "template_dirs": [BASE_DIR / "tenant-hyperview"],
            },
        },
    ],
}

A custom backend defines its own supported OPTIONS through its constructor. There is no package-wide list for third-party options; unknown keyword arguments fail during source initialization. See Filesystem and Database and admin for backend-specific behavior.

Template engine behavior¶

Named templates use dj-hyperview's dedicated resolver-backed template engine by default. That engine copies only context_processors, string_if_invalid, builtins, and libraries from the first configured DjangoTemplates backend or subclass. It deliberately isolates security-sensitive options such as autoescape and replaces the backend's loaders, so template lookup still follows HYPERVIEW["SOURCES"] and never falls through to unrelated Django template directories.

The response path does not switch engines when SOURCES is empty. An empty source list therefore produces a normal missing-template result. To opt out and select a consumer Django engine explicitly, pass its alias, for example using="django", to HyperviewTemplateResponse. The dj_hyperview.W005 system check calls out an absent configuration or an explicitly empty source list. Temporarily unavailable filesystem roots emit dj_hyperview.W006 and do not prevent later roots from resolving templates.

Continue with Filesystem, Database and admin, Cache consistency, Security, Testing, Release and rollback, or the public Python API. Return to the documentation home.