Added docs
This commit was merged in pull request #1.
This commit is contained in:
@@ -0,0 +1,242 @@
|
||||
# Form Validation
|
||||
|
||||
htmx-powered server-side validation that provides real-time per-field feedback on blur and full-form validation on submit — all without Blazor interactivity.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Browser │
|
||||
│ │
|
||||
│ ┌─────────────┐ blur ┌──────────────────────────┐ │
|
||||
│ │ <TextInput> │ ──────► │ htmx POST /validate │ │
|
||||
│ └─────────────┘ │ { _field: "email", │ │
|
||||
│ │ email: "bad" } │ │
|
||||
│ └──────────┬───────────────┘ │
|
||||
│ │ │
|
||||
│ ┌─────────────────┐ ◄──────────┘ │
|
||||
│ │ <p data-field- │ HTML fragment: │
|
||||
│ │ error="email"> │ <p class="text-destructive"> │
|
||||
│ │ swapped by │ Please enter a valid email. │
|
||||
│ │ htmx │ </p> │
|
||||
│ └─────────────────┘ │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Server (Minimal API) │
|
||||
│ │
|
||||
│ FormValidator.ValidateField("email", "bad") │
|
||||
│ → "Please enter a valid email address." │
|
||||
│ │
|
||||
│ HtmxFormValidationRenderer.FieldErrorFragment(...) │
|
||||
│ → HTML <p> element with error text │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create a Validator
|
||||
|
||||
Define your validation rules by extending `FormValidator` and calling `RuleFor()` in the constructor:
|
||||
|
||||
```csharp
|
||||
using Enciphered.Blazor.UIComponents.Validation;
|
||||
|
||||
public class ContactFormValidator : FormValidator
|
||||
{
|
||||
public ContactFormValidator()
|
||||
{
|
||||
RuleFor("name",
|
||||
displayName: "Name",
|
||||
required: true,
|
||||
minLength: 2);
|
||||
|
||||
RuleFor("email",
|
||||
displayName: "Email",
|
||||
required: true,
|
||||
pattern: @".+@.+\..+",
|
||||
message: "Please enter a valid email address.");
|
||||
|
||||
RuleFor("password",
|
||||
displayName: "Password",
|
||||
required: true,
|
||||
minLength: 6);
|
||||
|
||||
RuleFor("age",
|
||||
displayName: "Age",
|
||||
min: 0,
|
||||
max: 150);
|
||||
|
||||
RuleFor("birthdate",
|
||||
displayName: "Birth Date",
|
||||
custom: value => !DateOnly.TryParse(value, out _)
|
||||
? "Please enter a valid date."
|
||||
: null);
|
||||
|
||||
RuleFor("preferredtime",
|
||||
displayName: "Preferred Time",
|
||||
custom: value => !TimeOnly.TryParse(value, out _)
|
||||
? "Please enter a valid time."
|
||||
: null);
|
||||
|
||||
RuleFor("appointment",
|
||||
displayName: "Appointment",
|
||||
custom: value => !DateTime.TryParse(value, out _)
|
||||
? "Please enter a valid date and time."
|
||||
: null);
|
||||
|
||||
RuleFor("confirmation",
|
||||
displayName: "Confirmation",
|
||||
required: true,
|
||||
custom: value => value != "CONFIRM"
|
||||
? "You must type CONFIRM to proceed."
|
||||
: null);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Register Validation Endpoints
|
||||
|
||||
In `Program.cs`, call `MapFormValidation<T>()`:
|
||||
|
||||
```csharp
|
||||
app.MapFormValidation<ContactFormValidator>("/api/forms/contact");
|
||||
```
|
||||
|
||||
This registers two endpoints:
|
||||
|
||||
| Endpoint | Method | Purpose |
|
||||
|---|---|---|
|
||||
| `POST /api/forms/contact/validate` | Per-field | Validates a single field on blur |
|
||||
| `POST /api/forms/contact/submit` | Full form | Validates all fields on submit |
|
||||
|
||||
Both endpoints have antiforgery disabled (via `.DisableAntiforgery()`) since htmx sends form data directly.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Build the Form
|
||||
|
||||
Use `HtmxForm`, `FormField`, and input components:
|
||||
|
||||
```razor
|
||||
<HtmxForm Endpoint="/api/forms/contact">
|
||||
<FormField Label="Full Name" For="name">
|
||||
<TextInput Id="name" Name="name" Placeholder="Jane Doe" />
|
||||
</FormField>
|
||||
|
||||
<FormField Label="Email" For="email">
|
||||
<TextInput Id="email" Name="email" Type="email" Placeholder="jane@example.com" />
|
||||
</FormField>
|
||||
|
||||
<FormField Label="Password" For="password">
|
||||
<TextInput Id="password" Name="password" Type="password" />
|
||||
</FormField>
|
||||
|
||||
<FormField Label="Age" For="age">
|
||||
<NumberInput Id="age" Name="age" Min="0" Max="150" />
|
||||
</FormField>
|
||||
|
||||
<FormField Label="Birth Date" For="birthdate">
|
||||
<DateInput Id="birthdate" Name="birthdate" />
|
||||
</FormField>
|
||||
|
||||
<div class="flex gap-2 pt-2">
|
||||
<Button Type="submit">Submit</Button>
|
||||
<Button Type="reset" Variant="@ButtonVariant.Outline">Reset</Button>
|
||||
</div>
|
||||
</HtmxForm>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## RuleFor API Reference
|
||||
|
||||
```csharp
|
||||
protected void RuleFor(
|
||||
string field, // Form field name (must match the input's Name)
|
||||
string? displayName, // Human-readable label (auto-generated from field if omitted)
|
||||
bool required, // Whether the field is required
|
||||
int? minLength, // Minimum string length
|
||||
int? maxLength, // Maximum string length
|
||||
string? pattern, // Regex pattern for format validation
|
||||
double? min, // Minimum numeric value
|
||||
double? max, // Maximum numeric value
|
||||
string? message, // Custom error message for pattern failures
|
||||
Func<string, string?>? custom // Custom validation function
|
||||
);
|
||||
```
|
||||
|
||||
### Validation Order
|
||||
|
||||
Rules are evaluated in this order — the first failure stops evaluation:
|
||||
|
||||
1. **Required** — empty/whitespace check
|
||||
2. **Empty skip** — if not required and value is empty, the field passes (skips remaining rules)
|
||||
3. **MinLength** — minimum character count
|
||||
4. **MaxLength** — maximum character count
|
||||
5. **Pattern** — regex match (uses `message` if provided, else default format error)
|
||||
6. **Min/Max** — numeric range (attempts to parse as `double`)
|
||||
7. **Custom** — arbitrary validation function returning an error string or `null`
|
||||
|
||||
### Custom Validators
|
||||
|
||||
The `custom` parameter accepts a `Func<string, string?>` — receive the trimmed value, return an error message or `null`:
|
||||
|
||||
```csharp
|
||||
RuleFor("confirmation",
|
||||
required: true,
|
||||
custom: value => value != "CONFIRM"
|
||||
? "You must type CONFIRM to proceed."
|
||||
: null);
|
||||
```
|
||||
|
||||
For date/time/datetime fields, use `TryParse`:
|
||||
|
||||
```csharp
|
||||
RuleFor("birthdate",
|
||||
custom: value => !DateOnly.TryParse(value, out _)
|
||||
? "Please enter a valid date."
|
||||
: null);
|
||||
```
|
||||
|
||||
> **Note**: Custom validators only run when the value is non-empty. If the field is not required and left blank, the custom function is never called.
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### On Blur (Per-Field)
|
||||
|
||||
1. `InputBase<T>` auto-injects htmx attributes when inside `HtmxForm` + `FormField`
|
||||
2. When the user leaves an input, htmx fires `POST /validate` with the field name and value
|
||||
3. The server calls `FormValidator.ValidateField()` and returns an HTML `<p>` fragment
|
||||
4. htmx replaces the existing `<p data-field-error="...">` element with the response
|
||||
|
||||
### On Submit (Full Form)
|
||||
|
||||
1. `HtmxForm` adds `hx-post="/submit"` to the `<form>` element
|
||||
2. htmx sends all form fields
|
||||
3. The server calls `FormValidator.ValidateAll()` and returns:
|
||||
- **If errors**: OOB (out-of-band) swap fragments for each field's error element
|
||||
- **If valid**: Success message + OOB swaps to clear all errors
|
||||
|
||||
### HtmxForm Parameters
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `Endpoint` | `string` | **required** | Base path (e.g. `/api/forms/contact`) |
|
||||
| `ResultId` | `string` | `"form-result"` | ID of the result div for success/error messages |
|
||||
| `Class` | `string?` | — | Additional CSS classes on the `<form>` |
|
||||
|
||||
### Form Reset
|
||||
|
||||
Clicking a `<Button Type="reset">` triggers the browser's native form reset. The `forms.js` module listens for the `reset` event and:
|
||||
- Clears all visible input values
|
||||
- Hides all `[data-field-error]` elements
|
||||
- Hides the result div
|
||||
- Resets date/time trigger button text to their placeholders
|
||||
Reference in New Issue
Block a user