Add NuGet READMEs

This commit is contained in:
Daniel J. Summers 2021-11-11 18:40:22 -05:00
parent dc06b06b1f
commit 5906f3b295
5 changed files with 88 additions and 2 deletions

View File

@ -1,8 +1,8 @@
<?xml version="1.0" encoding="utf-8" standalone="no"?> <?xml version="1.0" encoding="utf-8" standalone="no"?>
<Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003"> <Project ToolsVersion="15.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<PropertyGroup> <PropertyGroup>
<VersionPrefix>0.9.1</VersionPrefix> <VersionPrefix>0.9.2</VersionPrefix>
<PackageReleaseNotes>Initial NuGet release</PackageReleaseNotes> <PackageReleaseNotes>Complete view engine modules; add READMEs</PackageReleaseNotes>
<Authors>danieljsummers</Authors> <Authors>danieljsummers</Authors>
<Company>Bit Badger Solutions</Company> <Company>Bit Badger Solutions</Company>
<PackageProjectUrl>https://github.com/bit-badger/Giraffe.Htmx</PackageProjectUrl> <PackageProjectUrl>https://github.com/bit-badger/Giraffe.Htmx</PackageProjectUrl>

View File

@ -4,10 +4,12 @@
<TargetFramework>net6.0</TargetFramework> <TargetFramework>net6.0</TargetFramework>
<GenerateDocumentationFile>true</GenerateDocumentationFile> <GenerateDocumentationFile>true</GenerateDocumentationFile>
<Description>htmx header extensions and helpers for Giraffe</Description> <Description>htmx header extensions and helpers for Giraffe</Description>
<PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup> </PropertyGroup>
<ItemGroup> <ItemGroup>
<Compile Include="Htmx.fs" /> <Compile Include="Htmx.fs" />
<None Include="README.md" Pack="true" PackagePath="\" />
</ItemGroup> </ItemGroup>
<ItemGroup> <ItemGroup>

33
src/Htmx/README.md Normal file
View File

@ -0,0 +1,33 @@
## Giraffe.Htmx
This package enables server-side support for [htmx](https://htmx.org) within [Giraffe](https://giraffe.wiki) and ASP.NET's `HttpContext`.
### Setup
1. Install the package.
2. Prior to using the request header extension properties or the header-setting `HttpHandler`s, `open Giraffe.Htmx`.
### Use
To obtain a request header, using the `IHeaderDictionary` extension properties:
```fsharp
let myHandler : HttpHander =
fun next ctx ->
match ctx.HxPrompt with
| Some prompt -> ... // do something with the text the user provided
| None -> ... // no text provided
```
To set a response header:
```fsharp
let myHandler : HttpHander =
fun next ctx ->
// some meaningful work
withHxPush "/some/new/url" >=> [other handlers]
```
### 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.

View File

@ -4,10 +4,12 @@
<TargetFramework>net6.0</TargetFramework> <TargetFramework>net6.0</TargetFramework>
<GenerateDocumentationFile>true</GenerateDocumentationFile> <GenerateDocumentationFile>true</GenerateDocumentationFile>
<Description>Extensions to Giraffe View Engine to support htmx attributes and their values</Description> <Description>Extensions to Giraffe View Engine to support htmx attributes and their values</Description>
<PackageReadmeFile>README.md</PackageReadmeFile>
</PropertyGroup> </PropertyGroup>
<ItemGroup> <ItemGroup>
<Compile Include="Htmx.fs" /> <Compile Include="Htmx.fs" />
<None Include="README.md" Pack="true" PackagePath="\" />
</ItemGroup> </ItemGroup>
<ItemGroup> <ItemGroup>

View File

@ -0,0 +1,49 @@
## Giraffe.ViewEngine.Htmx
This package enables [htmx](https://htmx.org) support within the [Giraffe](https://giraffe.wiki) view engine.
### Setup
1. Install the package.
2. Prior to using the attribute or support modules, `open Giraffe.ViewEngine.Htmx`.
### 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:
- `HxEncoding`
- `HxHeaders`
- `HxParams`
- `HxRequest`
- `HxSwap`
- `HxTrigger`
- `HxVals`
### Learn
htmx's attributes and these attribute functions map one-to-one. The lone exception is `_hxBoost`, which implies `true`; use `_hxNoBoost` to set it to `false`. 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:
- `HxRequest` has a `Configure` function, which takes a list of strings; the other functions in the module allow for configuring the request.
```fsharp
HxRequest.Configure [ HxRequest.Timeout 500 ] |> _hxRequest
```
- `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
```