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

6.10.1. <rich:modalPanel> available since 3.0.0

expand all
6.10.1.1. Description
6.10.1.2. Key Features
6.10.1.3. Details of Usage
6.10.1.4. Reference Data
6.10.1.5. Relevant Resources Links

The component implements a modal window that blocks user interaction with the main application while active.


Position the <rich:modalPanel> on the screen by specifying coordinates of it's top-left corner. Set values for "top" and "left" attributes in pixels for Y and X coordinates correspondingly. By default the component is autopositionable.

The modal window can be moved and resized by the end user. To disable those features (which are enabled by default) set "moveable" and "resizeable" attributes to false. Resizing may be limited by specifying window's minimal sizes with the "minWidth" and "minHeight" attributes.

To open and close the <rich:modalPanel> use one of three JS API functions (offset to the "Reference Data" below in this chapter):


<a onclick="Richfaces.showModalPanel('pnl');" href="#">Show ModalPanel</a>
<a4j:form>
      <rich:modalPanel id="pnl" >
            <a onclick="Richfaces.hideModalPanel('pnl');" href="#">Hide ModalPanel</a>
      </rich:modalPanel>
</a4j:form>

The result:


Besides client ID it is possible to pass other parameters while opening and closing the <rich:modalPanel> with the JS API function. For example, you can pass top and left indents or panel size:


<a onclick="Richfaces.showModalPanel('pnl', {top:'10px', left:'10px', height:'400px'});">Show ModalPanel</a>

Also the <rich:modalPanel> allows to handle its own opening and closing events on the client side. Custom parameters passed with JS API are also obtained in this case:


<rich:modalPanel onshow="alert(event.parameters.param1)">
      ...
</rich:modalPanel>

The component can restore its previous state (including position on the screen) after submitting and reloading. Set "keepVisualState" to true to submit and pass <rich:modalPanel> current parameters to a new page. The "showWhenRendered" boolean attribute is used in cases when component should be rendered after first page loading.

The "trimOverlayedElements" boolean attribute can be used to determine if the modal panel will expand to show other components inside it. Set the attribute to false to ensure components are not cut off.

To understand sense of the "domElementAttachment" attribute it is necessary to understand what is stacking context and how it works in the HTML makeup. Since each positioned or z-indexed element (CSS position:absolute or relative and z-index:*any integer different from 0*) form their own stacking context the <rich:modalPanel> rendered as a child of such element may be overlapped with an element that appears later in HTML hierarchy or assimilated with <body> stacking context (basic for HTML page). Not so fast! To make the <rich:modalPanel> rendered in "closest" to an observer layer and avoid such overlapping, the component was designed in way when it is always being automatically assimilated with <body> with a very high rendering layer (z-index). But our panel should be assimilated with <body> not always, because of some side effects that take place in this case. The "domElementAttachment" attribute helps to reassign the panel to its 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>.

Notes:

If the "domElementAttachment" value is not body then some overlapping may occur.

To avoid overlapping by an embed object (inserted with HTML <embed> tag) set the "overlapEmbedObjects" to true.

The "label" attribute is a generic one. It provides an association between a component and message the component produces. This attribute defines 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 this attribute you can replace the last parameter substitution token shown in the message. For example, DoubleRangeValidator.MAXIMUM or ShortConverter.SHORT.

The <rich:modalPanel> supports two facets. The header facet defines header and text label on it:


...
<rich:modalPanel id="pnl">
      <f:facet name="header">
            <h:outputText value="I'm 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 ModalPanel</a>
</rich:modalPanel>
...

The result:


The controls facet places any control on a header, defines image, style and function for it. For example, "Close" control:


<rich:modalPanel id="pnl">
      ...
      <f:facet name="controls">
            <h:graphicImage value="/pages/close.png" style="cursor:pointer" onclick="Richfaces.hideModalPanel('pnl')" />
      </f:facet>
        ...
</rich:modalPanel>

The result:


An example of using <h:commandButton> within the <rich: modalPanel>:


<a4j:form>
      <rich:modalPanel>
            <h:form>
                  <h:commandButton value="Test" action="#{TESTCONTROLLER.test}" />
            </h:form>
      </rich:modalPanel>
</a4j:form>

Table of <rich:modalPanel> attributes.






You can find all necessary information about style classes redefinition in Definition of Custom Style Classes section.

Visit ModalPanel page at RichFaces Livedemo for examples of component usage and their sources.

Useful articles:

If you have any questions or ideas regarding the <rich:modalPanel> tell about them at the RichFaces Users Forum.