### Create new RichFaces Documentation Jira issue

Summary
255 characters left
Description
Environment
This will launch the RichFaces Jira page - to complete your feedback please login if needed, and submit the Jira.

JBoss.org Community Documentation

- Prev
- Next

## 6.70. < rich:modalPanel >

### 6.70.1. Description

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.198. The <rich:modalPanel> component opens in closest to observer layer. All other layers are dimmed by blocking `<div>` element (gray on the picture).

### 6.70.2. Key Features

- 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.369. rich : modalPanel attributes

Attribute Name | Description
--- | ---
autosized | If "true" modalPanel should be autosizeable. Default value is "false".
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
domElementAttachment | Defines the DOM element, which stacking context will assimilate the modalPanel. Possible values: "body", "form", "parent". Default value is "body".
headerClass | CSS style(s) is/are to be applied to component header when this component is rendered
height | Attribute defines height of component. Default value is "200".
id | Every component may have a unique id that is automatically created if omitted
keepVisualState | If "true" modalPanel should save state after submission. Default value is "false".
label | A localized user presentable name for this component.
left | Attribute defines X position of component left-top corner. Default value is "auto".
minHeight | Attribute defines min height of component. Default value is "10". If the value is less then 10, a "IllegalArgumentException" exception is thrown.
minWidth | Attribute defines min width of component. Default value is "10". If the value is less then 10, a "IllegalArgumentException" exception is thrown.
moveable | if "true" there is possibility to move component. Default value is "true".
onbeforehide | HTML: script expression; before panel is hidden
onbeforeshow | HTML: script expression; before panel is opened
onhide | HTML: script expression; after panel is 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 | HTML: script expression; before panel is moved
onresize | HTML: script expression; panel is resized
onshow | HTML: script expression; after panel is opened
overlapEmbedObjects | If "true" modalPanel creates iframe to overlap embed objects like PDF on a page. Default value is "false".
rendered | If "false", this component is not rendered
resizeable | if "true" there is possibility to change component size. Default value is "true".
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. Default value is "false"
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. Default value is "auto".
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
trimOverlayedElements | Defines whether to trim or not elements inside modalPanel. Default value is "true"
visualOptions | Defines options that were specified on the client side
width | Attribute defines width of component. Default value is "300".
zindex | Attribute is similar to the standard HTML attribute and can specify window. Default value is "100". placement relative to the content

Table 6.370. 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

### 6.70.3. Creating the Component with a Page Tag

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 onclick="Richfaces.hideModalPanel('modalPanelID');" href="#">Hide</a>

    </rich:modalPanel>

    <a onclick="Richfaces.showModalPanel('modalPanelID');" href="#">Show</a>

    ...

### 6.70.4. Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlModalPanel;

    ...

    HtmlModalPanel myPanel = new HtmlModalPanel();

    ...

### 6.70.5. Details of Usage

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.371. 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

## Important:

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>.

## Note:

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 &lt;rich:modalPanel&gt; accepts different types of information:

            from simple text to iterative components such as &lt;rich:dataTable&gt;, etc.

            </p>

            <a onclick="Richfaces.hideModalPanel('pnl');" href="#">Hide</a>

        </rich:modalPanel>

    </a4j:form>

Here is what happening on the page:

Figure 6.199. <rich:modalPanel> with links

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 &lt;rich:modalPanel&gt; accepts different types of information:

            from simple text to iterative components such as &lt;rich:dataTable&gt;, etc.

            </p>

        </rich:modalPanel>

    </a4j:form>

The result:

Figure 6.200. <rich:modalPanel> with 'Close' control

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 heirarchy 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>`.

## Note:

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"`.

Here 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.

### 6.70.6. JavaScript API

Table 6.372. JavaScript API

Function | Description
--- | ---
show() | Opens the corresponding modalPanel
hide() | Closes the corresponding modalPanel

### 6.70.7. Facets

Table 6.373. Facets

Facet | Description
--- | ---
header | Define the header content
controls | Defines the control elements on the header

### 6.70.8. Look-and-Feel Customization

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

### 6.70.9. Skin Parameters Redefinition

Table 6.374. Skin parameters for a component

Skin parameters | CSS properties
--- | ---
generalBackgroundColor | background-color
panelBorderColor | border-color

Table 6.375. Skin parameters redefinition for a header element

Skin parameters | CSS properties
--- | ---
headerBackgroundColor | background-color
headerBackgroundColor | border-color

Table 6.376. Skin parameters redefinition for a header content

Skin parameters | CSS properties
--- | ---
headerSizeFont | background-color
headerTextColor | font-size
headerWeightFont | color
headerFamilyFont | font-family

Table 6.377. Skin parameters redefinition for a body element

Skin parameters | CSS properties
--- | ---
generalSizeFont | font-size
generalTextColor | color
generalFamilyFont | font-family

### 6.70.10. Definition of Custom Style Classes

Figure 6.201. <rich:modalPanel> class name

The screenshot shows the classes names for defining different elements.

Table 6.378. 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:

Figure 6.202. Redefinition styles with predefined classes

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:

Figure 6.203. Redefinition styles with own classes and styleClass attributes

As it could be seen on the picture above,the font style for header was changed.

### 6.70.11. Relevant Resources Links

Vizit 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);

- "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.

- Prev6.69. < rich:messages >
- Top of page
- Front page
- Next6.71. < rich:orderingList >