Dialog Specification

Overview

igx-dialog supports dialog component that opens centered on top of the app content. With the igx-dialog you can create alerts, dialogs and custom dialogs.

Objectives

Provide means for citizen developers to implement a simple common case, yet customizable dialog with minimal efforts.

User Stories

Developer

As a citizen developer, I want to be able to add a dialog to my application, so that I can inform or “ask” the end user.
As a citizen developer, I want to add a message to the dialog templates, so that I clarify my dialog better for the end user.
As a citizen developer, I want to have at least one button, so that I can enable the end user confirm that he had been notified.
As a citizen developer, I want to add second button, so that I can enable the end user make a choice.
As a citizen developer, I want to disable the rest of the app, so that I would make it mandatory for the end user to take action.
As a citizen developer, I want to customize the dialog template using ng-content, so that I would provide the end user with a custom dialog that suits the functions of the app. (size, add more content, make it scrollable, add inputs, checkboxes, radio button and etc)

End user

As an end user, I want to get a dialog inside my app, so that I can be notified upon important information that must be presented to me.
As an end user, I want to get title in the dialog, so that I can read the dialog.
As an end user, I want to get message in the dialog, so that I read more details about the dialog.
As an end user, I want to have more content in the dialog, so that I perform more tasks or settings of any kind.

##Acceptance criteria

The citizen developer can add a dialog to the application.
The citizen developer can add a title to the dialog.
The citizen developer can add a message to the dialog.
The citizen developer can add one button to the dialog.
The citizen developer can add a second button to the dialog.
The citizen developer can customize the dialog's content as he/she sees fit, including make it scrollable.
The citizen developer can add more content to the dialog as he/she sees fit.
The citizen developer can assign events to actions occurring on the dialog.
The end user sees the dialog on top of the app and is restricted from interacting with the main application.
The end user could interact with the dialog – make a selection, enter data and scroll if content overflows the dialog boundaries.
The end user can leave the dialog on making a selection or taping outside the dialog.
The citizen developer has all ARIA tags that apply.

Functionality

Dialogs should never be obscured, either by other elements or the screen edge or appear partially on screen. Dialogs always retain focus until dismissed or a required action has been taken.

End User Experience

The dialog must follow the material design guidelines, i.e. be a square and look floating above the main application with consistent shadows appearing at the bottom and on the left. On-screen mobile keyboard if called should push the dialog up and snap to it.

Developer Experience

Alerts are done by adding title, message and button label.

<igx-dialog #alert
    title="Alert"
    message="Your email has been sent successfully!"
    leftButtonLabel="OK" (onLeftButtonSelect)="alert.close()">
</igx-dialog>

You can set title to the alert title="TitleofTheAlert"

You can be more descriptive and set message message="Your email has been sent successfully!"

You can attach to the left button select event (onLeftButtonSelect)="alert.close()"

Dialogs are done by adding another button.

<igx-dialog #dialog
    title="Confirmation"
    message="Are you sure you want to delete the Microsoft_Annual_Report_2015.pdf and Microsoft_Annual_Report_2015.pdf files?"
    leftButtonLabel="Cancel"
    (onLeftButtonSelect)="dialog.close()"
    rightButtonLabel="OK"
    (onRightButtonSelect)="onDialogOKSelected($event)">
</igx-dialog>

Custom Dialogs are done by adding any mark up in the igx-dialog tag.

When you are using Custom Dialogs you don't have a message property set.

<igx-dialog #form
    title="Sign In"
    leftButtonLabel="Cancel"
    (onLeftButtonSelect)="form.close()"
    rightButtonLabel="Sign In"
    rightButtonBackgroundColor="green"
    rightButtonColor="white"
    closeOnOutsideSelect="true">
    <div class="ig-form-group">
        <input type="text" igInput />
        <label igLabel>Username</label>
    </div>
    <div class="ig-form-group">
        <input type="password" igInput />
        <label igLabel>Password</label>
    </div>
</igx-dialog>

You can make the dialog dismissible `closeOnOutsideSelect="true"``

User Interface

The end user interface consists of:

Title (optional) - The title briefly describes the type of choice being made. Titles should always be displayed in their entirety and only used when necessary.
Content - Dialog content typically consists of text and/or UI control elements. It is focused on a specific task, such as confirming item deletion or choosing a setting.
Actions - Dialogs present a focused and limited set of actions, which are generally affirmative or dismissive.

Navigation

The modal control can be dismissed by touching/clicking outside of a dialog window or by using the system back button.

Positioning and animations

You can use positionSettings input in order to specify specific location of the dialog to be opened and change the animation
Another way to specify a dialog position is to pass overlaySettings to the open method