The XForms Dialog Module

From W3C XForms Group Wiki (Public)

__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:

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 to true. If you specify hide="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. The dialog to select is specified by this attribute or by the child element dialog.

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. The dialog to select is specified by this attribute or by the child element dialog.

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:

  1. Adjusts the shown state of the dialog.
  2. 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:

  1. Adjusts the shown state of the dialog.
  2. Makes the dialog unavailable to the user.