## Giraffe.ViewEngine.Htmx

This package enables [htmx](https://htmx.org) support within the [Giraffe](https://giraffe.wiki) view engine.

**htmx version: 4.0.0-beta5**

_Upgrading from v2.x: see [the migration guide](https://four.htmx.org/docs/get-started/migration) 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 marked obsolete in this release, and will be removed from the first production release of v4. With the exception of `_hxDisable`, though (which now functions as the deprecated `_hxDisabledElt` did), this should not introduce compile errors. Rather, this package will raise warnings for deprecated constructs, along with suggestions of what to use instead._

### Setup

1. Install the package.
1. Prior to using the attribute or support modules, `open Giraffe.ViewEngine.Htmx`.
1. 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:

```fsharp
let autoload =
    div [ _hxGet "/this/data"; _hxTrigger HxTrigger.Load ] [ str "Loading..." ]
```

Support modules include:
- `HxConfig` _(new in v4)_
- `HxEncoding`
- `HxHeaders`
- ~~`HxParams`~~ _(removed in v4)_
- ~~`HxRequest`~~ _(renamed to `HxConfig`)_
- `HxSwap` (requires `open Giraffe.Htmx`)
- `HxTrigger`
- `HxVals`

`Htmx.Script.local` creates an `XmlNode` to load the package-provided htmx library. There are also two `XmlNode`s 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](https://bitbadger.solutions/blog/2022/fragment-rendering-in-giraffe-view-engine.html), 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.

```fsharp
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:

```fsharp
HxTrigger.Click
|> HxTrigger.Filter.Shift
|> HxTrigger.FromDocument
|> HxTrigger.Delay "3s"
|> _hxTrigger

// or

(HxTrigger.Filter.Shift >> HxTrigger.FromDocument >> HxTrigger.Delay "3s") HxTrigger.Click
|> _hxTrigger
```