Debian Codegraph @

docs/usage/htmx.rst

raw
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 )