Create new RichFaces Documentation Jira issue
This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.
JBoss.orgCommunity Documentation
The component implements a modal dialog window. All operations in the main application window are locked out while this window is active. Opening and closing the window is done through client JavaScript code.
Figure 6.74. The
<rich:modalPanel>
component opens in closest to observer layer.
All other layers are dimmed by blocking <div> element (gray on the picture).
Highly customizable look and feel
Support of draggable operations and size changes by you
Easy positioning for the modal dialog window
Possibility to restore of the previous component state on a page (including position on the screen) after submitting and reloading
The component is defined as a panel with some content inside that displays its content as a modal dialog. To call it and to close it, the client API for the window is used.
Table 6.106. Functions description
| Function | Description |
|---|---|
| Richfaces.showModalPanel (client Id) | Opens a window with a specified client Id |
| Richfaces.hideModalPanel (client Id) | Closes a window with a specified client Id |
| Richfaces.hideTopModalPanel () | Closes the current visible window at the top |
To work properly the <rich:modalPanel> should always be placed outside the original <h:form> and must include its own <h:form> for such cases like performing submissions from within the <rich:modalPanel>.
In order to avoid a bug in IE, the root node of the dialog is moved on the top of a DOM tree.
It's possible to add a "header" facet to the component to set the content for the header.
Example:
<a onclick="Richfaces.showModalPanel('pnl');" href="#">Show ModalPanel</a>
<a4j:form>
<rich:modalPanel id="pnl">
<f:facet name="header">
<h:outputText value="This is a panel header" />
</f:facet>
<p>The <rich:modalPanel> accepts different types of information:
from simple text to iterative components such as <rich:dataTable>, etc.
</p>
<a onclick="Richfaces.hideModalPanel('pnl');" href="#">Hide</a>
</rich:modalPanel>
</a4j:form>
Here is what happening on the page:
A facet named "controls" can be added to the component to place control elements on a header.
Example:
<a onclick="Richfaces.showModalPanel('pnl');" href="#">Show ModalPanel</a>
<a4j:form>
<rich:modalPanel id="pnl">
<f:facet name="header">
<h:outputText value="This is a panel header" />
</f:facet>
<f:facet name="controls">
<h:graphicImage value="/pages/close.png" style="cursor:pointer" onclick="Richfaces.hideModalPanel('pnl')" />
</f:facet>
<p>The <rich:modalPanel> accepts different types of information:
from simple text to iterative components such as <rich:dataTable>, etc.
</p>
</rich:modalPanel>
</a4j:form>
The result:
To understand the sence of "
domElementAttachment
" attribute you should understand the
stacking context in the division
element (<div>) HTML makeup. Since each
positioned or z-indexed element (in CSS position:
absolute or relative or z-index:
[any integer value different from 0]) form their own
stacking context the
<rich:modalPanel>
nested into such element may be overlapped with another
elements, which appear later in HTML hierarchy and assimilated with
basic stacking context (HTML <body>). To make the panel
rendered in closest to the observer layer and avoid such overlapping,
the component was designed in way when it is always being
automatically assimilated with <body> and
with a very high rendering layer (z-index). Due to some
side effects the
<rich:modalPanel>
should not always be assimilated with
<body> stacking context. The "
domElementAttachment
" attribute helps to reassign the panel to it
'parent' or
'form' element. If
'form' is used and no
parent form is available the panel is functioning as if it is
assimilated with <body>.
If " domElementAttachment " value is not 'body' then some overlapping may occur.
To manage window placement relative to the component, there are "left" and "top" attributes defining a window shifting relative to the top-left corner of the window.
Modal windows can also support resize and move operations on the client side. To allow or disallow these operations, set the "resizeable" and "moveable" attributes to "true" or "false" values. Window resizing is also limited by "minWidth" and "minHeight" attributes specifying the minimal window sizes.
Also you can use
"minWidth"
and
"minHeight"
attributes used as showModalPanel() arguments
in JavaScript options.
You can pass your parameters during modalPanel opening or closing. This passing could be performed in the following way:
Example:
Richfaces.showModalPanel('panelId', {left: auto, param1: value1});
Thus, except the standard modalPanel parameters you can pass any of your own parameters.
Also modalPanel allows to handle its own opening and closing events on the client side. The "onshow" attribute is used in this case.
The following example shows how on the client side to define opening and closing event handling in such a way that your own parameters could also be obtained:
Example:
onshow="alert(event.parameters.param1)"
Here, during modalPanel opening the value of a passing parameter is output.
More information about this problem could be found on the RichFaces Development Forum.
There is a possibility to restore of the previous component state on a page (including position on the screen) after submitting and reloading. The modalPanel has some special attributes like "showWhenRendered" and "keepVisualState" .
"showWhenRendered" - This boolean attribute is used if modalPanel should be rendered after first page loading.
"keepVisualState"
- Used if modalPanel should save state after submission.
If keepVisualState="true" then
parameters which modalPanel has during opening should be submitted and
passed to new page.
Example:
<a href="javascript:Richfaces.showModalPanel('pnl', {top:'10px', left:'10px', height:'400'});">Show</a>
Here, if you open modal dialog window using current link and after submits data then modalPanel destination and height on new loaded page is restored.
if you need the content of the modalPanel to be submitted - you need to remember two important rules:
modalPanel must have its own form if it has form elements (input or/and command components) inside (as it was shown in the example above)
modalPanel must not be included into the form (on any level up) if it has the form inside.
Simple example of using commandButton within modalPanel is placed below.
Example:
<a4j:form>
<rich:modalPanel>
<f:facet name="header">
<h:outputText value="Test" />
</f:facet>
<f:facet name="controls">
<h:commandLink value="Close" style="cursor:pointer" onclick="Richfaces.hideModalPanel('mp')" />
</f:facet>
<h:form>
<h:commandButton value="Test" action="#{TESTCONTROLLER.test}" />
</h:form>
</rich:modalPanel>
See also discussion about this problem on the RichFaces Users Forum.
The
"label"
attribute is a generic attribute. The
"label"
attribute provides an association between a component, and
the message that the component (indirectly) produced. This attribute
defines the parameters of localized error and informational messages
that occur as a result of conversion, validation, or other application
actions during the request processing lifecycle. With the help of this
attribute you can replace the last parameter substitution token shown
in the messages. For example, {1} for
"DoubleRangeValidator.MAXIMUM",
{2} for "ShortConverter.SHORT".
In RichFaces Cookbook article about Modal Panel there is information for those of you who would like to click on a details link in table and have it show a modal panel with information loaded from the server.
To avoid overlapping of the
<rich:modalPanel>
component on the page by any embed objects (inserted with HTML <EMBED> tag) set the
"overlapEmbedObjects"
attribute to "true".
Table of <rich:modalPanel> attributes.
Table 6.107. Component Identification Parameters
| Name | Value |
|---|---|
| component-type | org.richfaces.ModalPanel |
| component-class | org.richfaces.component.html.HtmlModalPanel |
| component-family | org.richfaces.ModalPanel |
| renderer-type | org.richfaces.ModalPanelRenderer |
| tag-class | org.richfaces.taglib.ModalPanelTag |
Table 6.108. JavaScript API
| Function | Description |
|---|---|
| show() | Opens the corresponding modalPanel |
| hide() | Closes the corresponding modalPanel |
Table 6.109. Facets
| Facet | Description |
|---|---|
| header | Define the header content |
| controls | Defines the control elements on the header |
Table 6.110. Classes names that define a component appearance
| Class name | Description |
|---|---|
| rich-modalpanel | Defines styles for a wrapper <div> element of a modalPanel |
| rich-mpnl-mask-div | Defines styles for a wrapper <div> element of a mask |
| rich-mpnl_panel | Defines styles for a modalPanel |
| rich-mp-container | Defines styles for a modalPanel container |
| rich-mpnl-resizer | Defines styles for a wrapper <div> element of a resizing element |
| rich-mpnl-shadow | Defines styles for a modalPanel shadow |
| rich-mp-content-table | Defines styles for a <table> element of a modalPanel |
| rich-mpnl-header | Defines styles for a modalPanel header |
| rich-mpnl-header-cell | Defines styles for a header cell |
| rich-mpnl-text | Defines styles for a wrapper <div> element of a header text |
| rich-mpnl-body | Defines styles for a content inside a modalPanel |
| rich-mpnl-controls | Defines styles for a wrapper <div> element of a modalPanel control |
Visit ModalPanel page at RichFaces Livedemo for examples of component usage and their sources.
Read the " An Introduction To JBoss RichFaces" tutorial by Max Katz to find out how the <rich:modalPanel> helps to edit and save changes for table entries.
Some articles at JBoss portal describing different aspects of <rich:modalPanel> usage:
"ModalPanelWizards" article describes how to create a typical wizard with the help of <rich:modalPanel> component (the same could also be found in the " How to organize wizards using the <rich:modalPanel> component?" chapter of RichFaces FAQ guide);
Refer to the "How to do a detail view modalPanel in a table" article in the RichFaces cookbook at JBoss Portal to find out how to build a table with details link clicking on which will display a modal panel with information loaded from the server.
"ModalPanelValidation" article gives examples of validation in <rich:modalPanel> (the same in the corresponding topic at RichFaces Users Forum);
"RichFacesPleaseWaitBox" article describes how to show a "Please wait" box and block the input while the Ajax request is being processed using combination of <a4j:status> and <rich:modalPanel> components.
