243 lines
9.0 KiB
Markdown
243 lines
9.0 KiB
Markdown
# 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
|