From ece89c91b1e9a30c247175832230d6d5218c76b0 Mon Sep 17 00:00:00 2001 From: "Daniel J. Summers" Date: Sun, 28 Dec 2025 11:47:16 -0500 Subject: [PATCH] Update READMEs for release --- README.md | 6 +++++- src/Common/README.md | 2 +- src/Directory.Build.props | 18 ++++++++++-------- src/Htmx/README.md | 2 ++ src/ViewEngine.Htmx/README.md | 2 +- 5 files changed, 19 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 80a3423..112372e 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,8 @@ htmx uses attributes and HTTP headers to attain its interactivity; the libraries |---|---| |[![Nuget](https://img.shields.io/nuget/v/Giraffe.Htmx?style=plastic)](https://www.nuget.org/packages/Giraffe.Htmx/)|[![Nuget](https://img.shields.io/nuget/v/Giraffe.ViewEngine.Htmx?style=plastic)](https://www.nuget.org/packages/Giraffe.ViewEngine.Htmx/)| +Both of these packages will also install `Giraffe.Htmx.Common`, which has some common definitions and provides a local-to-your-project version of the htmx JavaScript _(as of v2.0.8)_. + ## Server Side (`Giraffe.Htmx`) In addition to the regular HTTP request payloads, htmx sets [one or more headers](https://htmx.org/docs/#request_headers) along with the request. Once `Giraffe.Htmx` is opened, these are available as properties on `HttpContext.Request.Headers`. These consist of the header name, translated to a .NET name (ex. `HX-Current-URL` becomes `HxCurrentUrl`), and a strongly-typed property based on the expected value of that header. Additionally, they are all exposed as `Option`s, as they may or may not be present for any given request. @@ -42,6 +44,8 @@ let theHandler : HttpHandler = Of note is that the `HX-Trigger` headers can take either one or more events. For a single event with no parameters, use `withHxTrigger`; for a single event with parameters, or multiple events, use `withHxTriggerMany`. Both these have `AfterSettle` and `AfterSwap` versions as well. +`HtmxScript.local` provides an `HtmlString` with a script tag to load the package-provided htmx library. This can be used in code, Razor templates, etc. (If you're using Giraffe.ViewEngine, see below.) + ## View Engine (`Giraffe.ViewEngine.Htmx`) As htmx uses [attributes](https://htmx.org/docs/#attributes) to extend HTML, the primary part of this library defines attributes that can be used within Giraffe views. Simply open `Giraffe.ViewEngine.Htmx`, and these attributes, along with support modules, will be visible. @@ -66,7 +70,7 @@ let shiftClick = ] ``` -If you want to load htmx from unpkg, `Htmx.Script.minified` or `Htmx.Script.unminified` can be used to load the script in your HTML trees. +If you want to use the package-provided htmx library, `Htmx.Script.local` will create the `script` tag for you. To load htmx from jsDelivr, `Htmx.Script.cdnMinified` or `Htmx.Script.cdnUnminified` can be used to load the script in your HTML trees. In this case, if you are using a Content Security Policy (CSP) header, `cdn.jsdelivr.net` will need to be added to the `script-src` list. ## Feedback / Help diff --git a/src/Common/README.md b/src/Common/README.md index 6994367..9a2cd15 100644 --- a/src/Common/README.md +++ b/src/Common/README.md @@ -1,5 +1,5 @@ ## Giraffe.Htmx.Common -This package contains common code shared between [`Giraffe.Htmx`](https://www.nuget.org/packages/Giraffe.Htmx) and [`Giraffe.ViewEngine.Htmx`](https://www.nuget.org/packages/Giraffe.ViewEngine.Htmx), and will be automatically installed when you install either one. +This package contains common code shared between [`Giraffe.Htmx`](https://www.nuget.org/packages/Giraffe.Htmx) and [`Giraffe.ViewEngine.Htmx`](https://www.nuget.org/packages/Giraffe.ViewEngine.Htmx), and will be automatically installed when you install either one. It also contains htmx as a static web asset, allowing it to be loaded from your local (or published) project. **htmx version: 2.0.8** diff --git a/src/Directory.Build.props b/src/Directory.Build.props index 58015d0..39a10a0 100644 --- a/src/Directory.Build.props +++ b/src/Directory.Build.props @@ -1,15 +1,17 @@  - net8.0;net9.0 - 2.0.6 + net8.0;net9.0;net10.0 + 2.0.8 true - - All packages now have full XML documentation -- Adds HxSync module and attribute helper to view engine -- Updates script tags to pull htmx 2.0.6 (no header or attribute changes) -- Drops .NET 6 support - -NOTE: The CDN for htmx changed from unpkg.com to cdn.jsdelivr.net; sites with Content-Security-Policy headers will want to update their allowed domains accordingly + - Adds package-provided script (available via Giraffe.Htmx.Common); use app.MapStaticAssets() for publish support, use builder.UseStaticWebAssets() for non-development/non-published execution +- [View Engine] Deprecates Script.minified and Script.unminified (use Script.cdnMinified and Script.cdnUnminified instead) +- Updates script tags to pull htmx 2.0.8 (no header or attribute changes) +- Adds .NET 10 support + +See full release notes, including more info about the package-provided script, at https://git.bitbadger.solutions/bit-badger/Giraffe.Htmx/releases/tag/v2.0.8 + +NOTE: As of 2.0.6, the CDN for htmx changed from unpkg.com to cdn.jsdelivr.net; sites with Content-Security-Policy headers will want to update their allowed script-src domains accordingly danieljsummers Bit Badger Solutions diff --git a/src/Htmx/README.md b/src/Htmx/README.md index e7f8466..07b002d 100644 --- a/src/Htmx/README.md +++ b/src/Htmx/README.md @@ -34,6 +34,8 @@ let myHandler : HttpHander = The `HxSwap` module has constants to use for the `HX-Reswap` header. These may be extended with settle, show, and other qualifiers; see the htmx documentation for the `hx-swap` attribute for more information. +To load the package-provided htmx library without using Giraffe.ViewEngine, use `HtmxScript.local`. + ### Learn The naming conventions of this library were selected to mirror those provided by htmx. The header properties become `Hx*` on the `ctx.Request.Headers` object, and the response handlers are `withHx*` based on the header being set. The only part that does not line up is `withHxTrigger*` and `withHxTriggerMany`; the former set work with a single string (to trigger a single event with no arguments), while the latter set supports both arguments and multiple events. \ No newline at end of file diff --git a/src/ViewEngine.Htmx/README.md b/src/ViewEngine.Htmx/README.md index 22dfe7f..1ed050f 100644 --- a/src/ViewEngine.Htmx/README.md +++ b/src/ViewEngine.Htmx/README.md @@ -29,7 +29,7 @@ Support modules include: - `HxTrigger` - `HxVals` -There are two `XmlNode`s that will load the htmx script from jsdelivr; `Htmx.Script.minified` loads the minified version, and `Htmx.Script.unminified` loads the unminified version (useful for debugging). +`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). 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).