type: widget
release: 1.5
status: released
documentation: http://api.jqueryui.com/dialog/
demo: http://jqueryui.com/dialog/
1 - Description:
A dialog is an overlay that is typicaly used in a modal situation to provide a message that the user needs to acknowledge (N1), a decision that needs to be confirmed (N2) or a data entry workspace or wizard (N3). Overlays can also be non-modal, but confirmations and data entry dialogs are always modal in a typical application unless it is an inpector-style window.
2 - Visual Design:
3 - Functional Specifications/Requirements:
- Follows existing specifications:
- the element that .dialog() is called on will become the content area of the dialog
- a titlebar and button pane will be generated automatically based on the options
- the content, titlebar and button pane will be wrapped in a generated div
- all dialog interactions must be performed on the content element, not the generated wrapper
- if the title option is null on init, the title attribute on the element that .dialog() was called on will be used. If neither exists, a non-breaking space is used.
- dialogs are placed at the end of the body on open to ensure proper stacking.
- min/max width/height will be enforced for height: auto and for resizable dialogs
- if height is not set to auto, height will override other inconsistent settings
- the context of the functions for buttons will be the element that .dialog() was called on
- pressing escape when a dialog has focus will close the dialog if closeOnEscape is set to true
- the position option should not allow the titlebar to go outside of the viewport
- the dialog will always be contained within the document when dragging
- modal dialogs will prevent access to all elements not in the dialog
- other dialogs opened after the modal dialog will still be accessible
- preventing the default action in the beforeClose event will prevent the dialog from closing
- focus will be set to the dialog on open
- focus will be set on
- the first element inside the content area with a autofocus attribute
- or the first tabbable element in the content area
- or the first button in the button pane
- or the close button
- or the dialog itself
- tabbing through elements will be contained within the dialog (including titlebar and button pane)
- calling open when the dialog is already open will move the dialog to the top, if it isn't already, and focus as if opened from scratch
- calling close when the dialog is already closed will result in no action being taken
- draggable and resizable options are ignored if the relevant plugins aren't loaded
Keyboard
- ESCAPE - close the dialog
- TAB - focus the next element, or wrap around to the first
- SHIFT+TAB - focus the previous element, or wrap around to the last
See also DHTML style guide for dialogs.
Accessibility
- Follows the ARIA authoring practices
- In addition, to make content accessible that doesn't have focusable elements or is otherwise marked up properly, aria-describedby is set on the wrapper element, pointing at the id of the content element. That tells the screenreader to read the content of the dialog when opened, in addition to the title (via aria-labelledby).
4 - Markup & Style:
(only used prior to implementation)
5 - Latest version of plugin:
http://view.jqueryui.com/master/demos/dialog/default.html
6 - Open issues being discussed
- Close button needs high-contrast support
- Needs core support for high-contrast mode, see https://github.com/jquery/jquery-ui/pull/217
- Resizing and dragging isn't keyboard accessible
- See Hans dialog branch with keyboard support for dragging and resizing, tabbing into the browser chrome, demo here
- Update/replace closeText option when a full internationalization solution is implemented.