rich:modalPanel HtmlModalPanel

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

## 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 href="javascript:RichFaces.hideModalPanel('form:panel')">Hide</a>
        </rich:modalpanel>
    ...
        <a href="javascript:RichFaces.showModalPanel('form:panel')">Show</a>
    ...

## Creating the Component Dynamically Using Java

Example:

    import org.richfaces.component.html.HtmlModalPanel;
    ...
    HtmlModalPanel myPanel = new HtmlModalPanel();
    ...

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

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

New:

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

ModalPanel with links

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.gif"/>
        </rich:modalPanel>

The result is displayed here:

ModalPanel with control element

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 will be 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>
                            <t: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.

## JavaScript API

JavaScript API

Function | Description
--- | ---
Show() | Shows the corresponding tooltip
Hide() | Hides the corresponding tooltip

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

## Skin Parameters Redefinition

Skin parameters for a component

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

Skin parameters redefinition for a header element

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

Skin parameters redefinition for a header content

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

Skin parameters redefinition for a body element

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

## Definition of Custom Style Classes

Modal Panel class names

The screenshot shows the classes names for defining different elements.

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 and define necessary properties in them.

To change styles of particular <rich:modalPanel> components, define your own style classes in the corresponding <rich:modalPanel> attributes.

## Relevant Resources Links

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.