From d5139be4738919424a66c13843a6be8f4457ce99 Mon Sep 17 00:00:00 2001 From: rameel Date: Mon, 17 Aug 2026 19:25:32 +0500 Subject: [PATCH] Rename HTMX toolkit script API --- README.md | 54 ++++++------------- .../Pages/Shared/_Layout.cshtml | 2 +- samples/Ramstack.HtmxToolkit.Demo/Program.cs | 2 +- .../Builder/EndpointRouteBuilderExtensions.cs | 40 ++++---------- .../HtmlHelperExtensions.cs | 22 ++++---- 5 files changed, 38 insertions(+), 82 deletions(-) diff --git a/README.md b/README.md index 37d8cc5..4cd482c 100644 --- a/README.md +++ b/README.md @@ -16,14 +16,9 @@ Provides HTMX integration for ASP.NET Core applications. * [HtmxHeaderTagHelper](#htmxheadertaghelper) * [HtmxConfigTagHelper](#htmxconfigtaghelper) * [Response Handling Configuration](#response-handling-configuration) - * [Antiforgery Token](#antiforgery-token) + * [Toolkit Script](#toolkit-script) * [Supported Versions](#supported-versions) * [Contributions](#contributions) - * [Changelog](#changelog) - * [1.2.2](#122) - * [1.2.1](#121) - * [1.2.0](#120) - * [1.1.0](#110) * [License](#license) @@ -675,18 +670,18 @@ Alternatively, you can set the entire response handling configuration directly a }" /> ``` -## Antiforgery Token +## Toolkit Script -If you have enabled the generation of the **Antiforgery** token in the configuration -(`include-antiforgery-token="true"`), then you need to include a small JavaScript file -that will ensure this token is present in form parameters or headers -and refresh it in a timely manner. +The toolkit script provides antiforgery support and HTMX compatibility behavior. +If you have enabled **Antiforgery** token generation in the configuration +(`include-antiforgery-token="true"`), include it to ensure the token is present in form +parameters or headers and refreshed in a timely manner. -To do this, you can directly include the contents of the JavaScript file on the page: +To do this, you can directly include the contents of the script file on the page: ```html ``` @@ -695,7 +690,7 @@ you can pass the debug parameter with a value of `true`: ```html ``` @@ -710,7 +705,7 @@ Alternatively, you can register the corresponding endpoint for the script by cal ```csharp app.UseAuthorization(); ... -app.MapHtmxAntiforgeryScript(); +app.MapHtmxToolkitScript(); app.MapControllers(); ``` @@ -723,13 +718,13 @@ when the script content is modified. If you want to change the path to your own, specify this path in the parameter. ```csharp -app.MapHtmxAntiforgeryScript("/my-path"); +app.MapHtmxToolkitScript("/my-path"); ``` Now, include it on the page. ```html - + ``` Alternatively, to retrieve the debug version of the script, you can pass the `debug` parameter @@ -737,7 +732,7 @@ with a value of `true`, which instructs to include a query parameter `?debug` in The presence of this parameter determines the loading of the debug version: ```html - + ``` The `debug` parameter determines whether to load the minimized version (used by default) @@ -745,31 +740,14 @@ or the debug version of the script. ## Supported Versions -| | Version | -|------|------------| -| .NET | 6, 7, 8, 9 | +| | Version | +|------|----------------| +| .NET | 6, 7, 8, 9, 10 | ## Contributions Bug reports and contributions are welcome. -## Changelog - -### 1.2.2 -Explicitly pass `document` object to event listeners in `htmx-toolkit.js` to improve compatibility - -### 1.2.1 -Add `[DisallowNull]` attribute to `Reswap` property to disallow null input - -### 1.2.0 -* Add `AjaxContext` to align with the capabilities provided by htmx -* Add method overloads for `PushUrl` and `ReplaceUrl` that prevents URL changes (`PreventPushUrl` / `PreventReplaceUrl`) -* Add support `` element as a standalone HTML element - -### 1.1.0 -* Add overloads for IsHtmxRequest and IsHtmxBoosted methods enabling retrieval of htmx request headers -* Improve HtmxRequestAttribute - ## License This package is released as open source under the **MIT License**. See the [LICENSE](https://github.com/rameel/ramstack.htmxtoolkit/blob/main/LICENSE) file for more details. diff --git a/samples/Ramstack.HtmxToolkit.Demo/Pages/Shared/_Layout.cshtml b/samples/Ramstack.HtmxToolkit.Demo/Pages/Shared/_Layout.cshtml index d77b166..d98f437 100644 --- a/samples/Ramstack.HtmxToolkit.Demo/Pages/Shared/_Layout.cshtml +++ b/samples/Ramstack.HtmxToolkit.Demo/Pages/Shared/_Layout.cshtml @@ -52,7 +52,7 @@ - + diff --git a/samples/Ramstack.HtmxToolkit.Demo/Program.cs b/samples/Ramstack.HtmxToolkit.Demo/Program.cs index 9c757de..38b63f6 100644 --- a/samples/Ramstack.HtmxToolkit.Demo/Program.cs +++ b/samples/Ramstack.HtmxToolkit.Demo/Program.cs @@ -13,7 +13,7 @@ app.UseStaticFiles(); app.UseRouting(); -app.MapHtmxAntiforgeryScript(); +app.MapHtmxToolkitScript(); app.MapRazorPages(); app.Run(); diff --git a/src/Ramstack.HtmxToolkit/Builder/EndpointRouteBuilderExtensions.cs b/src/Ramstack.HtmxToolkit/Builder/EndpointRouteBuilderExtensions.cs index b617050..e0d7c12 100644 --- a/src/Ramstack.HtmxToolkit/Builder/EndpointRouteBuilderExtensions.cs +++ b/src/Ramstack.HtmxToolkit/Builder/EndpointRouteBuilderExtensions.cs @@ -16,44 +16,24 @@ public static class EndpointRouteBuilderExtensions internal static string AssetPath { get; private set; } = $"/htmxtoolkit/{HtmxAssets.Hash}"; /// - /// Maps a GET request to the default path for the htmx anti-forgery script. + /// Maps an endpoint that serves the HTMX toolkit script at the default path. /// - /// - /// Ensure to include the following script tag in your Layout.cshtml or Razor view: - /// - /// - /// or - /// - /// ]]> - /// - /// - /// The to add the route to. + /// The endpoint route builder. /// - /// An that can be used to further configure the endpoint. + /// The endpoint convention builder for the mapped script endpoint. /// - public static IEndpointConventionBuilder MapHtmxAntiforgeryScript(this IEndpointRouteBuilder builder) => - builder.MapHtmxAntiforgeryScript(AssetPath); + public static IEndpointConventionBuilder MapHtmxToolkitScript(this IEndpointRouteBuilder builder) => + builder.MapHtmxToolkitScript(AssetPath); /// - /// Maps a GET request to the specified path for the htmx anti-forgery script. + /// Maps an endpoint that serves the HTMX toolkit script at the specified path. /// - /// - /// Ensure to include the following script tag in your Layout.cshtml or Razor view: - /// - /// - /// or - /// - /// ]]> - /// - /// - /// The to add the route to. - /// The path to map the GET request to. + /// The endpoint route builder. + /// The path at which to serve the script. /// - /// An that can be used to further configure the endpoint. + /// The endpoint convention builder for the mapped script endpoint. /// - public static IEndpointConventionBuilder MapHtmxAntiforgeryScript(this IEndpointRouteBuilder builder, string path) + public static IEndpointConventionBuilder MapHtmxToolkitScript(this IEndpointRouteBuilder builder, string path) { if (path.Length == 0) throw new ArgumentException( diff --git a/src/Ramstack.HtmxToolkit/HtmlHelperExtensions.cs b/src/Ramstack.HtmxToolkit/HtmlHelperExtensions.cs index 9f09bcd..b100f0c 100644 --- a/src/Ramstack.HtmxToolkit/HtmlHelperExtensions.cs +++ b/src/Ramstack.HtmxToolkit/HtmlHelperExtensions.cs @@ -24,26 +24,24 @@ public static class HtmlHelperExtensions internal static HtmlString DebugPath { get; set; } = new(EndpointRouteBuilderExtensions.AssetPath + "?debug"); /// - /// Returns an HTML string containing the script for htmx to integrate with the anti-forgery feature of ASP.NET Core. + /// Returns the HTMX toolkit script content. /// - /// The instance that this method extends. - /// A boolean value indicating whether to use the debug version of the script. - /// Defaults to . + /// The HTML helper. + /// Whether to return the debug version of the script. /// - /// An HTML string of the script. + /// The HTMX toolkit script content. /// - public static IHtmlContent HtmxAntiforgeryScript(this IHtmlHelper _, bool debug = false) => + public static IHtmlContent HtmxToolkitScript(this IHtmlHelper _, bool debug = false) => debug ? s_debugScript : s_script; /// - /// Returns an HTML string of the path to the script to integrate with the anti-forgery feature of ASP.NET Core. + /// Returns the path to the HTMX toolkit script endpoint. /// - /// The instance that this method extends. - /// A boolean value indicating whether to use the debug version of the script. - /// Defaults to . + /// The HTML helper. + /// Whether to return the debug version of the script. /// - /// An HTML string of the path to the script. + /// The HTMX toolkit script endpoint path. /// - public static IHtmlContent HtmxAntiforgeryScriptPath(this IHtmlHelper _, bool debug = false) => + public static IHtmlContent HtmxToolkitScriptPath(this IHtmlHelper _, bool debug = false) => debug ? DebugPath : Path; }