Dialog boxes

Table of contents

• Alert dialog box
• Confirmation dialog box
• Standard dialog box
• onAction, onExecute, and onCancel callbacks
• Action Labels
• Changing Available Actions

The Episerver user interface uses dialog boxes in many place to communicate information or perform tasks within the current view. 

Alert dialog box

The Alert dialog box displays information that a user acknowledges but is not required to perform any action. For example, when a page version is successfully deleted, you can display an alert that tells the user that the operation was successful.

require(["epi/shell/widget/dialog/Alert"], function (Alert) {
    var dialog = new Alert({
        heading: "Version Deleted",
        description: "The page version has been successfully deleted."
    });
    dialog.show();
});

Confirmation dialog box

The Confirmation dialog displays information for which a user must make a decision. For example, if a user wants to edit a page that is locked for editing by someone else, display a question that asks whether it is OK to continue.

require(["epi/shell/widget/dialog/Confirmation"], function (Confirmation) {
    var dialog = new Confirmation({
        heading: "Edit Page",
        description: "This page is currently being edited by someone else. Do you wish to continue?"
    });
    dialog.show();
});

Standard dialog box

The standard Dialog displays custom content. You should create a widget that displays and manages the business logic of the component and use the standard dialog as a display container. For example, if you want to delete a page that has other pages linking to it, you can display a standard dialog with a widget that contains information about linked pages.

require([
"epi/shell/widget/dialog/Dialog", 
"example/widget/LinkedPages"], 

function (Confirmation, LinkedPages) {
    var dialog = new Dialog({
        title: "Move to Trash",
        heading: "Move page to the trash?",
        description: "The following pages link to this page or its children. Move this page to the trash anyway?",
        content: new LinkedPages()
    });
    dialog.show();
});

onAction, onExecute, and onCancel Callbacks

Dialog boxes have a callback interface for when actions occur. The alert and confirmation dialog boxes each have the onAction callback; an acknowledgement for the alert dialog box and a boolean parameter for the confirmation dialog box. 

require(["epi/shell/widget/dialog/Confirmation"], function (Confirmation) {
    var dialog = new Confirmation({
        description: "This page is currently being edited by someone else. Do you wish to continue?",
        title: "Edit Page",
        onAction: function (confirmed) {
            if (confirmed) {
                /* Change view to edit mode */
            }
        }
    });
    dialog.show();
});

The standard dialog box uses the Dojo API for issuing callbacks; the confirm action causes an onExecute callback and the cancel action causes an onCancel callback. You should read the Dojo dialog box documentation before connecting to or overriding either of these events.

Action labels

Each dialog box has properties that define the labels to be displayed. You can customize the default labels for actions when you construct the dialog box using acknowledgeActionText for the alert dialog box and confirmActionText and cancelActionText for the confirmation and standard dialogs. There are common action labels localized in epi.resources.action .

Changing available actions

When you use the standard dialog, there are times when the displayed widget needs to add actions to the action pane; a provider and consumer pattern is implemented to facilitate this in a decoupled fashion. The standard dialog is an epi.shell.widget._ActionConsumer and your widget inside the dialog implements the epi.shell.widget._ActionProviderWidget and supply its actions using the addActions method.

require([
"dijit/layout/_LayoutWidget", 
"epi/shell/widget/dialog/Dialog", 
"epi/shell/widget/_ActionProviderWidget"], 

function (_LayoutWidget, Dialog, _ActionProviderWidget) {

    var MyActionProviderWidget = dojo.declare("example.widgets.MyActionProviderWidget", [_LayoutWidget, _ActionProviderWidget], {
        startup: function () {
            this.inherited(arguments);
            this.addActions({
                name: "hello",
                label: "Say hello",
                iconClass: "buttonClass",
                action: dojo.hitch(this, function () {
                    this._sayHello();
                })
            });
        },

        _sayHello: function () {
            console.log("Hello!");
        }
    });

    var providerWidget = new MyActionProviderWidget();

    var dialog = new Dialog({
        content: providerWidget
    });

    dialog.show();
});

You can register a provider with a consumer manually, by supplying it to the constructor arguments of the consumer.

require(["epi/shell/widget/dialog/Dialog", "epi/shell/widget/_ActionProvider"], function (Dialog, _ActionProvider) {

    var MyActionProvider = dojo.declare("example.MyActionProvider", [_ActionProvider], {
        getActions: function () {
            return [
                {
                    name: "hello",
                    label: "Say hello",
                    iconClass: "buttonClass",
                    action: dojo.hitch(this, function () {
                        this._sayHello();
                    })
                }           
            ];
        },

        _sayHello: function () {
            console.log("Hello!");
        }

    });
    var provider = new MyActionProvider();

    var dialog = new Dialog({
        content: "Some dialog content.",
        actionProviders: [provider]
    });

    // Act
    dialog.show();
});

If you do not have any use for the default dialog buttons, you can remove them by setting defaultActionsVisible to false when constructing the dialog box.

Changing the state of actions

To change the state of an action during the lifetime of a dialog box, such as enabling or disabling an action, call  _ActionProvider.setActionProperty().

<script type="text/javascript">
    require(["dojo", "dijit/_Widget", "epi/shell/widget/dialog/Dialog", "epi/shell/widget/_ActionProviderWidget"],
    function (dojo, _Widget, Dialog, _ActionProviderWidget) {

        // Implement a widget inheriting the action provider widget
        var MyActionProvider = dojo.declare("example.MyActionProvider", [_Widget, _ActionProviderWidget], {
            startup: function () {
                this.inherited(arguments);

                // Add an action to the dialog toolbar
                this.addActions({
                    name: "disableme",
                    label: "Click to disable",
                    action: dojo.hitch(this, function () {
                        // When the action is executed we disable this action
                        this.setActionProperty("disableme", "disabled", true);
                    })
                });
            }
        });

        var dialog = new Dialog({
            content: new MyActionProvider()
        });

        dialog.show();
    });
</script>