3.8 KiB
Giraffe.ViewEngine.Htmx
This package enables htmx support within the Giraffe view engine.
htmx version: 4.0.0
Upgrading from v2.x: see the migration guide for changes, which are plentiful. htmx switches from XMLHTTPRequest to fetch, and many changes are related to the new event cycle.
Inheritance is now explicit; to have an attribute's value inherited to its children, wrap the attribute in hxInherited (ex. hxInherited (_hxTarget "#main")). Values can be appended to inherited values as well using the hxAppend modifier.
Several constructs have been removed in this release. If you encounter compile errors, install version 4.0.0-beta5; it will instead flag these with warnings and suggestions on how to mitigate them. Once the warnings are gone, you can reinstall this version.
Setup
- Install the package.
- Prior to using the attribute or support modules,
open Giraffe.ViewEngine.Htmx. - If the client is using the
htmaxbundle, alsoopen Giraffe.ViewEngine.Htmax.
Use
Following Giraffe View Engine's lead, there are a set of attribute functions for htmx; for many of the attributes, there are also helper modules to assist with typing the values. The example below utilizes both:
let autoload =
div [ _hxGet "/this/data"; _hxTrigger HxTrigger.Load ] [ str "Loading..." ]
Support modules include:
HxConfig(new in v4, replacesHxRequest)HxEncodingHxHeadersHxSwap(requiresopen Giraffe.Htmx)HxTriggerHxVals
Htmx.Script.local creates an XmlNode to load the package-provided htmx library. There are also two XmlNodes that will load the htmx script from jsdelivr; Htmx.Script.cdnMinified loads the minified version, and Htmx.Script.cdnUnminified loads the unminified version (useful for debugging). htmx v4 also distributes a "max" bundle which contains some common extensions; these are available with the same names under Htmx.Script.Max.
NOTE: When using the CDN nodes and a Content Security Policy (CSP) header, cdn.jsdelivr.net needs to be listed as an allowable script-src.
This also supports fragment rendering, providing the flexibility to render an entire template, or only a portion of it (based on the element's id attribute).
Learn
htmx's attributes and these attribute functions map one-to-one. There are two exceptions:
_hxBoostimpliestrue; use_hxNoBoostto set it tofalse._hxSwapWithTransitionrenders the standardhx-swapattribute and appendstransition:trueto the specified swap value.
The htmx hx-on attribute supports multiple events if they are separated with a newline (\n) character. The value provided to this attribute will be attribute-escaped, but in testing, it was interpreted correctly.
The support modules contain named properties for known values (as illustrated with HxTrigger.Load above). A few of the modules are more than collections of names, though:
HxConfighas aConfigurefunction, which takes a list of strings; the other functions in the module allow for configuring the request.
HxConfig.Configure [ HxRequest.Timeout 500 ] |> _hxConfig
HxTriggeris (by far) the most complex of these modules. Most uses won't need that complexity; however, complex triggers can be defined by piping into or composing with other functions. For example, to define an event that responds to a shift-click anywhere on the document, with a delay of 3 seconds before firing:
HxTrigger.Click
|> HxTrigger.Filter.Shift
|> HxTrigger.FromDocument
|> HxTrigger.Delay "3s"
|> _hxTrigger
// or
(HxTrigger.Filter.Shift >> HxTrigger.FromDocument >> HxTrigger.Delay "3s") HxTrigger.Click
|> _hxTrigger