Design

Dialogs are used to capture information, complete actions or display detailed messages without leaving the current page.

Available dialog sizes:

Small dialogs are commonly used for messages, while medium and large dialogs are used to capture information or complete tasks. If you feel you need a larger dialog, consider using a Page Dialog or simply create a full-viewport view instead.

When the viewport is too small for the selected dialog size, the dialog will become a full-screen overlay.

In most cases a Dialog will have at least two buttons in the footer - a verb action and an icon button to close the Dialog:

When the Close button is the only control in the Dialog footer, it must have the full visible text 'Close':

Dialog vs Page Dialog

Dialogs are used for modal interactions which are layered over the current view.

Note there is also a Page Dialog, which is a non-modal dialog used without layering over an existing view.

Code

There are two parts to each Dialog:

  1. A trigger element (usually a button) used to open the Dialog
  2. The Dialog itself, with a heading, content and controls

Notes:

  • The Dialog content has no spacing applied by default. For standard grid spacing wrap the dialog content in an .ace-panel element.
  • If using the HTML API, note the dialog's aria-labelledby attribute must match the id attribute of the h2 inside the dialog header.
  • If you are managing state directly, note the aria-hidden attribute must be updated appropriately when showing and hiding.
Example Element Code
Dialog trigger Any button or link can be used as a Dialog trigger.

Attach an event to your trigger element, then use the Dialog's ID with the open method. For example with jQuery:


                                                                    $('#TRIGGERID').on('click', function() {
                                                                      ACE.Dialog.open('#DIALOGID');
                                                                    });
Small dialogs are suitable for short messages. 

                                                                                                      <dialog class="ace-dialog ace-dialog-small" role="dialog" aria-hidden="true" aria-labelledby="smallDialogheader" id="smallDialog">
                                                                                                            <div class="ace-dialog-header">
                                                                                                              <h2 id="smallDialogheader" class="ace-h2">Small Dialog</h2>
                                                                                                            </div>
                                                                                                            <div class="ace-dialog-content">
                                                                                                                  <div class="ace-panel">
                                                                                                                    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque faucibus dui et elit lacinia, eget molestie magna tincidunt. Vivamus feugiat quam in nulla cursus laoreet sed id urna. Curabitur volutpat dolor at ultrices imperdiet. Integer neque tellus, rhoncus vitae tincidunt sit amet, dictum at velit.</p>
                                                                                                                  </div>
                                                                                                            </div>
                                                                                                            <div class="ace-dialog-footer">
                                                                                                                  <button class="ace-button" id="disclosebuttonsmall" type="button"><span>Disclose</span></button>
                                                                                                                  <button class="ace-button ace-button-icon" id="disclosebuttoniconsmall" type="button"><span><span class="ace-icon ace-icon-control-close" title="Close">Close</span></span></button>
                                                                                                            </div>
                                                                                                      </dialog>

                                                                                              <% 
                                                                                              ace.Dialog(Array(_
                                                                                                "id", "smallDialog",_
                                                                                                "headerid", "smallDialogheader"_
                                                                                              ))
                                                                                                ace.DialogHeader(Array(_
                                                                                                  "id", "smallDialogHeader",_
                                                                                                  "text", "Quick Brown Fox"_
                                                                                                ))
                                                                                                ace.DialogContent()
                                                                                                  ace.Panel(Array()) %>
                                                                                                    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque faucibus dui et elit lacinia, eget molestie magna tincidunt. Vivamus feugiat quam in nulla cursus laoreet sed id urna. Curabitur volutpat dolor at ultrices imperdiet. Integer neque tellus, rhoncus vitae tincidunt sit amet, dictum at velit.</p>
                                                                                                  <% ace.PanelEnd
                                                                                                ace.DialogContentEnd()
                                                                                                ace.DialogFooter()
                                                                                                  ace.Button(Array(_
                                                                                                    "text", "Ok",_
                                                                                                    "id", "disclosebuttonsmall"_
                                                                                                  ))
                                                                                                  ace.Button(Array(_
                                                                                                    "text", "Cancel",_
                                                                                                    "id", "disclosebuttoniconsmall"_
                                                                                                  ))
                                                                                                ace.DialogFooterEnd()
                                                                                              ace.DialogEnd() 
                                                                                              %>
Medium and large dialogs are good for forms.

Note that the dialog's aria-labelledby attribute must match the id attribute of the h2 inside the dialog header. Also the aria-hidden attribute must be updated appropriately if managing state directly.


                                                                                                          <dialog class="ace-dialog ace-dialog-medium" role="dialog" aria-hidden="true" aria-labelledby="mediumDialogheader" id="mediumDialog">
                                                                                                                <div class="ace-dialog-header">
                                                                                                                  <h2 id="mediumDialogheader" class="ace-h2">Medium Dialog</h2>
                                                                                                                </div>
                                                                                                                <div class="ace-dialog-content">
                                                                                                                      <div class="ace-panel">
                                                                                                                            <form class="ace-form ace-form-sidelabel" action="#" id="medium-dialog-form">
                                                                                                                                      <div class="ace-form-group ace-form-group-text" id="medium-dialog-form-field1-group">
                                                                                                                                            <div class="ace-form-item ace-form-item-label">
                                                                                                                                                  <label class="ace-form-label" for="medium-dialog-form-field1"><span class="ace-text">Enter some text</span>
                                                                                                                                                  </label>
                                                                                                                                            </div>
                                                                                                                                            <div class="ace-form-item ace-form-item-text">
                                                                                                                                                  <input class="ace-form-input ace-form-input-text" type="text" id="medium-dialog-form-field1">
                                                                                                                                                  </input>
                                                                                                                                            </div>
                                                                                                                                      </div>
                                                                                                                                      <div class="ace-form-group ace-form-group-text" id="medium-dialog-form-field2-group">
                                                                                                                                            <div class="ace-form-item ace-form-item-label">
                                                                                                                                                  <label class="ace-form-label" for="medium-dialog-form-field2"><span class="ace-text">More text</span>
                                                                                                                                                  </label>
                                                                                                                                            </div>
                                                                                                                                            <div class="ace-form-item ace-form-item-text">
                                                                                                                                                  <input class="ace-form-input ace-form-input-text" type="text" id="medium-dialog-form-field2">
                                                                                                                                                  </input>
                                                                                                                                            </div>
                                                                                                                                      </div>
                                                                                                                            </form>
                                                                                                                      </div>
                                                                                                                </div>
                                                                                                                <div class="ace-dialog-footer">
                                                                                                                      <button class="ace-button" id="disclosebuttonmedium" type="button"><span>Disclose</span></button>
                                                                                                                      <button class="ace-button ace-button-icon" id="disclosebuttoniconmedium" type="button"><span><span class="ace-icon ace-icon-control-close" title="Close">Close</span></span></button>
                                                                                                                </div>
                                                                                                          </dialog>

                                                                                              <% 
                                                                                              ace.Dialog(Array(_
                                                                                                "id", "mediumDialog",_
                                                                                                "headerid", "mediumDialogHeader",_
                                                                                                "type", "medium"_
                                                                                              ))
                                                                                                ace.DialogHeader(Array(_
                                                                                                  "id", "mediumDialogHeader",_
                                                                                                  "text", "Dialog Medium"_
                                                                                                ))
                                                                                                ace.DialogContent() %>
                                                                                                  <% ace.Form(Array(_
                                                                                                    "action","#",_
                                                                                                    "id", "medium-dialog-form",_
                                                                                                    "type", "sidelabel"_
                                                                                                  ))
                                                                                                    ace.PresetFormGroup(Array(_
                                                                                                      "type","text",_
                                                                                                      "label","Enter some text",_
                                                                                                      "id", "medium-dialog-form-field1"_
                                                                                                    ))
                                                                                                    ace.PresetFormGroup(Array(_
                                                                                                      "type","text",_
                                                                                                      "label","More text",_
                                                                                                      "id", "medium-dialog-form-field2"_
                                                                                                    ))
                                                                                                  ace.FormEnd %>
                                                                                                <% ace.DialogContentEnd()
                                                                                                  ace.DialogFooter()
                                                                                                    ace.Button(Array(_
                                                                                                      "text", "Ok",_
                                                                                                      "id", "disclosebuttonmedium"_
                                                                                                    ))
                                                                                                    ace.Button(Array(_
                                                                                                      "text", "Cancel",_
                                                                                                      "id", "disclosebuttonmedium"_
                                                                                                    ))
                                                                                                  ace.DialogFooterEnd()
                                                                                              ace.DialogEnd 
                                                                                              %>
Dialog with footer submit buttons In some cases the dialog will contain form elements and you need to use the buttons in the dialog footer to submit the form. To do this, the ACE form classes are applied using a DIV (essentially a shim to enable styles) and an unclassed FORM element is placed as the first child of DIALOG. 

                                                                                                  <dialog class="ace-dialog ace-dialog-small" role="dialog" aria-hidden="true" aria-labelledby="smallDialogheader" id="smallDialog">
                                                                                                    <!-- Use an unclassed FORM element here, it encloses the footer buttons-->
                                                                                                    <form action="#">
                                                                                                          <div class="ace-dialog-header">
                                                                                                            <h2 id="smallDialogheader" class="ace-h2">Quick Brown Fox</h2>
                                                                                                          </div>
                                                                                                          <div class="ace-dialog-content">
                                                                                                                <div class="ace-panel">
                                                                                                                  <!-- Use a DIV to set up the form layout-->
                                                                                                                  <div class="ace-form ace-form-sidelabel">
                                                                                                                    <!-- Form groups as usual-->
                                                                                                                  </div>
                                                                                                                </div>
                                                                                                          </div>
                                                                                                          <div class="ace-dialog-footer">
                                                                                                            <!-- This button can now be used to submit the form-->
                                                                                                                    <button class="ace-button" type="submit"><span>Submit</span></button>
                                                                                                          </div>
                                                                                                    </form>
                                                                                                  </dialog>

                                                                                              ace.Dialog(Array(_
                                                                                                "id", "DIALOGID",_
                                                                                                "headerid", "DIALOGHEADERID",_
                                                                                                "type", "medium"_
                                                                                              ))
                                                                                                %><form action="#"><%
                                                                                                ace.DialogHeader(Array(_
                                                                                                  "id", "DIALOGHEADERID",_
                                                                                                  "text", "Dialog Medium"_
                                                                                                ))
                                                                                                ace.DialogContent()
                                                                                                  ace.Panel(Array())
                                                                                                    %><div class="ace-form ace-form-sidelabel"><%
                                                                                                      ace.PresetFormGroup(Array(_
                                                                                                        "type","text",_
                                                                                                        "label","Enter some text",_
                                                                                                        "id", "medium-dialog-form-field1"_
                                                                                                      ))
                                                                                                      ace.PresetFormGroup(Array(_
                                                                                                        "type","text",_
                                                                                                        "label","More text",_
                                                                                                        "id", "medium-dialog-form-field2"_
                                                                                                      ))
                                                                                                    %></div><%
                                                                                                  ace.PanelEnd
                                                                                                ace.DialogContentEnd()
                                                                                                  ace.DialogFooter()
                                                                                                    ace.Button(Array(_
                                                                                                      "text", "Ok",_
                                                                                                      "id", "disclosebuttonmedium"_
                                                                                                    ))
                                                                                                    ace.Button(Array(_
                                                                                                      "text", "Cancel",_
                                                                                                      "id", "disclosebuttonmedium"_
                                                                                                    ))
                                                                                                  ace.DialogFooterEnd()
                                                                                                %></form><%
                                                                                              ace.DialogEnd

JavaScript

Methods

Function Arguments Description Example
init elementSelector

Binds all the events and polyfills to dialog element.

Init is called by default after the initial page load, so this is only required if you generate a new Dialog that has not been initialised.

 ACE.Dialog.init('.ace-dialog');
open elementSelector Opens dialog ACE.Dialog.open('#dialog');
close elementSelector Closes dialog ACE.Dialog.close('#dialog');
destroy elementSelector Removes the event bindings. ACE.Dialog.destroy('.ace-dialog');

Events

Event Description Example
ace-dialog-displayed Fires when dialog is displayed 
document.getElementById('dialog').addEventListener('ace-dialog-displayed', function() {});
ace-dialog-closed Fires when dialog is closed 

                                                        document.getElementById('dialog').addEventListener('ace-dialog-closed', function() {});

Dependencies

  • jQuery 1.10.2 http://jquery.com/
  • HTML5 Dialog support: dialog-polyfill https://github.com/GoogleChrome/dialog-polyfill
  • HTML5 custom events object: customeventpolyfill.js