Configuration
=============

All djxi settings are optional and have sensible defaults.  Override them in
your project's ``settings.py``.

Runtime settings
----------------

These values can be set in ``settings.py`` and are read by the
``djxi.conf.Settings`` proxy (importable as ``djxi.conf.package_settings``):

.. list-table::
   :header-rows: 1
   :widths: 35 15 50

   * - Setting
     - Default
     - Description
   * - ``DX_HTMX_VERSION``
     - ``"4"``
     - HTMX version to use for the CDN script tag.  Accepted values: ``"2"``
       or ``"4"``.  Also selects the correct ``request.htmx`` /
       ``response.htmx`` header class.
   * - ``DX_HTMX_COMPRESSION``
     - ``".js"``
     - Script variant to load from CDN.  Use ``".min.js"`` for the minified
       build (smaller, but harder to debug).
   * - ``DX_ROUTER_PREFIX``
     - ``"dx"``
     - Global URL prefix prepended to every battery route when
       ``url_patterns()`` is called without an explicit ``prefix=`` kwarg and
       the battery does not set ``battery_prefix``.  Set to ``None`` to
       disable the prefix entirely.
   * - ``DX_MESSAGE_CONTAINER_ID``
     - ``"message-container"``
     - DOM element ID used as the ``hx-swap-oob`` target for flash messages.
   * - ``DX_MESSAGE_SWAP_METHOD``
     - ``"beforeend"``
     - HTMX swap method applied when injecting messages into the container.
   * - ``DX_MESSAGE_TEMPLATE``
     - ``"djxi/messages/message_list.html"``
     - Template path for the message list fragment.  Override to customise
       message rendering without touching the container.
   * - ``DJXI_ROUTE_MODULES``
     - ``["views", "endpoints", "batteries"]``
     - Module suffixes that the ``djxi_routes`` management command tries to
       import from each installed app in order to trigger battery class
       definitions before introspecting subclasses.

Immutable constants
-------------------

The following values are defined in ``djxi.const`` and **cannot** be
overridden via ``settings.py`` — the ``Settings`` proxy returns them before
checking ``django.conf.settings``:

.. list-table::
   :header-rows: 1
   :widths: 30 20 50

   * - Constant
     - Value
     - Purpose
   * - ``DX_SECTION_TAG``
     - ``"dx-section"``
     - HTML tag name used to delimit named template sections.
   * - ``DX_INCLUDE_TAG``
     - ``"dx-include"``
     - HTML tag name used to inline-expand another section.

URL prefix resolution order
---------------------------

When ``url_patterns()`` is called, the prefix is resolved in the following
priority order (highest wins):

1. Explicit kwarg: ``MyBattery.url_patterns(prefix="my/prefix")``
2. Class attribute: ``battery_prefix = "my-prefix"`` on the battery class
3. Django setting: ``DX_ROUTER_PREFIX`` (default ``"dx"``)

Example:

.. code-block:: python

    class ApiV1Battery(DXEndpointBattery):
        battery_prefix = "api/v1"

        @dx_get("items/", name="items")
        def items(self, request):
            ...

    # In urls.py — no prefix= needed, battery_prefix is used:
    urlpatterns = [
        path("", include(ApiV1Battery.url_patterns())),
        # Registers: GET  /api/v1/items/
    ]

Template tags
-------------

Load in any template with ``{% load djxi %}``:

``{% htmx_script_inclusion %}``
    Renders a ``<script>`` tag that loads HTMX from jsDelivr CDN with an SRI
    integrity hash.  Version and compression level are controlled by
    ``DX_HTMX_VERSION`` and ``DX_HTMX_COMPRESSION``.

``{% htmx_headers %}``
    Renders the ``hx-headers`` body attribute (and ``hx-headers:inherited``
    for HTMX 4) containing the CSRF token so all HTMX requests are
    CSRF-protected automatically.

``{% flash_messages_inclusion %}``
    Renders the ``<ul id="message-container">`` element that acts as the
    out-of-band swap target for Django flash messages.

Startup validation
------------------

``DjxiAppConfig.ready()`` validates ``DX_HTMX_VERSION``, ``DX_HTMX_COMPRESSION``,
and ``DX_ROUTER_PREFIX`` on startup and raises ``ImproperlyConfigured`` with a
descriptive message if any value is invalid.