Tutorial: Your first Djxi EndpointBattery
========================================

This tutorial walks through the `todo` example included with the project
(`sourcecode/example/todo`) and demonstrates how to create a small
`DXEndpointBattery` that exposes multiple endpoint methods.

1) The template
----------------

In the example the endpoint uses `INLINE_TEMPLATE` containing several
`<dx-section name="...">` blocks. Each named section is rendered independently
via the endpoint's `render_section` method.

2) The endpoint class
---------------------

Look at `sourcecode/example/todo/views.py` — the `TodoListDXBattery` class:

- Inherits from `DXEndpointBattery` which in turn provides `DXSectionMixin` and
  `DXRouterMixin` functionality.
- Sets `inline_template = INLINE_TEMPLATE` to define all its sections.
- Defines helper methods like `get_item` and `get_all` for data access.
- Declares route handlers with `@dx_get`, `@dx_put`, `@dx_delete`, and
  `@dx_action` for multi-method endpoints.

Example handler:

.. code-block:: python

    @dx_get("list", name="list")
    def list(self, request):
        item_qs = self.get_all()
        search = request.GET.get("search", "")
        if search:
            item_qs = item_qs.filter(title__icontains=search)
        return self.render_section(
            request,
            section_name="todo-list-container",
            context={"todo_items": item_qs, "search": search},
        )

3) Wiring routes
-----------------

You can include the class's generated URL patterns into your `urlpatterns`:

.. code-block:: python

    from django.urls import path, include
    from myapp.views import TodoListDXBattery

    urlpatterns = [
        path("todo/", include((TodoListDXBattery.url_patterns(), "todo"), namespace="todo")),
    ]

This will register the routes declared via decorators (the path fragments are
relative to the include prefix).

4) Running the example
----------------------

The example project is bootstrapped so you can run the server and explore the
todo app. The todo `DXEndpointBattery` demonstrates list rendering, item
creation/editing, state toggles (complete/reopen) and deletion. The handlers
use the Django messaging framework to show feedback in the UI.

5) Extra notes
--------------

- The `INLINE_TEMPLATE` in the example shows patterns for nested `dx-include`
  usage and for actions that return either `render_section` or `render_empty`.
- The example templates under `sourcecode/src/djxi/templates/djxi` provide
  default message templates and HTMX includes that you can override in your
  project by placing templates with the same names in your project's template
  directories.

See the example code at `sourcecode/example/todo/views.py` and the templates in
`sourcecode/example/templates` for a full working illustration.