Dialog

Overview

Since 3.0

The dialog component is used to pop up a dialog. You can use it as a container for other contents/components. Attributes allow you to specify whether it be modal, draggable, resizable and closable.

See the ICEfaces Showcase Live Demo of this component, complete with source code.

Getting Started

            <ace:dialog id="dialog"
                               header="A sample dialog overview example"
                               widgetVar="sampleDialog"
                               closable="false"
                               modal="true"
                               draggable="false"
                               showEffect="clip"
                               hideEffect="explode"
                               width="400">

                <h:form id="inputForm">
                    <h:panelGrid columns="2" width="100%">
                        <h:outputLabel id="firstNameLabel" for="firstNameInputField" value="First Name:"/>
                        <h:inputText id="firstNameInputField" value="#{dialogBean.firstName}" />

                        <h:outputLabel id="lastNameLabel" for="lastNameInputField" value="Last Name:"/>
                        <h:inputText id="lastNameInputField" value="#{dialogBean.lastName}"/>
                    </h:panelGrid>

                    <h:panelGrid width="100%" style="text-align: center;">
                        <h:commandButton value="Click me once done with input" onclick="sampleDialog.hide();"/>
                    </h:panelGrid>
                </h:form>

            </ace:dialog>

Attributes

TagLib Documentation
This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available here.

modal specifies whether the document should be shielded with a partially transparent mask.

draggable allows the user to drag the dialog using its header.

resizable makes the dialog resizable by its corners and sides.

closable specifies whether the dialog should have a close button in the header. If set to false you can still close the dialog through the visible attribute or JavaScript API.

visible can be used to toggle the visibility of the dialog from the server.

Event Listeners

None.

Client Behavior Events

close

Fired when the panel is closed (default event).

JavaScript API

ICEfaces 3.x

The client side dialog object is exposed through the global variable name specified in the widgetVar attribute. You can use the hide() and show() methods to hide and show the dialog on the client side:

            <h:commandButton onclick="sampleDialog.show();" ... />
            ...
            <ace:dialog widgetVar="sampleDialog" ... >
                ...
                <h:commandButton onclick="sampleDialog.hide();" ... />
                ...
            </ace:dialog>

ICEfaces 4+

The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use.

widget = ice.ace.instance('frm:myDialog');

To illustrate this change, see the before and after code example below.

Before (ICEfaces 3 API)

<h:commandButton id="show" value="Show Dialog" onclick="sampleDialog.show();" type="button"/>

<ace:dialog id="myDialog"
            header="A sample dialog overview example"
            widgetVar="sampleDialog"
            width="400">
...

After (ICEfaces 4 API)

    
<h:commandButton id="show" value="Show Dialog" onclick="ice.ace.instance('myDialog').show();" type="button"/>
            
<ace:dialog id="myDialog"
            header="A sample dialog overview example"
            width="400">
...

The ice.ace.instance approach for showing dialogs requires the full client id of the dialog to be specified, such as "j_idt77:qrDialog" instead of just "qrDialog". To reduce the complexity of working with complete IDs for showing/hiding dialogs it may be preferable in some cases to locate dialogs inside of forms with <h:form prependId="false"> specified.

Client-side vs. Server-side

Avoid using both the visible attribute and client side API to open and close the dialog. If you do, you have to make sure that the open/closed state is in sync by using the appropriate server side listeners. In the above example you would have to use the actionListener to do that. The close event of the upper right close button can be listened to by a child <ace:ajax> tag.

If there is a chance that the dialog would be re-rendered from the server while open, you must use the visible attribute and use a variable for its value, because the default is false and the next time it's rendered it would be like visible = "false" always.

Keyboard and ARIA Support

The following ARIA roles are supported: dialog, button.

CSS Classes

The following markup represents the basic HTML structure of the component and the CSS classes it uses.

<!-- Root container -->
<div>
	<div class="ui-dialog ui-widget ui-widget-content ui-corner-all [user defined classes]" style="[user defined styles]">
		<!-- Header -->
		<div class="ui-dialog-titlebar ui-widget-header ui-corner-all ui-helper-clearfix">
			<span class="ui-dialog-title">Title</span>
			<!-- Close button -->
			<a class="ui-dialog-titlebar-close ui-corner-all">
				<span class="ui-icon ui-icon-closethick">close</span>
			</a>
		</div>
		<!-- Body -->
		<div class="ui-dialog-content ui-widget-content">
		</div>
	</div>
</div>

Known Issues

The following effects have been disabled due to some conflicts:

'pulsate' on hide for all browsers .
'highlight' and 'bounce' on hide for IE7 and IE8.
'explode' on show for IE7 and IE8.

Dialog closes unexpectedly at the first request when having cleared the cache and pasted the URL
This situation can occur because JSF needs to add or remove two hidden fields to the form (javax.faces.ViewState and javax.faces.ClientWindow) when loading the page in this way. The domdiff causes a full form update, and all the components inside the form are re-initialized to their original state, which in the case of the dialog is closed. This situation can be avoided by redirecting to the page where this occurs by creating a jsp file whose contents are only <% response.sendRedirect("<target-page>.jsf"); %>. This can also be avoided if the visible property is set to true in the server when the dialog is opened.