Dialogs

Introduction

Overview

The Aurelia Dialog plugin provides a flexible and powerful way to display modal dialogs in your Aurelia applications. It supports dynamic content, customizable styling, and offers a robust API for managing dialog interactions.

Key Features

  • Dynamic content loading

  • Customizable styling and layouts

  • Promise-based API for handling dialog results

  • Built-in components for common dialog elements

  • Lifecycle hooks for fine-grained control

  • Support for both modal and non-modal dialogs

  • Keyboard navigation support

  • Native dialog renderer support

Installation and Setup

Installing the Plugin

Install the dialog plugin using npm:

Basic Configuration

To use the dialog plugin, you need to configure it in your application's main entry point. First, ensure you're using manual bootstrapping by modifying your index.html:

Then, configure the plugin in your main.js:

circle-exclamation

Configuration Options

For more control, you can provide a configuration callback:

Basic Usage

Dialog Service Overview

The Dialog Service is the main entry point for creating and managing dialogs. Import it into your view-model:

Opening Dialogs

There are two main approaches to opening dialogs:

  1. Using a Simple Prompt:

  1. Using Custom Dialog Components:

Handling Dialog Results

Dialog operations return promises that resolve when the dialog closes. Use the whenClosed method to handle results:

Using Dialog Controller

When creating custom dialog components, use the DialogController to manage the dialog:

circle-info

The DialogController provides methods like ok(), cancel(), and error() for closing the dialog with different results.

Dialog Components

Built-in Components

The dialog plugin provides several built-in components for constructing dialog interfaces:

  • <ux-dialog>: The main container component

  • <ux-dialog-header>: Header section of the dialog

  • <ux-dialog-body>: Main content area

  • <ux-dialog-footer>: Footer section, typically for buttons

Example of a complete dialog template:

attach-focus Attribute

The attach-focus attribute allows you to automatically focus an element when the dialog opens:

circle-info

The attach-focus attribute only works during the initial attachment. For dynamic focus changes, use Aurelia's focus attribute instead.

Controlling Default Resources

You can control which default resources are registered:

Configuration and Settings

Global Settings

Configure global settings that apply to all dialogs:

Per-dialog Settings

Configure settings for individual dialogs:

Position Callback

Use the position callback for custom positioning:

Dialog Lifecycle

Lifecycle Hooks Overview

Dialogs support several lifecycle hooks that execute in a specific order:

canActivate(model)

Controls whether the dialog can be opened:

activate(model)

Initializes the dialog with the provided model:

canDeactivate(result)

Controls whether the dialog can be closed:

deactivate(result)

Cleanup when dialog is closing:

Lifecycle Execution Order

  1. Constructor

  2. canActivate()

  3. activate()

  4. created()

  5. bind()

  6. attached()

  7. canDeactivate()

  8. deactivate()

  9. detached()

  10. unbind()

circle-exclamation

All lifecycle hooks can return promises, which will be awaited before proceeding to the next phase. This allows for asynchronous operations during the dialog lifecycle.

Customization

Styling Dialogs

Default Styles Override

The default styles are included when calling config.useDefaults(). To customize styles, you can override the default CSS:

Custom CSS Examples

Custom Renderers

Create a custom renderer by implementing the DialogRenderer interface:

Using Native Dialog Renderer

The plugin supports native HTML <dialog> element:

Advanced

Accessing Dialog Controller API

Access and control dialogs from the opening context:

Custom Dialog Implementations

Create complex dialogs with multiple steps:

Dynamic Dialog Content

Load dialog content dynamically:

Usage:

circle-info

When using dynamic content loading, ensure all potential components are properly bundled and available in your application.

These advanced features allow you to create sophisticated dialog implementations that can handle complex scenarios while maintaining clean, maintainable code.

Last updated

Was this helpful?