Dialogs and notifications
A dialog is declared by the view and rendered closed by the shell, and opened and closed by key — from a command that fills it first, or from a press alone, with no round trip. Notifications are a client effect with nowhere of their own on the tree — they stack up in a corner the view chooses. This page is also where a failed command's report and the error page are configured.
Declaring a dialog
Override CreateDialogs() on the view and return a list of UIDialog:
protected override IReadOnlyList<UIDialog> CreateDialogs()
=> [
new UIDialog
{
Key = ReleasesController.ConfirmKey,
TitleId = "confirm-delete-title",
CloseOnBackdrop = false,
CloseOnEscape = false,
Content = new StackPanelComponent()
.SetSpacing(12)
.AddChild(new TextComponent("confirm-delete-title")
.SetTitle("Delete this release?")
.SetTitleType(UITextAppearance.Title)
.BindDescription(nameof(ReleasesController.Question))
)
.AddChild(new StackPanelComponent()
.SetOrientation(UIOrientation.Horizontal)
.SetSpacing(8)
.SetHorizontalAlignment(UIAlignment.End)
.AddChild(UIDialogs.CloseButton(ReleasesController.ConfirmKey))
.AddChild(new ButtonComponent()
.SetTitle("Delete")
.SetVariant(UIButtonVariant.Danger)
.OnClick(nameof(ReleasesController.DeleteRelease))
)
)
}.OnClose(nameof(ReleasesController.KeepRelease))
];
The content is an ordinary component tree, bound against the view's controller like the rest of the page — here a
line the controller writes before it opens the dialog, the standard Cancel, which shuts the dialog on the page and raises its
OnClose, and a Delete that runs a command. TitleId names the dialog by the title it shows. UIDialogs.Confirm is the
same dialog in one call.
UIDialog:
| Member | Meaning |
|---|---|
Key |
stable string a command or interaction opens/closes it by |
Content |
the root component of the dialog's body |
Surface (UISurfaceStyle) |
what the panel is made of — Background, Surface (default), Tinted |
Placement (UIDialogPlacement) |
Center (default), or a full-length sheet against Left, Right, Top, Bottom — a shortcut over the members below |
Width, MinWidth, MaxWidth, Height, MinHeight, MaxHeight (UIResponsive<UILayoutLength>) |
the panel's size on the overlay, per tier; unset, a centred panel is sized to its content under a 560 px cap, and on a phone it is the screen less a thin margin |
HorizontalAlignment, VerticalAlignment (UIAlignment) |
where the panel stands on the overlay — Start, Center, End, Stretch; unset, the placement decides |
Margin (UIResponsive<UIThickness>) |
the room kept between the panel and the overlay's edges, per tier |
Modal |
whether it blocks interaction with the view underneath (default true) |
CloseOnBackdrop |
whether clicking the backdrop closes it (default true) |
CloseOnEscape |
whether Escape closes it (default true); a non-modal dialog takes only an Escape pressed inside it |
TitleId |
the id of the component in Content whose words name the dialog for a screen reader (aria-labelledby), so a bound title names it as it changes; it must stand inside the content and in no template, or the view does not compile. The UIDialogs presets set it (UIDialogs.TitleId(key)) |
AccessibleName |
the name of a dialog that shows no title of its own, a phrase or an author's text, translated for the page's language; TitleId wins over it |
OnClose(command, arguments) |
a method, not an init member: the command run when the viewer dismisses the dialog by Escape, the backdrop or an × of its own (CloseDialogEffect with RaisesClose); a close the server asks for raises nothing; OnCloseLiteral takes literal values |
UIDialog is a record, so a dialog a preset built takes what it does not set itself:
UIDialogs.Create(key, title, content) with { Placement = UIDialogPlacement.Right }.
The panel is placed on the overlay the way a component is placed in its host, with the same words: a 640 px editor
is Width = UILayoutLength.Absolute(640), a panel pinned to the top-right corner is HorizontalAlignment = End, VerticalAlignment = Start, and a value per tier is UIResponsive<UILayoutLength>.Create(...). A sheet is the same
thing spelled short: Placement = Left is a panel at the start edge, stretched top to bottom, 420 px wide unless a
Width says otherwise. UILayoutLength.Fill() is the overlay's room less the panel's margins — the authored Margin, else the
thin default margin a centred panel keeps (none on a sheet) — so a filled panel keeps its margins rather than running past the
overlay's edge.
A destructive confirmation turns both CloseOnBackdrop and CloseOnEscape off, so only its own buttons answer
it. A non-modal sheet (Modal = false) at an edge, drawn on Surface = Background, is the shape a filter
drawer or a side panel takes — the page keeps working beside it, its Escape included. A dialog opened from another stands on
top of it, whatever order CreateDialogs lists them in.
Opening and closing
From a controller, Context.Dialogs (IUIDialogService):
_ = await Context.Dialogs.ShowAsync(Context.Handle, ProgressKey, cancellationToken).ConfigureAwait(false);
// ... work ...
_ = await Context.Dialogs.HideAsync(Context.Handle, ProgressKey, cancellationToken).ConfigureAwait(false);
ShowAsync/HideAsync push straight to the page, as Context.SendEffectsAsync sends an effect, so the dialog stands open for exactly as long as the
command takes — the pattern for a wait dialog nothing on its own body dismisses.
A command can instead return the effect, which is the more common shape when opening or closing is the whole of what the command does, or the last thing. The controller behind the confirmation above:
internal sealed partial class ReleasesController : UIControllerBase
{
public const string ConfirmKey = "confirm-delete";
private readonly List<int> _releases = [479, 480, 481];
[RecursiveMember]
public partial string Question { get; set; } = string.Empty;
[UICommand]
public UICommandResult AskBeforeDelete()
{
if (_releases.Count == 0)
return UICommandResult.Ok([new ShowNotificationEffect("Nothing left to delete.", UIColorStyle.Info)]);
Question = $"Release #{_releases[^1]} goes for good.";
return UICommandResult.Ok([new OpenDialogEffect(ConfirmKey)]);
}
[UICommand]
public UICommandResult DeleteRelease()
{
_releases.RemoveAt(_releases.Count - 1);
return UICommandResult.Ok([new CloseDialogEffect(ConfirmKey), new ShowNotificationEffect("The release is gone.", UIColorStyle.Success)]);
}
/// <summary>The dialog's close: its Cancel has shut it on the page already.</summary>
[UICommand]
public static UICommandResult KeepRelease()
=> UICommandResult.Ok([new ShowNotificationEffect("The release stays.", UIColorStyle.Info)]);
}
Changes go first, then effects, so the dialog opens on the question the command has just written.
OpenDialogEffect(dialogKey) and CloseDialogEffect(dialogKey) both take just the key. A dialog that shows what already
stands — a sheet of filters, a picker — opens from the press itself, with no round trip and no command:
UIButtons.Icon(UIGlyphs.Search, "Search").InteractOn(EventNames.Click, new OpenDialogEffect(SearchKey))
A close from an interaction is the viewer's own, an × in the dialog: new CloseDialogEffect(key) { RaisesClose = true }
closes it on the page and raises its OnClose as Escape does (the UIDialogs headers wire it). The dialog's own Cancel, Close or
Done is UIDialogs.CloseButton(key, action), which also puts back the held edits of the form the key names
(DiscardFormEffect), so a form opened again shows what the server holds. A close the controller decides
— after a save — goes from a command. A key the view does not declare fails the view's compile when an interaction names it;
returned from a command, the effect is dropped and logged as an error rather than sent to find nothing.
Notifications
ShowNotificationEffect(string message, UIColorStyle tone = UIColorStyle.Info) raises a toast, and
ShowNotificationEffect(UIPhrase message, UIColorStyle tone = UIColorStyle.Info) raises one whose words carry arguments:
return UICommandResult.Ok([new ShowNotificationEffect("app.build.published", UIColorStyle.Success)]);
return UICommandResult.Ok([new ShowNotificationEffect(UIPhrase.Of("app.build.published-number", ("number", 481)), UIColorStyle.Success)]);
A notification's words are translated on the page, as a label's are: a string is read as a plain value on a translatable
property is — under KeyPrefixes only a prefixed one is a key, and any other text shows as written — and a UIPhrase is always
looked up and filled. An open toast follows a language switch. Message is the UIPhrase either way (UIPhrase.IsText for an
author's text), so there is no need to translate in the controller first (localization).
Tone is a UIColorStyle, the scale a badge's colour takes, and six of its members give the toast an accent in their colour: Info,
Success, Warning, Danger, Primary and Accent; any other member leaves it with the plain border. A
Warning or Danger toast is announced to a screen reader at once (role="alert"), every other one politely. Where a view's
notifications stack is UIViewOptions.NotificationPlacement (UINotificationPlacement: Bottom — the default
— or Top), set once for the view rather than per notification. Every toast of a view is one width,
UIViewOptions.NotificationWidth — 400 pixels by default — and a narrow screen narrows it further.
A toast carries a close button and dismisses itself after five seconds — eight when it carries an action — or after its own
Duration. The pointer resting on it, or the keyboard on its buttons, holds it; when they leave, it gets its full time again.
One raised while the page is off screen waits until the page is shown, and its time starts there.
A toast with the way back
Action gives a toast one button that runs a command of the controller's — the commonest use is "Deleted — Undo", in place
of asking first:
[UICommand]
public UICommandResult Delete(string id)
{
_deleted[id] = Messages.Take(id); // a soft delete: kept for the way back
return UICommandResult.Ok([new ShowNotificationEffect("app.message.deleted")
{
Action = new UINotificationAction("app.undo", nameof(Restore), id)
}]);
}
[UICommand]
public void Restore(string id)
{
if (_deleted.Remove(id, out Message? message))
Messages.Put(message);
}
The label is translated as the message is. The argument goes to the command's one parameter; the command needs no button of
its own. It is checked as the effect is sent: a command the controller does not declare, or one that takes more than the one
argument, is logged, and the toast shows without its button. The page is never told the command or the argument — only an id
the runtime issued for this one press — and the press runs the command as a button would, through the command filters,
authorization and MaxConcurrent, once. A pressed toast closes.
Duration is the window the button can be pressed in, held open while the reader hovers or focuses the toast. Without one, a
toast with an action stands eight seconds rather than five: the reader reads the message before reaching the button. Making the delete
final once that window has passed — purging what the soft delete kept — is the controller's; nothing tells it the toast closed.
Off the page: the system's notification
A toast raised in a tab nobody looks at waits there until the tab is shown, so a reader looking elsewhere does not see it.
ShowSystemNotificationEffect(title, body) shows the operating system's
notification while the page is off screen — another tab chosen, the window minimised — and the page's toast while it is on screen:
[UICommand(ConcurrencyMode = UICommandConcurrencyMode.Background)]
public async Task<UICommandResult> WatchDeployAsync(int release, CancellationToken cancellationToken)
{
await _deploys.WaitAsync(release, cancellationToken);
return UICommandResult.Ok([new ShowSystemNotificationEffect(UIPhrase.Of("app.release.live", ("release", release)), "app.release.live.body")
{
Tag = $"release:{release}",
Action = new UINotificationAction("app.open", nameof(OpenRelease), release)
}]);
}
The page decides as it shows it, from what it is then. When is WhenHidden by default, or Always; Fallback is what shows
where the system's does not — off screen with no permission, on screen under WhenHidden, a phone's browser without the
framework's worker: the toast by default, its title over its body, held until the page is on screen; or None. A click brings
the page forward and runs Action's command, offered for one press as a toast's is; the toast's button runs the same. Tag is
the key a later notification replaces this one by — one per chat; without one, each send gets its own. Address, a path of
this site, is where a click brings the page — through its own leave, so unsaved work is asked about first — or opens it once the
page is gone; a page already there runs Action instead. The fallback toast leads there by an "Open" button (AddressTitle
words it), and on a page already there shows Action's button. Icon is the page's icon unless set. Sent to every page of a runtime
(SendEffectsToAllAsync, a broadcast), a page off screen is left out while another is on screen, and with none on screen only
one of them is sent it, so the reader is told once, where they look; with Always, one page is sent it — the first on screen,
else one off screen — so it sounds once.
A reader has many runtimes — one per tab and route by default — so a notification about something that happened to the user,
not to one page, goes through IUINotifier, which applies the same rule across all of a browser's pages:
public sealed class ChatNotices(IUINotifier notifier)
{
public ValueTask<int> MessageAsync(string userId, Message message, CancellationToken cancellationToken)
=> notifier.NotifyUserAsync(userId, new ShowSystemNotificationEffect(message.Author, message.Text)
{
Tag = $"chat:{message.ChatId}",
Address = $"/chat?id={message.ChatId}"
}, cancellationToken);
}
Each session signed in as the user — each browser — decides on its own: while a page of it is on screen, whatever its route, the
pages on screen are sent it and show the fallback; while none is, one page off screen shows the system's. With Always, one page
of the browser shows it. It offers no Action — a command belongs to one page's runtime — and refuses one; Address is the way
back, and a click without one only brings forward the page that showed it. A page that already shows what it is about — the
conversation open on screen, which the controller knows from OnVisibilityChangedAsync — is the application's to know: it does not
send. It answers how many pages it reached; none means the user has no page open.
The browser asks the reader first, and only inside their own press: RequestNotificationPermissionEffect raised by an interaction
(InteractOn("click", …)), never from a command's answer, after which most browsers refuse without a word. What it answered is
Context.NotificationPermission — one browser's, not the reader's — and a change reaches OnNotificationPermissionChangedAsync,
queued as posted work is (controllers). Denied is undone only in the browser's settings: say so rather than ask again. A page
not on https (localhost aside) shows none and reports Unsupported: a phone opening the PC's address on the network is one.
A desktop browser shows a page's notification itself. A phone's shows only a service worker's, so the application turns the
framework's on in its web services, and the page registers it at /_ne/, where it controls no page of the application:
services.AddSystemNotifications(); // the framework's worker
services.AddSystemNotifications(WebServiceWorkerMode.Imported); // the application's own worker runs importScripts("/_ne/sw.js")
An iPhone shows a page's notifications only for an application added to the Home Screen, which takes a manifest:
WebEndpointOptions.Manifest (WebManifestOptions: Name, ShortName, Icons, Display, colours) is served at
/_ne/manifest.webmanifest and linked from every page. A notification to a reader with no page open at all — Web Push — is not
in the framework yet.
When a command fails
The client never reads a raw success/failure flag — both the invoke return and the push channel only apply
changes and effects. So a failed command whose result carries no effects of its own — one that returned
UICommandResult.Fail(error), threw, or was refused by an authorization check — gets one attached
automatically: a Danger ShowNotificationEffect whose text comes from UIErrorHandlingOptions, configured
through ConfigureErrorHandling:
application.ConfigureErrorHandling(errors =>
{
errors.NotifyOnCommandFailure = true;
errors.IncludeExceptionDetail = false;
errors.CommandRefusedMessage = "You are not allowed to do that.";
errors.CommandFailedMessage = "Something went wrong. Please try again.";
errors.ErrorPageMessage = "This page could not be shown.";
errors.ErrorRoute = "/error";
errors.NotFoundRoute = "/not-found";
});
| Option | Meaning |
|---|---|
NotifyOnCommandFailure |
whether a failed command with no effects of its own is reported at all (default true) |
IncludeExceptionDetail |
whether the real exception message reaches the browser, in the toast and on the error page — off by default, since an exception routinely carries a connection string, a table name or a file path |
CommandRefusedMessage |
shown when a command throws an UnauthorizedAccessException — an authorization check's refusal |
CommandFailedMessage |
shown when a command throws anything else, unless IncludeExceptionDetail is on |
ErrorPageMessage |
what the default error page shows, unless IncludeExceptionDetail is on and the failure handed over its text |
ErrorRoute |
where a page goes when resolving its view throws, or rendering it does; a failing command is reported in place, never routed here |
NotFoundRoute |
where a request for an unregistered route goes, with the requested route in its route parameter; the page standing in for that route is answered with a 404 |
The toast's text has three levels:
- What the command wrote.
UICommandResult.Fail(error)is shown with its ownerroras it stands; a failure with no text shows nothing. - A refusal. A command that throws an
UnauthorizedAccessExceptionshowsCommandRefusedMessage. - Anything else thrown.
CommandFailedMessage, or the exception's own message whenIncludeExceptionDetailis on.
Returning your own effects from a failing command is how it takes over the reporting — the automatic
notification only fires when a command's result carries none. The text at every level is translated on the page by the
plain rule a notification's string is — a command's own error included, so under KeyPrefixes only a prefixed one is a key —
and follows a language switch while the toast is open; ErrorPageMessage goes through the translator too. An application
overrides the framework's wording by localization rather than by re-implementing the mechanism.
A page's own value write or window of rows that fails on the server is reported the same way: the controller's handler's
effects, else the failure notification, go to the page that asked. A call to the server that fails in the browser with nothing else
saying so — a press, a value, a window of rows or a page turn, a toast's action — shows one toast, Something went wrong. Please
try again. (ui.command.failed), once for a burst of them; a dropped connection and an expired press say their own.
When a page fails
A page whose view cannot be resolved goes to ErrorRoute, and so does a page that throws while it is being
rendered — a getter that fails as this reader's values are drawn — rather than answering with a bare 500. The error
page receives the exception's text when IncludeExceptionDetail is on, as a UIErrorDetail in its message navigation
parameter, handed over in-process; an error page of the application's own reads that type, never a string, since a message in
the address is anybody's words. Off, there is no parameter and the default page shows ErrorPageMessage. Both routes are used only when they are registered, and the error route never
redirects to itself, so a failing error page cannot loop. A refusal while resolving is not an error: it goes to the
sign-in or forbidden route instead (see security).