@@ -0,0 +1,252 @@
|
||||
# Dialog
|
||||
|
||||
A modal dialog using the native HTML `<dialog>` element. Content is organized into optional title, description, body, and footer sections. Open/close is handled by client-side JS via delegated click events on `data-dialog-open` and `data-dialog-close` attributes.
|
||||
|
||||
---
|
||||
|
||||
## HTML structure
|
||||
|
||||
```
|
||||
dialog[id, class=...]
|
||||
div.dialog-panel.relative.bg-background.p-6.rounded-lg.shadow-xl.w-full.max-w-md...
|
||||
button.absolute.top-4.right-4[data-dialog-close={id}] ← × close button
|
||||
h2.text-lg.font-semibold ← title (omitted when empty)
|
||||
p.text-sm.text-muted-foreground.mt-1 ← description (omitted when empty)
|
||||
div.mt-4 ← body content
|
||||
{content}
|
||||
div.mt-6.flex.justify-end.gap-2 ← footer (omitted when empty)
|
||||
{footer}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CSS mechanics
|
||||
|
||||
| Class | Effect |
|
||||
|---|---|
|
||||
| `dialog::backdrop` (in `input.css`) | Semi-transparent black overlay behind the dialog |
|
||||
| `animate-in fade-in-0 zoom-in-95` | CSS entry animation when dialog opens |
|
||||
| `max-w-md w-full` | Responsive: full width on small screens, capped at `md` |
|
||||
| `overflow-y-auto max-h-[90vh]` | Scrollable body for tall content |
|
||||
|
||||
---
|
||||
|
||||
## JavaScript (delegated clicks in `components.js`)
|
||||
|
||||
Set up once on `document` and works for all dialogs on the page, including those HTMX-swapped in.
|
||||
|
||||
### Open
|
||||
Any element with `data-dialog-open="myDialogId"` calls `document.getElementById('myDialogId').showModal()`.
|
||||
|
||||
### Close
|
||||
Any element with `data-dialog-close="myDialogId"` calls `document.getElementById('myDialogId').close()`.
|
||||
|
||||
The `×` close button inside the dialog panel already has `data-dialog-close` set to the dialog's id.
|
||||
|
||||
Clicking the `::backdrop` (outside the panel) also closes the dialog — the click handler checks whether the click target is the `<dialog>` element itself.
|
||||
|
||||
---
|
||||
|
||||
## Constructor signature
|
||||
|
||||
```csharp
|
||||
public Dialog(
|
||||
string id,
|
||||
string content,
|
||||
string title = "",
|
||||
string description = "",
|
||||
string footer = "")
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
|---|---|
|
||||
| `id` | Element id — must be unique per page; also used by `data-dialog-open` |
|
||||
| `content` | Raw HTML for the dialog body |
|
||||
| `title` | Optional heading at the top of the panel |
|
||||
| `description` | Optional subheading below the title |
|
||||
| `footer` | Optional raw HTML for the bottom button row |
|
||||
|
||||
---
|
||||
|
||||
## Usage examples
|
||||
|
||||
### Simple information dialog
|
||||
|
||||
```csharp
|
||||
// In the page component:
|
||||
Dialog = new Dialog(
|
||||
id: "about-dialog",
|
||||
title: "About BeepBoop",
|
||||
description: "A fast AOT-safe HTMX framework.",
|
||||
content: "<p>Version 1.0 — built with ❤️ and .NET 10.</p>",
|
||||
footer: """<button data-dialog-close="about-dialog" class="...">Close</button>""");
|
||||
```
|
||||
|
||||
Trigger button anywhere on the page:
|
||||
|
||||
```html
|
||||
<button data-dialog-open="about-dialog" class="...">About</button>
|
||||
```
|
||||
|
||||
### Confirmation dialog
|
||||
|
||||
```csharp
|
||||
new Dialog(
|
||||
id: "confirm-delete",
|
||||
title: "Delete item",
|
||||
content: "<p>This action cannot be undone.</p>",
|
||||
footer: """
|
||||
<button data-dialog-close="confirm-delete" class="...">Cancel</button>
|
||||
<button hx-delete="/items/42" hx-confirm="" data-dialog-close="confirm-delete"
|
||||
class="bg-destructive text-destructive-foreground ...">
|
||||
Delete
|
||||
</button>
|
||||
""")
|
||||
```
|
||||
|
||||
### HTMX-powered content reload
|
||||
|
||||
```csharp
|
||||
new Dialog(
|
||||
id: "user-detail",
|
||||
content: """<div hx-get="/users/42/detail" hx-trigger="revealed"></div>""")
|
||||
```
|
||||
|
||||
The `revealed` trigger fires when the dialog becomes visible, loading content on demand.
|
||||
|
||||
### Embedding inside a page slot
|
||||
|
||||
```html
|
||||
<!-- MyPage.htmx -->
|
||||
$$DeleteDialog$$
|
||||
<button data-dialog-open="confirm-delete" class="...">Delete</button>
|
||||
```
|
||||
|
||||
```csharp
|
||||
public IHtmxComponent DeleteDialog { get; }
|
||||
|
||||
public MyPage()
|
||||
{
|
||||
DeleteDialog = new Dialog(
|
||||
id: "confirm-delete",
|
||||
title: "Confirm deletion",
|
||||
content: "<p>Are you sure?</p>",
|
||||
footer: """<button data-dialog-close="confirm-delete">Cancel</button>""");
|
||||
}
|
||||
|
||||
protected override void RenderDeleteDialog(HtmxRenderContext ctx)
|
||||
=> DeleteDialog.Render(ctx.Next());
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tips and tricks
|
||||
|
||||
- The `id` is used both on the `<dialog>` element and in `data-dialog-open`/`data-dialog-close` — keep it unique per page.
|
||||
- The `×` close button is always rendered; `data-dialog-close` on footer buttons is optional but improves UX.
|
||||
- Use the native `<dialog>` `close` event for any cleanup needed after dismissal: `document.getElementById('id').addEventListener('close', fn)`.
|
||||
- Dialog content, title, description, and footer are raw HTML — HTML-encode user-supplied values.
|
||||
- For dialogs that load content via HTMX, place the HTMX attributes on a child div inside `content` rather than on the `<dialog>` element itself to avoid interfering with the dialog open/close lifecycle.
|
||||
- For dialogs that load content via HTMX, place the HTMX attributes on a child div inside `content` rather than on the `<dialog>` element itself to avoid interfering with the dialog open/close lifecycle.
|
||||
|
||||
---
|
||||
|
||||
## Complete page example
|
||||
|
||||
**`Templates/ItemsPage.htmx`**
|
||||
```html
|
||||
<div class="max-w-3xl mx-auto py-10">
|
||||
<div class="flex items-center justify-between mb-6">
|
||||
<h1 class="text-2xl font-bold">Items</h1>
|
||||
</div>
|
||||
$$ItemsTable$$
|
||||
$$DeleteDialog$$
|
||||
</div>
|
||||
```
|
||||
|
||||
**`Templates/ItemsPage.htmx.cs`**
|
||||
```csharp
|
||||
namespace Htmx.ApiDemo.Templates;
|
||||
|
||||
public sealed class ItemsPage : ItemsPageBase
|
||||
{
|
||||
private readonly IHtmxComponent _table;
|
||||
private readonly IHtmxComponent _deleteDialog;
|
||||
|
||||
public ItemsPage(IEnumerable<Item> items, string? deleteTargetId = null)
|
||||
{
|
||||
// Build table with a per-row Delete button that opens the dialog
|
||||
_table = new Components.Table(
|
||||
headers: new[] { "Name", "Created", "Actions" },
|
||||
rows: items.Select(item => new[]
|
||||
{
|
||||
System.Net.WebUtility.HtmlEncode(item.Name),
|
||||
item.CreatedAt.ToShortDateString(),
|
||||
$"""<button data-dialog-open="confirm-delete"
|
||||
hx-on:click="document.getElementById('delete-id').value='{item.Id}'"
|
||||
class="text-sm text-destructive underline">Delete</button>""",
|
||||
}));
|
||||
|
||||
_deleteDialog = new Components.Dialog(
|
||||
id: "confirm-delete",
|
||||
title: "Delete item",
|
||||
content: """
|
||||
<p class="text-sm">This action cannot be undone.</p>
|
||||
<input type="hidden" id="delete-id" name="itemId">
|
||||
""",
|
||||
footer: """
|
||||
<button data-dialog-close="confirm-delete"
|
||||
class="inline-flex h-9 rounded-md border border-input px-4 text-sm mr-2">
|
||||
Cancel
|
||||
</button>
|
||||
<button hx-delete="/items"
|
||||
hx-include="#delete-id"
|
||||
hx-target="closest tr"
|
||||
hx-swap="outerHTML"
|
||||
data-dialog-close="confirm-delete"
|
||||
class="inline-flex h-9 rounded-md bg-destructive text-destructive-foreground px-4 text-sm">
|
||||
Delete
|
||||
</button>
|
||||
""");
|
||||
}
|
||||
|
||||
protected override void RenderItemsTable(HtmxRenderContext ctx) => _table.Render(ctx.Next());
|
||||
protected override void RenderDeleteDialog(HtmxRenderContext ctx) => _deleteDialog.Render(ctx.Next());
|
||||
}
|
||||
```
|
||||
|
||||
**GET + DELETE handlers**
|
||||
```csharp
|
||||
[Handler]
|
||||
[MapGet("/items")]
|
||||
public static partial class GetItemsHandler
|
||||
{
|
||||
public record Query();
|
||||
|
||||
private static Task<IResult> HandleAsync(
|
||||
Query _, HttpContext ctx, CancellationToken ct)
|
||||
{
|
||||
var items = new[]
|
||||
{
|
||||
new Item("1", "Widget A", DateTime.Today.AddDays(-10)),
|
||||
new Item("2", "Widget B", DateTime.Today.AddDays(-5)),
|
||||
};
|
||||
return ctx.WriteHtmxPage(new ItemsPage(items), title: "Items");
|
||||
}
|
||||
}
|
||||
|
||||
[Handler]
|
||||
[MapDelete("/items")]
|
||||
public static partial class DeleteItemHandler
|
||||
{
|
||||
public record Command([property: FromForm] string ItemId);
|
||||
|
||||
private static IResult HandleAsync([AsParameters] Command cmd, CancellationToken ct)
|
||||
{
|
||||
// Delete item from database…
|
||||
return Results.Ok(); // HTMX swaps the row out with outerHTML
|
||||
}
|
||||
}
|
||||
|
||||
public record Item(string Id, string Name, DateTime CreatedAt);
|
||||
```
|
||||
Reference in New Issue
Block a user