Dialog Box / Question

Overview

An application’s primary activities take place in its main view. Occasionally the user needs to initiate a secondary activity at the same time as the primary activity, while maintaining the context of the first. Use the dialog box component to display a secondary activity in a window that floats above the primary activity taking place in the main view. The user’s attention is focused on the secondary activity, but they can still see the primary activity in the background.

A dialog box includes the following sections:

• A header at the top with a short title that explains what the dialog box is about
• One or more buttons right aligned at the bottom that close the dialog box and control the dialog’s action
• Optional content that displays between the dialog box header and the dialog box buttons

A dialog box is modal, which means that the user can see the primary activity in the background but cannot interact with it. Their focus is temporarily on the secondary activity.

Dialog boxes are reserved for simpler activities. Display more complex activities in the main view. In particular, dialog boxes cannot include a toolbar.

A dialog box must never launch another dialog box. Only one dialog box can be displayed at a time.

At mobile size, avoid using dialog boxes that are more complex than a simple question. There isn’t enough room to effectively display a secondary action without creating a confusing user experience, so keep this activity in the main view. If a view needs to be supported at mobile size, that often requires breaking larger tasks down into smaller pieces for the mobile experience.

The dialog box closes when the user presses any of the buttons at the bottom of the dialog or when the user presses the Escape key. You can include simple validations that disable a Save button until valid input is entered by the user, if appropriate. If the user closes the dialog box by pressing the Escape key, respond to that as if the user pressed the least destructive button option presented by the dialog. A dialog box should not close because the user clicks outside of it.

Dialog Box Buttons

A dialog box includes one button for each major action that the user can take with the dialog box. These buttons display in a section at the bottom-right of the dialog box. Each of these buttons closes the dialog box with a specific context.

The simplest dialog boxes only need to offer a single “Close” button, allowing the user to dismiss the dialog box. More complex dialog boxes ask the user to select between multiple actions, for example “Save” and “Cancel”. If the dialog box can add, modify, or delete anything, it must include a “Cancel” button to allow the user to back out of the dialog box without making any changes.

Dialog box button labels should be verbs that describe what will happen when the user presses the button. These labels should be both descriptive and succinct. Well labeled buttons should act like micro-help; not all users will read dialog box text completely, so button labels should be clear enough to accurately guide users through their tasks. Do not use generic button labels like “OK”; use descriptive button labels instead, such as “Close”, “Save”, and “Delete”. Always use the label “Cancel” for a button that allows the user to back out of the dialog box without making any changes.

Each dialog box button should use proper styling to communicate its impact:

• Use primary styling for the one dialog box button that performs the primary action for the dialog. Examples would include “Close” and “Save”. There should be no more than one primary button in the dialog box.
• Use destructive styling if pressing the dialog box button triggers a significant, destructive action like deletion. This button style should be used sparingly.
• Use secondary styling for all other dialog box buttons, including “Cancel” buttons. In some cases, all dialog box buttons have equal impact. Use secondary styling for all dialog buttons in this case.

Examples

Here are some common examples of dialog boxes.

A dialog box can be used to display a simple message that the user must acknowledge. In this case, display the message in the dialog box header and include a single Close button, which closes the dialog with no further action. (Most simple messages are displayed using notifications; a dialog box should only be used for this purpose if it’s important for the user to acknowledge the message.)

A dialog box can be used to ask a simple question. In this case, display the question in the dialog box header. Include buttons that answer the question but use descriptive labels (not just Yes/No). If the question requires more contextual information to help the user make the decision, display that info in the content area.

A dialog box can be used to prompt for user input then perform an action. In this case, display a title in the header, Save and Cancel buttons in the footer, and the appropriate input components in the content area.

A simple question displays as a slide-up at mobile size. (Don’t use complex dialog boxes at mobile size.)

A question that includes a destructive button.

Development

Web component development

Component reference

rui-question

rui-dialog-box

rui-dialog-box-button

Implementing a question

Use rui-question to show a simple message or ask a simple question. The question includes a title (the message or question) and one or more dialog box buttons that close the question when pressed.

Begin by importing the rui-dialog-box module into your application.

// import into app.module
import '@jkhy/responsive-ui-wc/components/rui-dialog-box/rui-dialog-box-imports';

Let’s look at an example of an rui-question used to prompt the user if they wish to log out.

First, let’s define a showLogOutQuestion boolean property in the TypeScript, initializing that to a value of false. This property will control when the question displays.

public showLogOutQuestion: boolean = false;

Now let’s add the rui-question element to the HTML:

• We set the titleText to an actual question: “Do you wish to log out?”.
• We bind the showQuestion trigger property to the showLogOutQuestion boolean backing property in the TypeScript.
• We reset the showLogOutQuestion property in the rui-question-show-question-change event handler. If we didn’t do this, the question would only ever display once.
• We specify the logOutQuestionClose() method as the handler for the rui-question-close event that fires when the user answers the question.
  • The detail field in $event will include the name of the button that the user pressed (or “Escape” if the user pressed the Escape key).
• The dialog box buttons provide all answers to the question: “Log Out” and “Cancel” in this case.
  • We nest the dialog box buttons within a div that has the question-buttons CSS class applied. If you don’t nest the buttons like this, they won’t work as expected.
  • The “Log Out” button uses primary styling since this is the primary action for the dialog.
  • The “Cancel” button uses secondary styling.

<rui-question titleText="Do you wish to log out?"
    [showQuestion]="showLogOutQuestion" (rui-question-show-question-change)="showLogOutQuestion = $event.detail"
    (rui-question-close)="logOutQuestionClose($event)">

    <div slot="question-buttons">
        <rui-dialog-box-button text="Log Out" buttonStyle="primary"></rui-dialog-box-button>
        <rui-dialog-box-button text="Cancel" buttonStyle="secondary"></rui-dialog-box-button>
    </div>
    
</rui-question>

In this example, we use a button in the view to trigger the display of the question. This button’s click event handler simply sets the showLogOutQuestion boolean property to a value of true when pressed, which in turn displays the question.

<rui-button text="Log Out" (rui-click)="showLogOutQuestion = true"></rui-button>

Here is the logOutQuestionClose() method that we specified as the event handler for the question’s rui-question-close event. The event parameter includes a detail field that contains either “Log Out”, “Cancel”, or “Escape”, depending on whether the user pressed a question button or pressed the Escape key. In this example we call the logOut() method if the user’s answer was “Log Out”. We do nothing if the user pressed the “Cancel” button or the Escape key.

public logOutQuestionClose(e): void {
    if (e.detail === 'Log Out')
        this.logOut();
}

Here’s an example of a question showing a destructive button. We set buttonStyle="destructive" on the “Delete Record” button since pressing that button results in a significant, destructive action.

<rui-question titleText="Delete this record?"
    [showQuestion]="showQuestionWithDestructive"
    (rui-question-close)="questionClose($event)"
    (rui-question-show-question-change)="showQuestionWithDestructive = $event.detail">

    <div slot="question-buttons">
        <rui-dialog-box-button text="Delete Record" buttonStyle="destructive"></rui-dialog-box-button>
        <rui-dialog-box-button text="Cancel" buttonStyle="secondary"></rui-dialog-box-button>
    </div>

</rui-question>

Implementing a dialog box

Begin by importing the rui-dialog-box module into your application.

// import into app.module
import '@jkhy/responsive-ui-wc/components/rui-dialog-box/rui-dialog-box-imports';

Let’s look at an example of an rui-dialog-box used to prompt for a user’s first and last name.

First, let’s define a showDialogBox boolean property in the TypeScript, initializing that to a value of false. This property will control when the dialog box displays.

public showDialogBox: boolean = false;

Now let’s add the rui-dialog-box element to the HTML:

• We set the titleText to “User Information”.
• We bind the showDialog trigger property to the showDialogBox boolean backing property in the TypeScript.
• We reset the showDialogBox property in the rui-dialog-box-show-dialog-change event handler. If we didn’t do this, the dialog box would only ever display once.
• We specify the dialogBoxClose() method as the handler for the rui-dialog-box-close event that fires when the user closes the dialog box.
  • The detail field in $event will include the name of the button that the user pressed (or “Escape” if the user pressed the Escape key).
• We nest the dialog box content between the rui-dialog-box start and end tags. The content in this example is a form with 2 fields, along with their validation errors.
• The “Save” and “Cancel” dialog box buttons allow the user to specify how to process the input values.
  • We nest the dialog box buttons within a div that has the dialog-box-buttons CSS class applied. If you don’t nest the buttons like this, they won’t work as expected.
  • The “Save” button uses primary styling since this is the primary action for the dialog.
  • The “Cancel” button uses secondary styling.

<rui-dialog-box titleText="User Information" [showDialog]="showDialogBox"
    (rui-dialog-box-close)="dialogBoxClose($event)"
    (rui-dialog-box-show-dialog-change)="showDialogBox = $event.detail">

    <form [formGroup]="addUserForm">

        <!-- First Name -->
        <rui-form-field labelText="First Name" labelFor="FirstName" [isRequired]="true"
            [hasError]="firstName.invalid && (firstName.dirty || firstName.touched)">
            <input id="FirstName" type="text" class="rui-form-control" formControlName="firstName" required />
        </rui-form-field>

        <!-- First Name validation errors -->
        <ul *ngIf="firstName.invalid && (firstName.dirty || firstName.touched)" class="rui-form-validation-errors">
            <li *ngIf="firstName.errors['required']">
                First Name is required
            </li>
        </ul>

        <!-- Last Name -->
        <rui-form-field labelText="Last Name" labelFor="LastName" [isRequired]="true"
            [hasError]="lastName.invalid && (lastName.dirty || lastName.touched)">
            <input id="LastName" type="text" class="rui-form-control" formControlName="lastName" required />
        </rui-form-field>

        <!-- Last Name validation errors -->
        <ul *ngIf="lastName.invalid && (lastName.dirty || lastName.touched)" class="rui-form-validation-errors">
            <li *ngIf="lastName.errors['required']">
                Last Name is required
            </li>
        </ul>
        
    </form>

    <div slot="dialog-box-buttons">
        <rui-dialog-box-button text="Save" buttonStyle="primary" [isDisabled]="!addUserForm.valid"></rui-dialog-box-button>
        <rui-dialog-box-button text="Cancel" buttonStyle="secondary"></rui-dialog-box-button>
    </div>

</rui-dialog-box>

In this example, we use a button to trigger the display of the dialog box. This button’s click event handler simply sets the showDialog boolean property to a value of true when pressed, which in turn displays the dialog box.

<rui-button text="Show Dialog Box" (rui-click)="showDialogBox = true"></rui-button>

Here is the dialogBoxClose() method that we specified as the event handler for the dialog box’s rui-dialog-box-close event. The event parameter’s detail field contains a value of “Save”, “Cancel”, or “Escape”, depending on whether the user pressed a dialog box button or pressed the Escape key. In this example we call the updateSettings() method if the user’s pressed the “Save” button, and we log a console message if the user pressed the “Cancel” button or the Escape key.

public dialogBoxClose(e): void {
    if (e.detail === 'Save') {
        this.updateSettings();
    } else if (e.detail === 'Cancel' || e.detail === 'Escape') {
        console.log('Settings changes canceled');
    }
}

Delaying the dialog box close

In some cases, you may need to perform some extra handling before the dialog closes. For example, if your application needs to complete server-side validation asynchronously, you must wait for that to complete before allowing the dialog box to close.

To do this, bind the dialog box’s canClose property to a backing value in your controller that has a value of false. Define an event handler for the rui-dialog-box-before-close event.

If the interim process is time consuming, use the canClosePollCount property to set the number of times the component polls the canClose value for true before quitting. The dialog box checks the canClose value every 100 milliseconds for the number of times specified in the canClosePollCount property, stopping once canClose is set to true.

<rui-dialog-box titleText="User Information" [showDialog]="showDialogBox"
    canClosePollCount="15" [canClose]="canDialogClose"
    (rui-dialog-box-before-close)="dialogBeforeClose()"
    (rui-dialog-box-close)="dialogBoxClose($event)">
    ....
</rui-dialog-box>

In the dialogBeforeClose event handler, execute any code needed to test if the dialog can close, updating the backing value appropriately.

public dialogBeforeClosed() {
    // Simulate server-side validation test
    if (formValidated) {
        this.canDialogClose = true;
    } else {
        this.canDialogClose = false;
    }
}

Angular wrapper development

Wrapper reference

jha-question

jha-dialog-box

jha-dialog-box-button

Implementing a question

Use jha-question to show a simple message or ask a simple question. The question includes a title (the message or question) and one or more dialog box buttons that close the question when pressed.

Begin by including noty in your package.json, where x.y.z is the currently supported version number for this framework specified here. Use npm install to install this framework.

"dependencies": {
    ...
    "noty": "x.y.z",
    ...
},

Once the package has been installed, add it to your scripts bundle in the angular.json file.

"scripts": [
    ...
    "node_modules/noty/js/noty/packaged/jquery.noty.packaged.min.js"
]

Begin by importing the JhaDialogBoxModule module into your application.

// import into app.module
import { JhaDialogBoxModule } from '@jkhy/responsive-ui-angular/jha-dialog-box';

@NgModule({
    imports: [
        ...
        JhaDialogBoxModule,
        ...
    ]
})

export class AppModule(){}

Let’s define a showLogOutQuestion boolean property in the TypeScript, initializing that to a value of false. This property will control when the question displays.

public showLogOutQuestion: boolean = false;

Next add the jha-question element to the HTML, prompting the user if they wish to log out. The question includes a “Log Out” button that uses primary styling since this is the primary action for the dialog, and a “Cancel” button that uses secondary styling by default. Use two-way binding to bind the jhaShowQuestion property to the backing showLogOutQuestion boolean property in the TypeScript. (Without two-way binding, the popup would only display once.) We specify the logOutQuestionClose() event to be called when the user answers the question. Pass $event as the event handler parameter; this string value will reflect the name of the button that the user pressed (or “Escape” if the user pressed the Escape key). Add the dialog box buttons within the jha-question start and close tags.

<jha-question jhaTitle="Do you wish to log out?" [(jhaShowQuestion)]="showLogOutQuestion" (jhaClose)="logOutQuestionClose($event)">
    <jha-dialog-box-button jhaText="Log Out" jhaButtonStyle="Primary"></jha-dialog-box-button>
    <jha-dialog-box-button jhaText="Cancel"></jha-dialog-box-button>
</jha-question>

In this example, we use a button in the view to trigger the display of the question. This button’s click event handler simply sets the showLogOutQuestion boolean property to a value of true when pressed, which in turn displays the question.

<jha-button jhaText="Log Out" (jhaClick)="showLogOutQuestion = true"></jha-button>

Here is the logOutQuestionClose() method that we specified as the event handler for the question’s jhaClose event. The dialogResult parameter reflects either “Log Out”, “Cancel”, or “Escape”, depending on whether the user pressed a button or pressed the Escape key. In this example we call the logOut() method if the user’s answer was “Log Out”. We do nothing if the user pressed the “Cancel” button or the Escape key.

public logOutQuestionClose(dialogResult: string): void {
    if (dialogResult === 'Log Out')
        this.logOut();
}

Here’s an example of a question showing a destructive button. We set jhaButtonStyle="destructive" on the “Delete Record” button since pressing that button results in a significant, destructive action.

<jha-question jhaTitle="Delete this record?" [(jhaShowQuestion)]="showQuestionWithDestructiveOption" (jhaClose)="questionClosed($event)">
    <jha-dialog-box-button jhaText="Delete Record" jhaButtonStyle="Destructive"></jha-dialog-box-button>
    <jha-dialog-box-button jhaText="Cancel"></jha-dialog-box-button>
</jha-question>

Implementing a dialog box

Begin by importing the JhaDialogBoxModule module into your application.

// import into app.module
import { JhaDialogBoxModule } from '@jkhy/responsive-ui-angular/jha-dialog-box';

@NgModule({
    imports: [
        ...
        JhaDialogBoxModule,
        ...
    ]
})

export class AppModule(){}

Let’s define a showDialogBox boolean property in the TypeScript, initializing that to a value of false. This property will control when the dialog box displays.

public showDialogBox: boolean = false;

Next add the jha-dialog-box element to the HTML. The dialog box includes a “Save” button that uses primary styling since this is the primary action for the dialog, and a “Cancel” button that uses secondary styling by default. Use two-way binding to bind the jhaShowDialog property to the backing showDialog boolean property in the TypeScript. (Without two-way binding, the popup would only display once.) Specify the dialogClosed() event to be called when the user closes the dialog. Pass $event as the event handler parameter; this string value will reflect the name of the button that the user pressed (or “Escape” if the user pressed the Escape key). Add the dialog box content and dialog box buttons within the jha-dialog-box start and close tags.

<jha-dialog-box jhaTitle="User Information" [(jhaShowDialog)]="showDialog" (jhaClose)="dialogClosed($event)">

    <form [formGroup]="addUserForm">

        <div class="row form-group" [ngClass]="{'has-error': firstName.invalid && (firstName.dirty || firstName.touched)}">
            <div class="col-md-3">
                 <label class="control-label jha-required-indicator" for="FirstName">First Name:</label>
            </div>
            <div class="col-md-4">
                <input id="FirstName" type="text" class="form-control" formControlName="firstName" required />
                <div *ngIf="firstName.invalid && (firstName.dirty || firstName.touched)" class="help-block">
                    <div *ngIf="firstName.errors.required">
                        First Name is required
                    </div>
                </div>
            </div>
        </div>

        <div class="row form-group" [ngClass]="{'has-error': lastName.invalid && (lastName.dirty || lastName.touched)}">
            <div class="col-md-3">
                <label class="control-label jha-required-indicator" for="LastName">Last Name:</label>
            </div>
            <div class="col-md-4">
                <input id="LastName" type="text" class="form-control" formControlName="lastName" required />
                <div *ngIf="lastName.invalid && (lastName.dirty || lastName.touched)" class="help-block">
                    <div *ngIf="lastName.errors.required">
                        Last Name is required
                    </div>
                </div>
            </div>
        </div>

    </form>

    <jha-dialog-box-button jhaText="Save" jhaButtonStyle="Primary" [jhaIsDisabled]="!addUserForm.valid"></jha-dialog-box-button>
    <jha-dialog-box-button jhaText="Cancel"></jha-dialog-box-button>

</jha-dialog-box>

In this example, we use a button to trigger the display of the dialog box. This button’s click event handler simply sets the showDialog boolean property to a value of true when pressed, which in turn displays the dialog box.

<jha-button jhaText="Show Dialog Box" (jhaClick)="showDialog = true"></jha-button>

Here is the dialogClosed() method that we specified as the event handler for the dialog box’s jhaClose event. The dialogResult parameter reflects either “Save”, “Cancel”, or “Escape”, depending on whether the user pressed a button or pressed the Escape key. In this example we call the updateSettings() method if the user’s answer was “Save”, and we log a console message if the user pressed the “Cancel” button or the Escape key.

public dialogClosed(dialogResult: string): void {
    if (dialogResult === 'Save') {
        this.updateSettings();
    } else if (dialogResult === 'Cancel' || dialogResult === 'Escape') {
        console.log('Settings changes canceled');
    }
}

Delaying the dialog box close

In some cases, you may need to perform some extra handling before the dialog closes. For example, if your application needs to complete server-side validation asynchronously, you must wait for that to complete before allowing the dialog box to close.

To do this, bind the dialog box’s jhaCanClose property to a backing value in your controller that has a value of false. Define an event handler for the jhaBeforeClose event.

If the interim process is time consuming, use the jhaCanClosePollCount property to set the number of times the component polls the jhaCanClose value for true before quitting. The dialog box checks the jhaCanClose value every 100 milliseconds for the number of times specified in the jhaCanClosePollCount property, stopping once canClose is set to true.

<jha-dialog-box jhaTitle="User Information" [(jhaShowDialog)]="showDialog" 
    jhaCanClosePollCount="15" [jhaCanClose]="canDialogClose" (jhaBeforeClose)="dialogBeforeClosed()" (jhaClose)="dialogClosed($event)">
    ....
</jha-dialog-box>

In the dialogBeforeClose event handler, execute any code needed to test if the dialog can close, updating the backing value appropriately.

public dialogBeforeClosed() {
    // Simulate server-side validation test
    if (formValidated) {
        this.canDialogClose = true;
    } else {
        this.canDialogClose = false;
    }
}

Design

There are two flavors of dialog boxes:

• The Dialog Box component displays a header at the top with a title, a button bar at the bottom with at least one button, and content between the header and the button bar.
• The Question component is a simpler version of the dialog box component, with only the header and the button bar. The title in the header asks a question, and the buttons in the button bar answer the answer.
  • At mobile size, the question displays as a slide-up.

All dialog boxes display a translucent modal backdrop behind them, which darkens the background. Add this component first. Resize it to cover the entire view. Lock the modal backdrop so you can drag other components on top of it.

Next, decide whether you’re displaying a dialog box or a question:

• If you’re displaying a dialog box:
  • Drag a dialog box component onto the modal backdrop and resize it appropriately.
  • Change the title in the header to an appropriate value.
  • Drag text buttons onto the button bar and change their text appropriately. These buttons are right justified in the button bar and are separated by 7 pixels of horizontal space. Use primary, secondary, and destructive buttons appropriately. Vertically center these buttons.
  • Add content to the center portion of the dialog box.
• If you’re displaying a question at tablet or desktop size:
  • Drag a question component onto the modal backdrop and resize it appropriately.
  • Change the title in the header to an appropriate value.
  • Drag text buttons onto the button bar and change their text appropriately. These buttons are right justified in the button bar and are separated by 7 pixels of horizontal space. Use primary, secondary, and destructive buttons appropriately. Vertically center these buttons.
• If you’re displaying a question at mobile size:
  • Drag a Slide Up component onto the bottom of the modal backdrop and resize it appropriately. The slide up always displays at the bottom of the screen.
  • Change the title in the slide up component to an appropriate value.
  • Drag slide up button components onto the slide up component and change their text appropriately. These buttons display below the slide up component’s title and are separated by 5 pixels of vertical space. Use primary, secondary, and destructive buttons appropriately.

Figma design

Adobe XD design