h2. 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.
{tip}See the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=dialogBean] of this component, complete with source code.{tip}
h2. Getting Started
{panel}
{code:xml|borderStyle=dashed} <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>
{code}
{panel}
h2. Attributes
{tip:title=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|http://www.icefaces.org/docs/v4_latest/ace/tld/ace/dialog.html].{tip}
{panel}
*modal* specifies whether the document should be shielded with a partially transparent mask.
{panel}
{panel}
*draggable* allows the user to drag the dialog using its header.
{panel}
{panel}
*resizable* makes the dialog resizable by its corners and sides.
{panel}
{panel}
*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.
{panel}
{panel}
*visible* can be used to toggle the visibility of the dialog from the server.
{panel}
h2. Event Listeners
None.
h2. Client Behavior Events
| close | Fired when the panel is closed (default event). |
h2. JavaScript API
h4. 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:
{panel}
{code:xml|borderStyle=dashed} <h:commandButton onclick="sampleDialog.show();" ... />
...
<ace:dialog widgetVar="sampleDialog" ... >
...
<h:commandButton onclick="sampleDialog.hide();" ... />
...
</ace:dialog>
{code}
{panel}
h4. 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.
{code}widget = ice.ace.instance('frm:myDialog');{code}
To illustrate this change, see the before and after code example below.
h5. Before (ICEfaces 3 API)
{panel}
{code:xml|borderStyle=dashed}
<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">
...
{code}{panel}
h5. After (ICEfaces 4 API)
{panel}{code:xml|borderStyle=dashed}
<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">
...
{code}{panel}
{tip}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.{tip}
h4. 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.
h2. Keyboard and ARIA Support
The following ARIA roles are supported: dialog, button.
h2. CSS Classes
The following markup represents the basic HTML structure of the component and the CSS classes it uses.
{code:xml}
<!-- 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>
{code}
h2. 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.
{panel}
*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.
{panel}
h2. Additional Resources
_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.
{tip}See the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=dialogBean] of this component, complete with source code.{tip}
h2. Getting Started
{panel}
{code:xml|borderStyle=dashed} <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>
{code}
{panel}
h2. Attributes
{tip:title=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|http://www.icefaces.org/docs/v4_latest/ace/tld/ace/dialog.html].{tip}
{panel}
*modal* specifies whether the document should be shielded with a partially transparent mask.
{panel}
{panel}
*draggable* allows the user to drag the dialog using its header.
{panel}
{panel}
*resizable* makes the dialog resizable by its corners and sides.
{panel}
{panel}
*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.
{panel}
{panel}
*visible* can be used to toggle the visibility of the dialog from the server.
{panel}
h2. Event Listeners
None.
h2. Client Behavior Events
| close | Fired when the panel is closed (default event). |
h2. JavaScript API
h4. 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:
{panel}
{code:xml|borderStyle=dashed} <h:commandButton onclick="sampleDialog.show();" ... />
...
<ace:dialog widgetVar="sampleDialog" ... >
...
<h:commandButton onclick="sampleDialog.hide();" ... />
...
</ace:dialog>
{code}
{panel}
h4. 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.
{code}widget = ice.ace.instance('frm:myDialog');{code}
To illustrate this change, see the before and after code example below.
h5. Before (ICEfaces 3 API)
{panel}
{code:xml|borderStyle=dashed}
<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">
...
{code}{panel}
h5. After (ICEfaces 4 API)
{panel}{code:xml|borderStyle=dashed}
<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">
...
{code}{panel}
{tip}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.{tip}
h4. 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.
h2. Keyboard and ARIA Support
The following ARIA roles are supported: dialog, button.
h2. CSS Classes
The following markup represents the basic HTML structure of the component and the CSS classes it uses.
{code:xml}
<!-- 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>
{code}
h2. 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.
{panel}
*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.
{panel}
h2. Additional Resources