Documentation

Dialog

Summary

Modal dialog that displays additional functionality without leaving the current page.

Status

Examples

Code

A simple Dialog may have just one page, with one panel, plus the usual header with heading text and a footer with buttons.

If multiple panels are added to a Dialog page, they will be shown one at a time with a vertical set of controls on the left (very similar to vertical nav or tabs).

Multi-step dialogs (eg. wizards) show multiple pages, accessed via buttons in the footer.

HTML

Create a trigger which will be used by the JavaScript:

<button id="dialog-button" class="aui-button">Show dialog</button>

JavaScript

// Standard sizes are 400, 600, 800 and 960 pixels wide
var dialog = new AJS.Dialog({
    width: 800, 
    height: 500, 
    id: "example-dialog", 
    closeOnOutsideClick: true
});

// PAGE 0 (first page)
// adds header for first page
dialog.addHeader("Dialog");

// add panel 1
dialog.addPanel("Panel 1", "<p>Some content for panel 1.</p>", "panel-body");
// You can remove padding with:
// dialog.get("panel:0").setPadding(0);

// add panel 2 (this will create a menu on the left side for selecting panels within page 0)
dialog.addPanel("Panel 2", "<p>Some content for panel 2.</p><div style='height: 2000px;'>(forced-height element to demonstrate scrolling content)</div><p>End.</p>", "panel-body");

dialog.addButton("Next", function (dialog) {
    dialog.nextPage();
});
dialog.addLink("Cancel", function (dialog) {
    dialog.hide();
}, "#");

// PAGE 1 (second page)
// adds a new page to dialog
dialog.addPage();

// adds header for second page
dialog.addHeader("Dialog");

// adds a single panel on second page (as there is only one panel, no menu will appear on the left side)
dialog.addPanel("SinglePanel", "<p>Some content for the only panel on Page 1</p>", "singlePanel");

// add "Previous" button to page 1
dialog.addButton("Previous", function(dialog) {
   dialog.prevPage();
});
// adds "Cancel" button to page 1
dialog.addButton("Cancel", function (dialog) {
    dialog.hide();
});

// Add events to dialog trigger elements
AJS.$("#dialog-button").click(function() {
    // PREPARE FOR DISPLAY
    // start first page, first panel
    dialog.gotoPage(0);
    dialog.gotoPanel(0);
    dialog.show();
});

Options

The Dialog API uses a Dialog object which can be instantiated as follows:

var dialog = new AJS.Dialog({
    width:800, 
    height:500, 
    id:"dialog-name", 
    closeOnOutsideClick: true
});

This alone will create a simple popup that closes if the user clicks outside the popup.

In most cases, further functionality is added using Dialog's various methods.

Methods

dialog.addHeader(
    "HEADING", 
    "title-class"
);

dialog.addButton(
    "label", 
    fnOnClickHandler, 
    "button-class-name"
);

dialog.addLink(
    "label", 
    fnOnClickHandler, 
    "link-class-name", 
    "url"
);

dialog.addSubmit(
    "label", 
    function() { 
        //on click event 
    }
);

dialog.addCancel(
    "label", 
    fnOnClickHandler
);

dialog.addButtonPanel();

dialog.addPanel("title", 
                "content-selector", 
                "panel-class-name", 
                1);

dialog.addPage("page-class-name");

dialog.nextPage();

dialog.prevPage();

dialog.gotoPage(3);

dialog.getPanel(1, 3);

dialog.getPage(1);

dialog.getCurrentPanel();

dialog.gotoPanel(page, 3);

dialog.show();

dialog.hide();

dialog.remove();

dialog.disable();

dialog.enable();

.updateHeight();

Event Handlers

The addButton, addLink and addCancel methods accept an onclick handler function which is called when the link or button is clicked with the following arguments.

function fnOnClickHandler(dialog, page) {
  // dialog = This AJS.Dialog instance
  // page = The page of the dialog to which this button has been added
  // As of AUI 3.4:
  // Return true to allow the default action of this click event.
  // Return any other value to prevent the default action of this click event.
  return true;
  }

As of AUI version 3.4, omitting the return statement or returning false will prevent the default action of click events on this element. Returning true will allow the default action to proceed.

Events

As of AUI 3.5, events are thrown when a dialog is shown, hidden and removed. You can bind to the events:

• show.dialog
• hide.dialog
• remove.dialog

For example:

AJS.bind("show.dialog", function(e, data) {
    console.log("Dialog shown " + data.dialog.id);
});