| 1 |
HTMX |
| 2 |
==== |
| 3 |
|
| 4 |
Litestar `HTMX <https://htmx.org>`_ integration. |
| 5 |
|
| 6 |
HTMX is a JavaScript library that gives you access to AJAX, CSS Transitions, WebSockets and Server Sent Events directly in HTML, using attributes, so you can build modern user interfaces with the simplicity and power of hypertext. |
| 7 |
|
| 8 |
This section assumes that you have prior knowledge of HTMX. |
| 9 |
If you want to learn HTMX, we recommend consulting their `official tutorial <https://htmx.org/docs>`_. |
| 10 |
|
| 11 |
HTMXPlugin |
| 12 |
------------ |
| 13 |
|
| 14 |
a Litestar plugin ``HTMXPlugin`` is available to easily configure the default request class for all Litestar routes. |
| 15 |
|
| 16 |
.. code-block:: python |
| 17 |
|
| 18 |
from litestar.plugins.htmx import HTMXPlugin |
| 19 |
from litestar import Litestar |
| 20 |
|
| 21 |
from litestar.contrib.jinja import JinjaTemplateEngine |
| 22 |
from litestar.template.config import TemplateConfig |
| 23 |
|
| 24 |
from pathlib import Path |
| 25 |
|
| 26 |
app = Litestar( |
| 27 |
route_handlers=[get_form], |
| 28 |
debug=True, |
| 29 |
plugins=[HTMXPlugin()], |
| 30 |
template_config=TemplateConfig( |
| 31 |
directory=Path("litestar_htmx/templates"), |
| 32 |
engine=JinjaTemplateEngine, |
| 33 |
), |
| 34 |
) |
| 35 |
|
| 36 |
See :class:`~litestar.plugins.htmx.HTMXDetails` for a full list of |
| 37 |
available properties. |
| 38 |
|
| 39 |
HTMXRequest |
| 40 |
------------ |
| 41 |
|
| 42 |
A special :class:`~litestar.connection.Request` class, providing interaction with the |
| 43 |
HTMX client. You can configure this globally by using the ``HTMXPlugin`` or by setting the `request_class` setting on any route, controller, router, or application. |
| 44 |
|
| 45 |
.. code-block:: python |
| 46 |
|
| 47 |
from litestar.plugins.htmx import HTMXRequest, HTMXTemplate |
| 48 |
from litestar import get, Litestar |
| 49 |
from litestar.response import Template |
| 50 |
|
| 51 |
from litestar.contrib.jinja import JinjaTemplateEngine |
| 52 |
from litestar.template.config import TemplateConfig |
| 53 |
|
| 54 |
from pathlib import Path |
| 55 |
|
| 56 |
|
| 57 |
@get(path="/form") |
| 58 |
def get_form(request: HTMXRequest) -> Template: |
| 59 |
if request.htmx: # if request has "HX-Request" header, then |
| 60 |
print(request.htmx) # HTMXDetails instance |
| 61 |
print(request.htmx.current_url) |
| 62 |
return HTMXTemplate(template_name="partial.html", context=context, push_url="/form") |
| 63 |
|
| 64 |
|
| 65 |
app = Litestar( |
| 66 |
route_handlers=[get_form], |
| 67 |
debug=True, |
| 68 |
request_class=HTMXRequest, |
| 69 |
template_config=TemplateConfig( |
| 70 |
directory=Path("litestar_htmx/templates"), |
| 71 |
engine=JinjaTemplateEngine, |
| 72 |
), |
| 73 |
) |
| 74 |
|
| 75 |
See :class:`~litestar.plugins.htmx.HTMXDetails` for a full list of |
| 76 |
available properties. |
| 77 |
|
| 78 |
|
| 79 |
HTMX Response Classes |
| 80 |
--------------------- |
| 81 |
|
| 82 |
|
| 83 |
HTMXTemplate Response Classes |
| 84 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 85 |
|
| 86 |
The most common use-case for HTMX to render an html page or html snippet. Litestar makes this easy by providing |
| 87 |
an :class:`~litestar.plugins.htmx.HTMXTemplate` response: |
| 88 |
|
| 89 |
.. code-block:: python |
| 90 |
|
| 91 |
from litestar.plugins.htmx import HTMXTemplate |
| 92 |
from litestar.response import Template |
| 93 |
|
| 94 |
|
| 95 |
@get(path="/form") |
| 96 |
def get_form( |
| 97 |
request: HTMXRequest, |
| 98 |
) -> Template: # Return type is Template and not HTMXTemplate. |
| 99 |
... |
| 100 |
return HTMXTemplate( |
| 101 |
template_name="partial.html", |
| 102 |
context=context, |
| 103 |
# Optional parameters |
| 104 |
push_url="/form", # update browser history |
| 105 |
re_swap="outerHTML", # change swapping method |
| 106 |
re_target="#new-target", # change target element |
| 107 |
trigger_event="showMessage", # trigger event name |
| 108 |
params={"alert": "Confirm your Choice."}, # parameter to pass to the event |
| 109 |
after="receive", # when to trigger event, |
| 110 |
# possible values 'receive', 'settle', and 'swap' |
| 111 |
) |
| 112 |
|
| 113 |
.. note:: |
| 114 |
- Return type is litestar's ``Template`` and not ``HTMXTemplate``. |
| 115 |
- ``trigger_event``, ``params``, and ``after parameters`` are linked to one another. |
| 116 |
- If you are triggering an event then ``after`` is required and it must be one of ``receive``, ``settle``, or ``swap``. |
| 117 |
|
| 118 |
HTMX provides two types of responses - one that doesn't allow changes to the DOM and one that does. |
| 119 |
Litestar supports both of these: |
| 120 |
|
| 121 |
1 - Responses that don't make any changes to DOM |
| 122 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 123 |
|
| 124 |
Use :class:`~litestar.plugins.htmx.HXStopPolling` to stop polling for a response. |
| 125 |
|
| 126 |
.. code-block:: python |
| 127 |
|
| 128 |
@get("/") |
| 129 |
def handler() -> HXStopPolling: |
| 130 |
... |
| 131 |
return HXStopPolling() |
| 132 |
|
| 133 |
Use :class:`~litestar.plugins.htmx.ClientRedirect` to redirect with a page reload. |
| 134 |
|
| 135 |
.. code-block:: python |
| 136 |
|
| 137 |
@get("/") |
| 138 |
def handler() -> ClientRedirect: |
| 139 |
... |
| 140 |
return ClientRedirect(redirect_to="/contact-us") |
| 141 |
|
| 142 |
Use :class:`~litestar.plugins.htmx.ClientRefresh` to force a full page refresh. |
| 143 |
|
| 144 |
.. code-block:: python |
| 145 |
|
| 146 |
@get("/") |
| 147 |
def handler() -> ClientRefresh: |
| 148 |
... |
| 149 |
return ClientRefresh() |
| 150 |
|
| 151 |
2 - Responses that may change DOM |
| 152 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 153 |
|
| 154 |
Use :class:`~litestar.plugins.htmx.HXLocation` to redirect to a new location without page reload. |
| 155 |
|
| 156 |
.. note:: This class provides the ability to change ``target``, ``swapping`` method, the sent ``values``, and the ``headers``. |
| 157 |
|
| 158 |
.. code-block:: python |
| 159 |
|
| 160 |
@get("/about") |
| 161 |
def handler() -> HXLocation: |
| 162 |
... |
| 163 |
return HXLocation( |
| 164 |
redirect_to="/contact-us", |
| 165 |
# Optional parameters |
| 166 |
source, # the source element of the request. |
| 167 |
event, # an event that "triggered" the request. |
| 168 |
target="#target", # element id to target to. |
| 169 |
swap="outerHTML", # swapping method to use. |
| 170 |
hx_headers={"attr": "val"}, # headers to pass to HTMX. |
| 171 |
values={"val": "one"}, |
| 172 |
) # values to submit with response. |
| 173 |
|
| 174 |
Use :class:`~litestar.plugins.htmx.PushUrl` to carry a response and push a url to the browser, optionally updating the ``history`` stack. |
| 175 |
|
| 176 |
.. note:: If the value for ``push_url`` is set to ``False`` it will prevent updating browser history. |
| 177 |
|
| 178 |
.. code-block:: python |
| 179 |
|
| 180 |
@get("/about") |
| 181 |
def handler() -> PushUrl: |
| 182 |
... |
| 183 |
return PushUrl(content="Success!", push_url="/about") |
| 184 |
|
| 185 |
Use :class:`~litestar.plugins.htmx.ReplaceUrl` to carry a response and replace the url in the browser's ``location`` bar. |
| 186 |
|
| 187 |
.. note:: If the value to ``replace_url`` is set to ``False`` it will prevent updating the browser's location. |
| 188 |
|
| 189 |
.. code-block:: python |
| 190 |
|
| 191 |
@get("/contact-us") |
| 192 |
def handler() -> ReplaceUrl: |
| 193 |
... |
| 194 |
return ReplaceUrl(content="Success!", replace_url="/contact-us") |
| 195 |
|
| 196 |
Use :class:`~litestar.plugins.htmx.Reswap` to carry a response with a possible swap. |
| 197 |
|
| 198 |
.. code-block:: python |
| 199 |
|
| 200 |
@get("/contact-us") |
| 201 |
def handler() -> Reswap: |
| 202 |
... |
| 203 |
return Reswap(content="Success!", method="beforebegin") |
| 204 |
|
| 205 |
Use :class:`~litestar.plugins.htmx.Retarget` to carry a response and change the target element. |
| 206 |
|
| 207 |
.. code-block:: python |
| 208 |
|
| 209 |
@get("/contact-us") |
| 210 |
def handler() -> Retarget: |
| 211 |
... |
| 212 |
return Retarget(content="Success!", target="#new-target") |
| 213 |
|
| 214 |
Use :class:`~litestar.plugins.htmx.TriggerEvent` to carry a response and trigger an event. |
| 215 |
|
| 216 |
.. code-block:: python |
| 217 |
|
| 218 |
@get("/contact-us") |
| 219 |
def handler() -> TriggerEvent: |
| 220 |
... |
| 221 |
return TriggerEvent( |
| 222 |
content="Success!", |
| 223 |
name="showMessage", |
| 224 |
params={"attr": "value"}, |
| 225 |
after="receive", # possible values 'receive', 'settle', and 'swap' |
| 226 |
) |