dijit.Dialog¶
Status: | Draft |
---|---|
Version: | 1.0 |
Available: | since V? |
Dijit’s modal Dialog Box simulates a regular GUI dialog box. The contents can be arbitrary HTML, but are most often a form or a short paragraph. The user can close the dialog box without acting by clicking on the X button in the top-right corner.
Usage¶
The Dialog and underlay append themselves to the <body> element, which requires you apply your theme className there (as no other elements parent the Dialog.domNode). You need <body class="tundra"> (or some other applicable theme name) in order for the Dialog to be styled.
Examples¶
Dialog via markup¶
The first example creates a Dialog via markup from an existing DOM node:
A dialog created via markup. First let’s write up some simple HTML code because you need to define the place where your Dialog sdhould be created.
<div id="dialogOne" dojoType="dijit.Dialog" title="My Dialog Title"> <div dojoType="dijit.layout.TabContainer" style="width: 200px; height: 300px;"> <div dojoType="dijit.layout.ContentPane" title="foo">Content of Tab "foo"</div> <div dojoType="dijit.layout.ContentPane" title="boo">Hi, I'm Tab "boo"</div> </div> </div> <p>When pressing this button the dialog will popup:</p> <button id="buttonOne" dojoType="dijit.form.Button">Show me! <script type="dojo/method" event="onClick" args="evt"> // Show the Dialog: dijit.byId("dialogOne").show(); </script> </button>
<script type="text/javascript"> dojo.require("dijit.form.Button"); dojo.require("dijit.Dialog"); dojo.require("dijit.layout.TabContainer"); dojo.require("dijit.layout.ContentPane"); </script>
Note that dialog’s source markup can be hidden via specifying style=”display: none”, to prevent it from flashing on the screen during page load. However, hiding the dialog indirectly via a class won’t work (in that the dialog will remain invisible even when it’s supposed to be displayed).
Dialog programmatically¶
Now lets create a dialog programmatically, and change the dialog’s content dynamically
A programmatically created dialog with no content. First lets write up some simple HTML code because you need to define the place where your Dialog dhould be created.
<p>When pressing this button the dialog will popup. Notice this time there is no DOM node with content for the dialog:</p> <button id="buttonTwo" dojoType="dijit.form.Button" onClick="showDialogTwo();">Show me!</button>
<script type="text/javascript"> dojo.require("dijit.form.Button"); dojo.require("dijit.Dialog"); var secondDlg; dojo.addOnLoad(function(){ // create the dialog: secondDlg = new dijit.Dialog({ title: "Programatic Dialog Creation", style: "width: 300px" }); }); function showDialogTwo(){ // set the content of the dialog: secondDlg.attr("content", "Hey, I wasn't there before, I was added at " + new Date() + "!"); secondDlg.show(); } </script>
Coloring the Underlay¶
If you wish to alter the default color for the underlay, you do so in CSS. The underlay receives an ID to match the Dialog, suffixed with :ref:underlay, which you can define a css class for:
<style type="text/css"> #dialogColor_underlay { background-color:green; } </style> <div id="dialogColor" title="Colorful" dojoType="dijit.Dialog"> My background color is Green </div> <p>When pressing this button the dialog will popup:</p> <button id="button4" dojoType="dijit.form.Button">Show me!</button>
<script type="text/javascript"> dojo.require("dijit.form.Button"); dojo.require("dijit.Dialog"); dojo.addOnLoad(function(){ // create the dialog: var dialogColor = dijit.byId("dialogColor"); // connect t the button so we display the dialog onclick: dojo.connect(dijit.byId("button4"), "onClick", dialogColor, "show"); }); </script>
Confirming Dialog Contents¶
This example shows a Dialog containing form data. You can get the form data as a javascript object by calling attr(‘values’) on the dialog.
To prevent the user from dismissing the dialog if there are errors in the form, add an onSubmit handler to your submit button:
<div dojoType="dijit.Dialog" id="formDialog" title="Form Dialog" execute="alert('submitted w/args:\n' + dojo.toJson(arguments[0], true));"> <table> <tr> <td><label for="name">Name: </label></td> <td><input dojoType=dijit.form.TextBox type="text" name="name" id="name"></td> </tr> <tr> <td><label for="loc">Location: </label></td> <td><input dojoType=dijit.form.TextBox type="text" name="loc" id="loc"></td> </tr> <tr> <td><label for="date">Start date: </label></td> <td><input dojoType=dijit.form.DateTextBox type="text" name="sdate" id="sdate"></td> </tr> <tr> <td><label for="date">End date: </label></td> <td><input dojoType=dijit.form.DateTextBox type="text" name="edate" id="edate"></td> </tr> <tr> <td><label for="date">Time: </label></td> <td><input dojoType=dijit.form.TimeTextBox type="text" name="time" id="time"></td> </tr> <tr> <td><label for="desc">Description: </label></td> <td><input dojoType=dijit.form.TextBox type="text" name="desc" id="desc"></td> </tr> <tr> <td colspan="2" align="center"> <button dojoType=dijit.form.Button type="submit" onSubmit="return checkData();">OK</button> </td> </tr> </table> </div> <p>When pressing this button the dialog will popup:</p> <button id="buttonThree" dojoType="dijit.form.Button">Show me!</button>
<script type="text/javascript"> dojo.require("dijit.form.Button"); dojo.require("dijit.Dialog"); dojo.require("dijit.form.TextBox"); dojo.require("dijit.form.DateTextBox"); dojo.require("dijit.form.TimeTextBox"); dojo.addOnLoad(function(){ formDlg = dijit.byId("formDialog"); // connect to the button so we display the dialog on click: dojo.connect(dijit.byId("buttonThree"), "onClick", formDlg, "show"); }); function checkData(){ var data = formDlg.attr('value'); console.log(data); if(data.sdate > data.edate){ alert("Start date must be before end date"); return false; }else{ return true; } } </script>
Sizing the Dialog¶
A dialog by default sizes itself according to it’s content, just like a plain <div>. If you want a scrollbar on a dialog, then you need to add width/height to a div inside the dialog, like this:
<script type="text/javascript"> dojo.require("dijit.form.Button"); dojo.require("dijit.Dialog"); </script>
<div id="sized" dojoType="dijit.Dialog" title="My scrolling dialog"> <div style="width: 200px; height: 100px; overflow: auto;"> <p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean semper sagittis velit. Cras in mi. Duis porta mauris ut ligula. Proin porta rutrum lacus. Etiam consequat scelerisque quam. Nulla facilisi. Maecenas luctus venenatis nulla. In sit amet dui non mi semper iaculis. Sed molestie tortor at ipsum. Morbi dictum rutrum magna. Sed vitae risus.</p> </div> </div> <p>When pressing this button the dialog will popup (with a scrollbar):</p> <button dojoType="dijit.form.Button" onClick="dijit.byId('sized').show();">Show me!</button>
Accessibility¶
Keyboard¶
Action | Key |
---|---|
Navigate to next focusable element in the dialog | tab |
Navigate to previous focusable element in the dialog | shift-tab |
Close the dialog | escape |
Known Issues¶
- On Windows, In Firefox 2, when in High Contrast mode, the dialog with display correctly, but the underlying page will not be seen.
- Dialogs with an input type=file as the only focusable element will not work with the keyboard. This is because input type=file elements require two tab stops - one in the textbox and the other on the “Browse” button. Rather than clutter the dialog box widget with code to special case for this one condition, dialog boxes with an input type=file as the only focusable element are not supported.
- Dialogs with an input type=file element as the first focusable element in Firefox (and there are additional focusable elements). Programmatically setting focus to an input type=file element behaves oddly in Firefox. In this case the focus is set onto the textbox field and then immediately moved onto the browse button of the input type=file field. This causes problems in Firefox when setting focus to an input type=file element as the first element as a dialog. For this reason, in Firefox if the first focusable item in a dialog is an input type=file, focus will be set onto the dialog container rather than the input element. For these reasons it is recommended that input type=file elements not be added as the only or first focusable item within a dialog in Firefox.
- Even though the dialog is marked with the proper ARIA role of dialog, JAWS 9 does not speak “dialog” when the dialog is opened. In Firefox 2 even though the focus is on the first focusable item in the dialog, the information about that item is also not spoken. Thus, it is important that the instructions or label for a trigger element that opens a dialog to indicate via text that a dialog will be opened. In Firefox 3 with JAWS 9 the dialog is also not announced but the information about the item in the dialog which gets focus is spoken. The issue has been fixed in JAWS 10 with Firefox 3.
- There are focus issues when the dialog is created via an href. Due to timing issues focus may not be properly set nor properly trapped in the dialog. For accessibility reasons, dialogs created via href are not recommended. This issue will be addressed in a future release.