The XForms Dialog Module

A dialog element is a container form control that allows a form author to aggregate other form controls into a single, aggregate user interface component that can be displayed to the user at a certain point in time to present information or request input.

The elements and attributes included in this module are:

Example:

• <xforms:dialog ref="user-info" 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, Node Set Binding

Special Attributes:

level: Author-optional attribute, which an only be used appearance is set to full, 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.

close: Author-optional, which an only be used appearance is set to full, 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 close is set to true. If you specify close="false", then you should provide a way to close 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.

Although a dialog element receives events associated with model item properties of a bound node, such as xforms-readonly and xforms-invalid, no special behavior is imparted by the dialog onto the content elements in the dialog as a direct result of any model item property. The model item property relevant of a bound data node can indirectly affect the content of the dialog via its contribution to deciding whether the dialog is relevant or non-relevant. The non-relevance of a dialog is determined in the same way as it is for group and similarly applies to the entire content, additionally a dialog is considered non-relevant when the dialog is not showed. Also, as with group, when a dialog becomes non-relevant, it must receive event xforms-disabled and then the XForms action handlers that are listening for events on the non-relevant dialog must be disabled. As well, when a non-relevant dialog changes to being relevant, the XForms action handlers that listen for events on the dialog must become enabled and then the switch must receive the event xforms-enabled. Additionally a non-cancelable xforms-dialog-close will be sent to the dialog if a dialog receives an xforms-disabled event, which will close the dialog as its default action.

The content elements (e.g. form controls, groups, switches, repeats and host language elements) within a non-showed dialog behave as if they were in a non-relevant group (see 9.1.1 The group Element). Similarly, content elements in a dialog that gets showed behave as if they were in a group that has become relevant.

Note: It should be possible to open 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-open event to the dialog that is being opened.

Note: Whether the IDREF is obtained from the dialog attribute or element, the IDREF may not uniquely identify the desired case if the case 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 case object.

Note:This action affects deferred updates by performing deferred update in its initialization.

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-close event to the dialog that is being closed.

The xforms-dialog-open Event

Dispatched in response to: xforms:show action executed with an existing dialog id.

Target: dialog

Bubbles: Yes

Cancelable: Yes

Context Info: none

Default Action: Open the dialog if it isn't open already.

The default action for this event results in the following steps:

1. Adjusts the showed state of the dialog.
2. Makes the dialog available to the user.

Note: The dialog can become visible without receiving an xforms-dialog-open event at that moment. When the dialog is made unavailable due to the relevance of a data node and the data node becomes relevant again no xforms-dialog-open event is dispatched at that moment.

The xforms-dialog-close Event

Dispatched in response to: xforms:hide action executed with an existing dialog id.

Target: dialog

Bubbles: Yes

Cancelable: Yes

Context Info: none

Default Action: Close the dialog if it isn't closed already.

The default action for this event results in the following steps:

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

Note: The dialog can become unavailable without receiving an xforms-dialog-close event when the data node becomes of the dialog becomes non-relevant.

TODO

• Add Dialog to the list of container controls all over the spec (like switch an repeat)

• Say something about appearance minimal

Pending questions

Answered questions

• Can the same dialog be showed multiple times?
• * No, this will be handled with components (it isn't the same dialog if it is another iteration in a repeat)
• When a dialog becomes non-relevant we should hide the dialog, but what is the event sequence? When is the xforms-dialog-close Event dispatched.
• * No xforms-dialog-close Event is dispatched, only the xforms-diabled event is dispatched to the dialog and all its content elements, just like group

CategoryXForms12