Giraffe.ViewEngine.Htmx 4.0.0

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

1. Install the package.
2. Prior to using the attribute or support modules, open Giraffe.ViewEngine.Htmx.
3. If the client is using the htmax bundle, also open 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, replaces HxRequest)
• HxEncoding
• HxHeaders
• HxSwap (requires open Giraffe.Htmx)
• HxTrigger
• HxVals

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:

• _hxBoost implies true; use _hxNoBoost to set it to false.
• _hxSwapWithTransition renders the standard hx-swap attribute and appends transition:true to 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:

• HxConfig has a Configure function, which takes a list of strings; the other functions in the module allow for configuring the request.

HxConfig.Configure [ HxRequest.Timeout 500 ] |> _hxConfig 

• HxTrigger is (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