11.4. <rich:popupPanel>

⁠11.4. `<rich:popupPanel>`

The <rich:popupPanel> component provides a pop-up panel or window that appears in front of the rest of the application. The <rich:popupPanel> component functions either as a modal window which blocks interaction with the rest of the application while active, or as a non-modal window. It can be positioned on the screen, dragged to a new position by the user, and re-sized.

⁠11.4.1. Basic usage

The <rich:popupPanel> does not require any compulsory attributes, though certain use cases require different attributes.

⁠11.4.2. Showing and hiding the pop-up

If show="true" then the pop-up panel will display when the page is first loaded.

The <rich:popupPanel> component can be shown and hidden manually using the show() and hide() methods from the JavaScript API. These can be implemented using two different approaches:

Using the <rich:componentControl> component. For details on the component, refer to Section 19.1, “<rich:componentControl>”.
Using the rich:component function. For details on the function, refer to Section 18.2, “rich:component”.

For explicit referencing when using the functions, the component can be given an id identifier.

Example 11.2, “<rich:popupPanel> example” demonstrates basic use of both the <rich:componentControl> component and the rich:component function to show and hide the <rich:popupPanel> component.

⁠

Example 11.2. <rich:popupPanel> example

<h:commandButton value="Show the panel">
    <rich:componentControl target="popup" operation="show" />
</h:commandButton>
...
<rich:popupPanel id="popup">
    <p><a href="#" onclick="#{rich:component('popup')}.hide()">Hide the panel</a></p>
</rich:popupPanel>

Important

The <rich:popupPanel> component is usually rendered in front of any other objects on the page. This is achieved by attaching the component to the <body> element of the page, and setting a very high "z-index" (the stack order of the object). This approach is taken because relatively-positioned elements could still overlap the pop-up panel if they exist at higher levels of the DOM hierarchy, even if their z-index is less than the <rich:popupPanel> component.

If the <rich:popupPanel> is to participate in submitting child components/behaviors, then a form element must be nested within the <rich:popupPanel>. Alternatively, if no overlapping elements exist, the <rich:popupPanel> component can be reattached to its original DOM element by setting domElementAttachment to either parent or form.

⁠11.4.3. Modal and non-modal panels

By default, the <rich:popupPanel> appears as a modal window that blocks interaction with the other objects on the page. To implement a non-modal window instead, set modal="false". This will allow interaction with other objects outside the pop-up panel.

⁠11.4.4. Size and positioning

The pop-up panel can be both re-sized and re-positioned by the user. The minimum possible size for the panel can be set with the minWith and minHeight attributes. These abilities can be deactivated by setting resizable or movable to false as necessary.

The pop-up panel can be automatically sized when it is shown if the autosized attribute is set to true.

Note

Embedded objects inserted into the HTML with the <embed> tag could be rendered in front of a <rich:popupPanel> component in some browsers. The <rich:popupPanel> component can be forcibly rendered in front of these objects by setting overlapEmbedObjects="true".

However, due to the additional script processing required when using the overlapEmbedObjects attribute, applications can suffer from decreased performance. As such, overlapEmbedObjects should only be set to true when <embed> or <object> tags are being used in the parent view. Do not set it to true for applications that do not require it.

⁠11.4.5. Header and controls

A panel header and associated controls can be added to the <rich:popupPanel> component through the use of facets. The header facet displays a title for the panel, and the controls facet can be customized to allow window controls such as a button for closing the pop-up. Example 11.3, “Header and controls” demonstrates the use of the facets.

⁠

Example 11.3. Header and controls

<h:commandLink value="Show pop-up">
    <rich:componentControl target="popup" operation="show" />
</h:commandLink>
...
<rich:popupPanel id="popup" modal="false" autosized="true" resizeable="false">
    <f:facet name="header">
        <h:outputText value="The title of the panel" />
    </f:facet>
    <f:facet name="controls">
        <h:graphicImage value="/pages/close.png" style="cursor:pointer" onclick="#{rich:component('popup')}.hide()" />
    </f:facet>
    <p>
        This is the content of the panel.
    </p>
</rich:popupPanel>

⁠
Figure 11.5. Header and controls

⁠11.4.6. Contents of the pop-up

The <rich:popupPanel> component can contain any other rich component just like a normal panel.

Contents of the <rich:popupPanel> component which are positioned relatively may be trimmed if they extend beyond the borders of the pop-up panel. For certain in-line controls this behavior may be preferable, but for other dynamic controls it could be undesirable. If the trimOverlayedElements attribute is set to false then child components will not be trimmed if they extend beyond the borders of the pop-up panel. For example, if using a calendar, select, or other pop-up component, set trimOverlayedElements="false".

⁠11.4.7. JavaScript API

The <rich:popupPanel> component can be controlled through the JavaScript API. The JavaScript API provides the following functions:

getTop(): Return the top co-ordinate for the position of the pop-up panel.
getLeft(): Return the left co-ordinate for the position of the pop-up panel.
moveTo(top,left): Move the pop-up panel to the co-ordinates specified with the top and left parameters.
resize(width,height): Resize the pop-up panel to the size specified with the width and height parameters.
show(): Show the pop-up panel.
hide(): Hide the pop-up panel.

⁠11.4.8. Reference data

component-type: org.richfaces.PopupPanel
component-class: org.richfaces.component.UIPopupPanel
component-family: org.richfaces.PopupPanel
renderer-type: org.richfaces.PopupPanelRenderer

⁠11.4.9. Style classes and skin parameters

⁠

Table 11.4. Style classes (selectors) and corresponding skin parameters

Class (selector)	Skin Parameters	Mapped CSS properties
`.rf-pp-btn` This class defines styles for the pop-up panel button.	No skin parameters.
`.rf-pp-shade` This class defines styles for the shading that covers the page when presenting a modal pop-up panel.	No skin parameters.
`.rf-pp-cntr` This class defines styles for the container for the pop-up panel.	`panelBorderColor`	border
	`generalBackgroundColor`	background
`.rf-pp-hdr` This class defines styles for the header of the pop-up panel.	`headerBackgroundColor`	background
`.rf-pp-hdr-cnt` This class defines styles for the content of the header.	`headerTextColor`	color
	`headerWeightFont`	font-weight
	`headerFamilyFont`	font-family
	`headerSizeFont`	font-size
`.rf-pp-cnt` This class defines styles for the content of the pop-up panel.	`generalTextColor`	color
	`generalFamilyFont`	font-family
	`generalSizeFont`	font-size
`.rf-pp-cnt-scrlr` This class defines styles for the scroll bars of the pop-up panel.	`generalBackgroundColor`	background
`.rf-pp-hndlr` This class defines styles for borders of the pop-up panel. The border handler is used to re-size the panel.	No skin parameters.
`.rf-pp-hndlr-t`, `.rf-pp-hndlr-b`, `.rf-pp-hndlr-l`, `.rf-pp-hndlr-r`, `.rf-pp-hndlr-tl`, `.rf-pp-hndlr-tr`, `.rf-pp-hndlr-bl`, `.rf-pp-hndlr-br` These classes define styles for the top, bottom, left, right, top-left, top-right, bottom-left, and bottom-right edges of the border handler.	No skin parameters.