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.
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
Table 6.291. rich : modalPanel attributes
Attribute Name | Description |
---|---|
autosized | If 'true' modalPanel should be autosizeable |
binding | The attribute takes a value-binding expression for a component property of a backing bean |
controlsClass | CSS style(s) is/are to be applied to component controls when this component is rendered |
converter | Id of Converter to be used or reference to a Converter |
converterMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the converter message, replacing any message that comes from the converter |
headerClass | CSS style(s) is/are to be applied to component header when this component is rendered |
height | Attribute defines height of component |
id | Every component may have a unique id that is automatically created if omitted |
keepVisualState | If "true" modalPanel should save state after submittion |
label | A localized user presentable name for this component. |
left | Attribute defines X position of component left-top corner |
minHeight | Attribute defines min height of component |
minWidth | Attribute defines min width of component |
moveable | if "true" there is possibility to move component |
onbeforehide | Event must occurs before panel is hiding |
onbeforeshow | Event must occurs before panel is opening |
onhide | Event must occurs after panel closed |
onmaskclick | HTML: a script expression; a pointer button is clicked outside modalPanel |
onmaskcontextmenu | JavaScript handler to be called on right click outside modalPanel |
onmaskdblclick | HTML: a script expression; a pointer button is double-clicked outside modalPanel |
onmaskmousedown | HTML: a script expression; a pointer button is pressed down outside modalPanel |
onmaskmousemove | HTML: a script expression; a pointer button is moved outside modalPanel |
onmaskmouseout | HTML: a script expression; a pointer button is moved away modalPanel |
onmaskmouseover | HTML: a script expression; a pointer button is moved onto modalPanel |
onmaskmouseup | HTML: a script expression; a pointer button is released outside modalPanel |
onmove | Event must occurs before panel is moving |
onresize | Event must occurs than panel is resizing |
onshow | Event must occurs after panel opened |
rendered | If "false", this component is not rendered |
resizeable | if "true" there is possibility to change component size |
shadowDepth | Pop-up shadow depth for suggestion content |
shadowOpacity | HTML CSS class attribute of element for pop-up suggestion content |
showWhenRendered | If "true" value for this attribute makes a modal panel opened as default. |
style | CSS style(s) is/are to be applied when this component is rendered |
styleClass | Corresponds to the HTML class attribute |
top | Attribute defines Y position of component left-top corner |
tridentIVEngineSelectBehavior | How to handle HTML SELECT-based controls in IE 6? - "disable" - default, handle as usual, use disabled="true" to hide SELECT controls - "hide" - use visibility="hidden" to hide SELECT controls |
validator | MethodBinding pointing at a method that is called during Process Validations phase of the request processing lifecycle, to validate the current value of this component |
validatorMessage | A ValueExpression enabled attribute that, if present, will be used as the text of the validator message, replacing any message that comes from the validator |
value | The current value of this component |
valueChangeListener | Listener for value changes |
visualOptions | Defines options that were specified on the client side |
width | Attribute defines width of component |
zindex | Attribute is similar to the standard HTML attribute and can specify window placement relative to the content |
Table 6.292. 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 |
Here is a simple example as it could be used on a page:
Example:
...
<rich:modalPanel id="panel">
<f:facet name="header">
<h:outputText value="header" />
</f:facet>
...
<!--Any Content inside-->
...
<a href="javascript:RichFaces.hideModalPanel('form:panel')">Hide</a>
</rich:modalPanel>
...
<a href="javascript:RichFaces.showModalPanel('form:panel')">Show</a>
...
Example:
import org.richfaces.component.html.HtmlModalPanel;
...
HtmlModalPanel myPanel = new HtmlModalPanel();
...
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.293. 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 |
In order to avoid a bug in IE, the root node of the dialog is moved on the top of a DOM tree. However, you should have a separate form inside the modal panel if you want to perform submits from this panel.
It's possible to add a "header" facet to the component to set the content for the header.
Example:
...
<form jsfc="h:form" id="form">
<rich:modalPanel id="panel" width="400" height="300">
<f:facet name="header">
<h:outputText value="Modal Panel"/>
</f:facet>
<h:graphicImage value="/pages/california_large.png"/>
<a href="javascript:Richfaces.hideModalPanel('form:panel')">Close</a>
</rich:modalPanel>
<a href="javascript:Richfaces.showModalPanel('form:panel');">Open</a>
</form>
...
This defines a window with a particular size and ID. It includes one "Open" link. Clicking on this link makes the modal window content appear.
A facet named "controls" can be added to the component to place control elements on a header.
Example:
...
<rich:modalPanel id="mp">
<f:facet name="header">
<h:outputText value="Modal Panel"/>
</f:facet>
<f:facet name="controls">
<h:graphicImage value="/pages/close.png" style="cursor:pointer" onclick="Richfaces.hideModalPanel('mp')" />
</f:facet>
<h:graphicImage value="/pages/california_large.png"/>
</rich:modalPanel>
...
The result is displayed here:
To manage the placement of inserted windows, use the "zindex" attribute that is similar to the standard HTML attribute and can specify window placement relative to the content.
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.
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" and "onclose" attributes are 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('_panel', {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:
...
<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>
...
<h:form>
<!--Some other Page content-->
</h:form>
...
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”.
Table 6.294. JavaScript API
Function | Description |
---|---|
show() | Opens the corresponding modalPanel |
hide() | Closes the corresponding modalPanel |
For skinnability implementation, the components use a style class redefinition method. Default style classes are mapped on skin parameters.
There are two ways to redefine the appearance of all <rich:modalPanel> components at once:
Redefine the corresponding skin parameters
Add to your style sheets style classes used by a <rich:modalPanel> component
Table 6.295. Skin parameters for a component
Skin parameters | CSS properties |
---|---|
generalBackgroundColor | background-color |
panelBorderColor | border-color |
Table 6.296. Skin parameters redefinition for a header element
Skin parameters | CSS properties |
---|---|
headerBackgroundColor | background-color |
headerBackgroundColor | border-color |
Table 6.297. Skin parameters redefinition for a header content
Skin parameters | CSS properties |
---|---|
headerSizeFont | background-color |
headerTextColor | font-size |
headerWeightFont | color |
headerFamilyFont | font-family |
Table 6.298. Skin parameters redefinition for a body element
Skin parameters | CSS properties |
---|---|
generalSizeFont | font-size |
generalTextColor | color |
generalFamilyFont | font-family |
The screenshot shows the classes names for defining different elements.
Table 6.299. Classes names that define a component appearance
Class name | Description |
---|---|
rich-modalpanel | Defines styles for a wrapper <div> element of a modalpanel |
rich-mpnl_panel | Defines styles for a modalpanel |
rich-mpnl-mask-div | Defines styles for a wrapper <div> element of a mask |
rich-mpnl-resizer | Defines styles for a wrapper <div> element of a resizing element |
rich-mpnl-shadow | Defines styles for a modalpanel shadow |
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 |
In order to redefine styles for all <rich:modalPanel> components on a page using CSS, it's enough to create classes with the same names (possible classes could be found in the tables above) and define necessary properties in them.
Example:
...
.rich-mpnl-mask-div{
background-color:#fae6b0;
}
...
This is a result:
In the example the background color for mask was changed.
Also it’s possible to change styles of particular <rich:modalPanel> component. In this case you should create own style classes and use them in corresponding <rich:modalPanel> styleClass attributes. An example is placed below:
Example:
...
.myClass{
font-style:italic;
}
...
The "headerClass" attribute for <rich:modalPanel> is defined as it’s shown in the example below:
Example:
<rich:modalPanel ... headerClass="myClass"/>
This is a result:
As it could be seen on the picture above,the font style for header was changed.
Here you can see the example of <rich:modalPanel> usage and sources for the given example.
Information about wizards using the <rich:modalPanel> component could be found in the Wiki article and in the FAQ chapter of the guide.
Examples of validation in <rich:modalPanel> could be found in the Wiki article and on the RichFaces Users Forum.