type: widget

release: 1.5

status: in development

documentation: http://docs.jquery.com/UI/Dialog

demo: http://jqueryui.com/demos/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.

 

There is an existing dialog widget in jQuery UI that will need some re-factoring and should leverage the new position utility and Buttons:

http://jqueryui.com/demos/dialog

http://docs.jquery.com/UI/Dialog

 

---

 

2 - Visual Design:

 

 

---

 

 

3 - Functional Specifications/Requirements:

 

Options/Methods/Events

• options:
  • autoOpen (boolean, default: true)
    • when set to true, this is the equivalent of calling .dialog('open') immediately after initializing the dialog
  • bgiframe (boolean, default: false)
    • to be removed - an equivalent of bgiframe will be added to UI and will be used automatically
  • buttons (hash, default: {})
    • a set of buttons to include in the button pane, with associated functions to execute on click
    • format: { buttonText: function() {} }
    • see discussion about additional features
  • closeOnEscape (boolean, default: true)
    • when set to true, pressing escape while the dialog has focus will close the dialog
  • closeText (string, default: 'close')
    • text to be displayed for the close button
    • to be modified when UI fully supports i18n
  • dialogClass (string, default: null)
    • class to add to the dialog wrapper element
  • draggable (boolean, default: true) 
    • when set to true, the dialog is draggable by the titlebar
    • requires draggable plugin
  • height (pixel value or 'auto', default: 'auto')
  • maxHeight (pixel value, default: null)
    • maximum height allowed when the dialog is resizable
  • maxWidth (pixel value, default: null)
    • maximum width allowed when the dialog is resizable
  • minHeight (pixel value, default: 150)
    • minimum height allowed when the dialog is resizable
  • minWidth (pixel value, default: 150)
    • minimum width allowed when the dialog is resizable
  • modal (boolean, default: false)
    • when set to true, an overlay is placed over the document when the dialog is opened, preventing access to other elements on the page.
  • position (mixed, default: 'center')
    • define options
    • will use position when available
  • resizable (boolean or string, default: true)
    • accepts any valid resizable handle option value or true/false to enable/disable resizing
    • requires resizable plugin
  • stack (boolean, default: true)
    • when set to true, if multiple dialogs are open at the same time, they will stack stack on click/drag
  • width (pixel value, default: 300)
  • zIndex (integer, default: 1000)
• methods:
  • close
    • closes the dialog, can be cancelled through the beforeclose event
  • destroy
    • destroys the dialog and reverts the element back to its original state
  • isOpen
    • determines if the dialog is currently open
  • moveToTop
    • moves the dialog to the front of all other dialogs
  • open
    • opens the dialog
• events:
  • open (event type: dialogopen)
    • original event types: none
    • triggered immediately after the dialog opens
  • focus (event type: dialogfocus)
    • original event types: none
    • triggered when the dialog gains focus (opened, moveToTop is called, or titlebar is clicked)
  • beforeclose (event type: dialogbeforeclose)
    • original event types: click, keypress
    • triggered immediately before the dialog closes, returning false will prevent the dialog from closing
  • close (event type: dialogclose)
    • original event types: click, keypress
    • triggered immediately after the dialog closes
  • dragStart (event type: dialogdragStart)
    • original event types: dragstart (mousedown)
    • triggered immediately after the user starts dragging the dialog
  • drag (event type: dialogdrag)
    • original event types: drag (mousemove)
    • triggered repeatedly as the user drags the dialog
  • dragStop (event type: dialogdragStop)
    • original event types: dragstop (mouseup)
    • triggered immediately after the user stops dragging the dialog
  • resizeStart (event type: dialogresizeStart)
    • original event types: resizestart (mousedown)
    • triggered immediately after the user starts resizing the dialog
  • resize (event type: dialogresize)
    • original event types: resize (mousemove)
    • triggered repeatedly as the user resizes the dialog
  • resizeStop (event type: dialogresizeStop)
    • original event types: resizestop (mouseup)
    • triggered immediately after the user stops resizing the dialog

 

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
• dialogs are placed at the end of the body on open to ensure proper display in IE
• 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
• returning false in the beforeclose callback will prevent the dialog from closing
• focus will be set to the dialog on open
  • focus will be set on the first tabbable element in the content are or the first button in the button pane
  • if there are no tabbable elements, focus will be set on the dialog wrapper div
    • the wrapper div must have a tabindex of -1 to be focusable
      • this will not work in Safari <= 3, but will work in Safari 4
• tabbing through elements will be contained within the dialog (including titlebar and button pane)
  • F6 will toggle focus between the dialog and the rest of the page
  • if there are multiple dialogs open, F6 should cycle between the dialogs and the page
• calling open when the dialog is already open will result in no action being taken
• calling close when the dialog is already closed will result in no action being taken

 

See DHTML style guide for dialogs.

 

---

 

4 - Markup & Style:

 

4.1 Initial markup examples

 

(Pre-enhanced HTML markup structure that will be transformed into the final widget. There may be multiple possible HTML markup options per widget: for example, for a slider, radiobuttons, inputs or selects could all be used. )

 

4.2 Recommended transformed HTML markup demo with html and css (live view of svn):

 

View Demo Page: http://jqueryui.com/demos/dialog

 

 

 

 

     (The HTML markup structure and classes that will be used by the scripts in the enhanced version) 

 

4.3 Markup & style browser QA status

 

As of 12/12/08, static markup for this widget renders correctly in the following browsers.  (Correct rendering = true to design, with only small differences across browsers owing to differences in support of rounded corners, and native OS form element and font rendering.)

 

Please update this list as more browsers / platforms are tested.

 

	XP	Vista	Mac 10.5
IE 6
IE 7
IE 8 beta
Firefox 2.0.0.18
Firefox 3.0.4
Safari 3.2
Opera 9.1
Opera 9.62
Chrome 1.0

 

 

 

 

 

 

 

 

 

 

 

 

 

    

4.4 Accessibility recommendation

 

(Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices) 

 

4.5 CSS & Theme

 

(Description of the CSS classes to be used for all states, how custom theming and Themeroller support will work.) 

 

---

 

5 - Latest version of plugin:

 

(Link to the latest version in the jQuery UI trunk here)

 

---

 

6 - Open issues being discussed

 

(Use this area to place things that we're hashing out like featuresand options we're not sure we should include, questions about how this fits into UI and relates to other widgets and utilities, known problems, whether features should be broken across multiple releases, etc.)

 

---