The XForms Dialog Module
__NUMBEREDHEADINGS__
- Document title:
- The XForms Dialog Module
- Editors
- Nick Van den Bleeken, Inventive Designers
- Abstract
This document, developed by the Forms Working Group, specifies the
dialog
element which can be used to aggregate other form controls into a single aggregated user interface component that can be displayed to the user at a certain point in time to either present information or request input.- Status of this Document
- This is a live wiki document. Although it often reflects the best understanding of the editors and members of the Working Group, it may be inaccurate and has not necessarily been reviewed. If you need a stable copy, use the most recent official version: http://www.w3.org/TR/xformsdialog.
Copyright © 2010 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
Overview
A dialog
element is a top level container form control that allows a form author to aggregate other form controls into a single aggregated user interface component that can be displayed to the user at a certain point in time, to present either information or request input.
The elements and attributes included in this module are:
Element | Attributes | Minimal Content Model |
dialog | Common, UI Common, level?, hide(xsd:boolean) | group|switch|repeat|UI Common)* |
show | Common, Events, Action Common, dialog(xsd:IDREF) | dialog |
hide | Common, Events, Action Common, dialog(xsd:IDREF) | dialog |
Example:
<xforms:dialog id="my-dialog"> <xforms:label>Please enter your information</xforms:label> <xforms:input ref="first-name"> <xforms:label>First Name:</xforms:label> </xforms:input> <xforms:input ref="last-name"> <xforms:label>Last Name:</xforms:label> </xforms:input> <xforms:input ref="e-mail"> <xforms:label>E-mail:</xforms:label> </xforms:input> <xforms:trigger> <xforms:label>Submit</xforms:label> <xforms:hide ev:event="DOMActivate" dialog="my-dialog"/> </xforms:trigger> </xforms:dialog>
A graphical browser might render the above dialog
as follows:
The dialog Element
Common Attributes: Common, UI Common
Special Attributes:
- level
- Author-optional attribute, containing a dialog level identifier, one of ("modeless"|"modal"|QNameButNotNCName). The default is "modal" if the attribute is not specified. This specification does not define behavior for QNameButNotNCName values.
- hide
- Author-optional, indicating if the processor should provide a way to hide the dialog. The default value is
true
. On a graphical browser an "x" could be shown in the dialog title bar when hide is set totrue
. If you specifyhide="false"
, then you should provide a way to hide the dialog, for instance by having you own "Close" button inside the dialog. This is typically useful when you want to force users to enter some data before proceeding and you don't want them to cancel the current operation by closing the dialog.
When a modal dialog is shown the user can't interact with any UI control on the page outside of that dialog. A graphical browser could visualize this by shielding the document with a partially transparent mask when a modal dialog is shown.
The dialog generates an implicit group that contains the content elements (e.g. form controls, groups, switches, repeats and host language elements). When the dialog is shown the implicit group is relevant, when the dialog is hidden the implicit group is non-relevant.
Note: It should be possible to show a new dialog from within a modal dialog.
The show Element
This XForms Action begins by invoking the deferred update behavior. This action then shows the specified dialog by dispatching an xforms-dialog-show event to the dialog that is being shown.
Special Attributes:
- dialog
- Author-optional reference to a
dialog
element. Thedialog
to select is specified by this attribute or by the child elementdialog
.
Note:
Whether the IDREF is obtained from the dialog attribute or element, the IDREF may not uniquely identify the desired dialog if the dialog element bearing the matching ID resides in a repeating construct such as element repeat. The general method described in 4.7 Resolving ID References in XForms is used to determine the desired run-time dialog object.
Note:
This action affects deferred updates by performing deferred update in its initialization.
The dialog Element Child of the show Element
This section defines a child element of show
named dialog
that is an alternate means of providing the identity of a dialog element to show.
Element: dialog
Common attributes: None
Special Attributes:
- value
- Author-optional attribute containing an expression to evaluate using the in-scope evaluation context. To obtain the dialog identity, the result of the expression is processed as if by call to the
string
conversion function as described in the expression module. An empty string is used if the evaluation fails.
Content: PCDATA
The dialog to be shown by the show
action is given by the dialog
attribute or the dialog
element. If both are given, the element takes precedence.
The hide Element
This XForms Action begins by invoking the deferred update behavior. This action then hides the specified dialog by dispatching an xforms-dialog-hide event to the dialog that is being hidden.
Special Attributes:
- dialog
- Author-optional reference to a
dialog
element. Thedialog
to select is specified by this attribute or by the child elementdialog
.
Note:
Whether the IDREF is obtained from the dialog attribute or element, the IDREF may not uniquely identify the desired dialog if the dialog element bearing the matching ID resides in a repeating construct such as element repeat. The general method described in 4.7 Resolving ID References in XForms is used to determine the desired run-time dialog object.
Note:
This action affects deferred updates by performing deferred update in its initialization.
The dialog Element Child of the hide Element
This section defines a child element of hide
named dialog
that is an alternate means of providing the identity of a dialog element to hide.
Element: dialog
Common attributes: None
Special Attributes:
- value
- Author-optional attribute containing an expression to evaluate using the in-scope evaluation context. To obtain the dialog identity, the result of the expression is processed as if by call to the
string
conversion function as described in the expression module. An empty string is used if the evaluation fails.
Content: PCDATA
The dialog to be hide by the hide
action is given by the dialog
attribute or the dialog
element. If both are given, the element takes precedence.
The xforms-dialog-show Event
Dispatched in response to a show action executed with an existing dialog id.
Target:dialog
Bubbles: Yes
Cancelable: Yes
Context Info: none
Default Action: Show the dialog if it isn't shown already.
The default action for this event results in the following steps:
- Adjusts the shown state of the dialog.
- Makes the dialog available to the user.
The xforms-dialog-hide Event
Dispatched in response to a hide action executed with an existing dialog id.
Target: dialog
Bubbles: Yes
Cancelable: Yes
Context Info: none
Default Action: Hide the dialog if it isn't hidden already.
The default action for this event results in the following steps:
- Adjusts the shown state of the dialog.
- Makes the dialog unavailable to the user.