The ICEfaces Tutorial
Table of Contents


Lesson: Using the panelPopup component

How to Use the ICEfaces Panel Popup Component

The panelPopup component can be used to display various types of content inside a draggable or modal dialog. These dialogs can be used on pages to display important information and options to the user in a manner similar to a standalone offline application.

The draggable popup panel can be moved around the page while still allowing interaction with the underlying page. The modal popup panel cannot be moved, and prevents page interaction by applying a partially transparent gray overlay. The following screenshot is of the ice:panelPopup component demo in component-showcase. Notice the draggable dialog covered by the modal popup.

panelPopup component in Component Showcase application

The panelPopup does not require any beans specific to the application. For example, static text can be used inside the body using only page level tools, which removes the complexity of bean setup. In the case of each example in this tutorial, a backing bean will only be used for the advanced demo.

The rest of this tutorial will discuss the following topics:

Creating a Draggable Panel Popup

The creation of a draggable panelPopup is simple and does not require any backend code or beans. In this next example the page contains a single draggable panelPopup with 2 outputText components inside the body.

The panelPopup component has 2 available facets (header and body) that can be filled and styled with content. The general layout of the panelPopup code is therefore similar to:

    <f:facet name="header">
        <!-- header content would go here -->
    </f:facet>
    
    <f:facet name="body">
        <!-- body content would go here -->
    </f:facet>

In this tutorial both facets contain outputText components, although it is possible to place other extended or custom components inside the popup panel. It is recommended that anything inside the facet be wrapped in either an ice:panelGroup or ice:panelGrid.

The facets would then be placed inside the ice:panelPopup tag. Because this section is demonstrating a draggable panelPopup, the draggable="true" attribute is added to the tag. This results in the following code:

    <ice:panePopup draggable="true">
        <f:facet name="header"/>
        <f:facet name="body"/>
    </ice:panelPopup>

The example page has added content inside the facets, as well as some minor styling to each component. Once completed, the draggable example looks similar to:

Draggable Panel Popup Example

The creation of this draggable dialog was very simple, as the draggablePanelPopup.jspx shows.

Download the demo:

The modal panelPopup is implemented in a similar manner to the draggable version, as the next tutorial will demonstrate.

Creating a Modal Panel Popup

The second option for a panelPopup is a modal approach. The modal dialog displays a partially transparent gray overlay around the panelPopup, which disables interaction with the page. This can be used to display critical messages that the user must acknowledge before continuing. The guidelines for a modal panelPopup are the same as the draggable version above. The only difference is the modal="true" attribute which must be set in the panelPopup tag, as shown below:

    <ice:panelPopup modal="true"/>

Using the draggable page as a basis, the new page modalPanelPopup.jspx can be created easily. When viewed, the page appears similar to:

Modal Panel Popup Example

Notice the blocking mechanism of the modal dialog, and also how the panelPopup cannot be dragged.

Download the demo:

The appearance of these 2 examples is rather generic and may not suit your application. The next section will demonstrate how to customize the CSS for panelPopup.

Customizing Panel Popup Styles

The popup styles can be customized by overriding the default CSS values. The first step is to create a new stylesheet and link to it in stylePanelPopup.jspx, as shown in the line below:

    <link href="./override.css" rel="stylesheet" type="text/css"/>

Next the default panel styles should be copied into the override sheet. To find the default styles, look inside the CSS normally linked to, which is ./xmlhttp/css/xp/xp.css. Copy all tab related styles into a new sheet, in our case override.css.

After this is done, you can begin customizing the styles. This demonstration changes the colors and borders of the header and body facet, as well as the panelPopup itself. The result is similar to the following:

Style Panel Popup Example

To achieve the color change of the panelPopup header, the following CSS changes were used:

.icePanelPopupHeader {
    background-color: #FF0000;
    color: #FFFFFF;
    text-align: center;
}

Other CSS changes were done to help display the possibilities, and since all the relevant classes are accessible the panelPopup style can be completely changed.

Download the demo:

As was mentioned earlier, complex components can be used inside of the panelPopup, and backing beans can be added to increase the functionality. The next tutorial will demonstrate both of these functions.

Advanced Draggable Panel Popup

This tutorial will focus on 2 features of panelPopup not previously covered. The first is the ability to have complex components inside the dialog, and the second is adding a backing bean and dynamic functionality.

Placing a new component inside the panelPopup is done by adding their tags, as shown below.

    <f:facet name="body">
        <ice:inputText value="Input Text"/>
        <ice:selectBooleanCheckbox value="true"/>
        <ice:outputLink value="">
            <ice:outputText value="Output Link"/>
        </ice:outputLink>
        <ice:selectInputDate/>
    </f:facet>

This would result in the dialog body containing an inputText, checkbox, link, and calendar. This demonstrates how flexible the contents of the popup panel can be. With this set of components inside the panelPopup, the page appears similar to:

Advanced Panel Popup Example

This section also demonstrates how to use backing beans with this component. As you can see from the screenshot, a close button (appears as ) has been added. This close button acts as a toggle to change the visibility of the panelPopup.

The bean PopupBean.java is used, and is bound in faces-config in the standard way (shown below for reference):

    <managed-bean>
        <managed-bean-name>popup</managed-bean-name>
        <managed-bean-class>
            com.icesoft.icefaces.tutorial.component.panelPopup.advanced.PopupBean
        </managed-bean-class>
        <managed-bean-scope>session</managed-bean-scope>
    </managed-bean>

Once this is done, a visible attribute is added to the panelPopup, which uses the backing bean value, as shown below.

<ice:panelPopup draggable="true" visible="#{popup.visible}"/>

The next step is to add 2 buttons to the page; one for opening a popup and one for closing the popup. These would be similar to the following:

<ice:commandButton image="images/close.gif" action="#{popup.closePopup}"/>
<ice:commandButton value="Open a Popup" action="#{popup.openPopup}"/>

The backing bean methods for these buttons and visibility attribute must now be written. The code for this is simple; the open method would toggle the visibility to true, and the close method would set it to false. For completeness, this is demonstrated below.

    public void closePopup() {
        visible = false;
    }
    
    public void openPopup() {
        visible = true;
    }

When these bindings and methods are complete, the page will allow opening and closing of the popup dialog, as can be seen in advancedPanelPopup.jspx

Download the demo:

As you can see it is trivial to add complex components and dynamic functionality to a popup panel.

Examples Using Panel Popups

Example Source Notes
Component Showcase Available in release bundles Panel Popup example which includes draggable and modal, as well as closing and opening a dialog.
Presenter Available on the demo site A panelPopup is used to confirm a user who wishes to pass moderator status.
panelPopup-draggable panelPopup-draggable source code Simple example of how to setup a basic draggable panelPopup component.
panelPopup-modal panelPopup-modal source code Example showing the modal type of panelPopup and the difference between a draggable dialog.
panelPopup-style panelPopup-style source code Demonstration of how easily and fully a panelPopup can be styled with custom CSS.
panelPopup-advanced panelPopup-advanced source code This example shows how complex components can be used, and how to tie a backing bean to the panelPopup.

The ICEfaces Tutorial
Table of Contents

Copyright 2006 ICEsoft Technologies Inc. All rights reserved.