PopupLayer

The PopupLayer component is a container for other JSF components that is displayed over the page contents. The size, placement, timeout value, and modality of the component can be easily customized. A convenient API lets you manage the display behavior of the PopupLayer component on the client side.


API Reference | Tag Reference
Online Demo

Key Features

Basic Configuration

To add the PopupLayer component to a page, use the <o:popupLayer> tag. As a container, the PopupLayer lets you place any kind of JSF components inside it to build its content. The display behavior of the PopupLayer component can be managed in two ways:

  • Showing and hiding the PopupLayer component without reloading the page using the show() and hide() JavaScript functions.

In the following example, when a user clicks the button, a PopupLayer component is shown. It contains a text and a button, which hides the PopupLayer when clicked.

<h:form id="form1">
  <input type="button" id="popupInvoker" value="Show PopupLayer"
         onclick="O$('form1:popupLayer1').show();"/>
  <o:popupLayer id="popupLayer1">
    <f:verbatim>
      Click here to hide this PopupLayer:<br/>
      <input type="button" value="Hide"
             onclick="O$('form1:popupLayer1').hide();"/>
    </f:verbatim>
  </o:popupLayer>
</h:form>
  • Showing and hiding the PopupLayer component using the visible server-only boolean attribute, which you can bind to a boolean property in the backing bean, like shown in the example below:
    <o:popupLayer id="popupLayer1"
                  visible="#{TestBean.popupLayerIsVisible}">
      <h:outputText value="Some text"/>
    </o:popupLayer>

Auto-Hiding

The PopupLayer component can be automatically hidden after a timeout. You can specify the timeout value in milliseconds in the hidingTimeout attribute. If the hidingTimeout attribute is "0" (default), the PopupLayer component will not be hidden automatically.

The PopupLayer component can be automatically dismissed when the user clicks outside of the component. You can define this behavior by setting the hideOnOuterClick attribute to "true" (by default, it is "false").

In the example below, if the user doesn't click the Hide button, the PopupLayer is hidden in 10000 milliseconds (or 10 seconds).

<o:popupLayer id="popupLayer1" hidingTimeout="10000">
  <f:verbatim>
    Click here to hide this PopupLayer:<br/>
    <input type="button" value="Hide"
           onclick="O$('form1:popupLayer1').hide();"/>
  </f:verbatim>
</o:popupLayer>

Positioning on the Page

By default, the PopupLayer's position is not defined and it is displayed as any other DHTML element with the absolute position: its placement may depend on CSS styles applied to it and/or the position on the page.

You can position the PopupLayer component explicitly by specifying its left and top attributes in pixels. These attributes define the x and y coordinates of the component's upper-left corner relative to the upper-left corner of the document or an absolutely positioned immediate container of the PopupLayer component. Note that the left and top attributes should indicate the number of pixels, without the postfix "px", like shown in the following example:

<o:popupLayer id="popupLayer1"
              left="300"
              top="200">
  <f:verbatim>
    Click here to hide this PopupLayer:<br/>
    <input type="button" value="Hide"
           onclick="O$('form1:popupLayer1').hide();"/>
  </f:verbatim>
</o:popupLayer>

Specifying the Size

By default, the PopupLayer component is adjusted to accommodate its content. However, you can set fixed width and height in any units (px, mm, em, etc) by using the width and height attributes.

The following example shows a fixed-sized PopupLayer component:

<o:popupLayer id="popupLayer1"
              width="200px"
              height="100px">
  <f:verbatim>
    Click here to hide this PopupLayer:<br/>
    <input type="button" value="Hide"
           onclick="O$('form1:popupLayer1').hide();"/>
  </f:verbatim>
</o:popupLayer>

Defining Modality

You can specify whether the PopupLayer component is shown in a modal state using the modal attribute (set to "false" by default). When a modal PopupLayer is displayed, all other components on the page are inaccessible until the PopupLayer component is hidden.

You can apply a style to the visible part of the page which is not covered by a modal PopupLayer by using the modalLayerStyle and modalLayerClass attributes. Note that this style is applied only if the modal attribute is set to "true". The following example shows a modal PopupLayer:

<o:popupLayer id="popupLayer1"
              modal="true"
              modalLayerStyle="background-color:silver;">
  <f:verbatim>
    Click here to hide this PopupLayer:<br/>
    <input type="button" value="Hide"
           onclick="O$('form1:popupLayer1').hide();"/>
  </f:verbatim>
</o:popupLayer>

By default, the modal PopupLayer can can be closed by pressing the Esc key. This behavior can be turned off by setting the hideOnEsc attribute to false.

Note that modality is provided by covering the page by a <div> element that is placed under a modal PopupLayer. By default, this <div> has the z-index equal to 300 and a modal PopupLayer has the z-index equal to 301. While this configuration works fine in the most cases, you can tune the z-indexes using the style and modalLayerStyle attributes, if needed.

Dragging Support

The PopupLayer component supports dragging. By default, the dragging feature is turned off. Turning this feature on by setting the draggable attribute to "true" allows the user to drag the PopupLayer component by its content area.

The following example shows a draggable PopupLayer component:

<o:popupLayer id="popupLayer1"
              left="300"
              top="200"
              draggable="true">
  <f:verbatim>
    Click here to hide this PopupLayer:<br/>
    <input type="button" value="Hide"
           onclick="O$('form1:popupLayer1').hide();"/>
  </f:verbatim>
</o:popupLayer>

Customizing Styles

You can customize a style for the PopupLayer component in the normal and rollover states using the style and styleClass and the rolloverStyle and rolloverClass attributes respectively.

Client-Side Events

The PopupLayer component supports a set of standard client-side events such as onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, onkeydown, onkeypress, onkeyup.

Note
Note that the keyboard events such as onkeydown, onkeypress, and onkeyup are fired only if the PopupLayer component contains elements that provide these events, for example HTMLInputText .

In addition, it provides a number of component-specific client-side events:

  • onshow - Occurs when the PopupLayer component is displayed on the client side.
  • onhide - Occurs when the PopupLayer component is hidden on the client side.
  • ondragstart - Occurs when the user starts dragging the PopupLayer component.
  • ondragend - Occurs when user finishes dragging the PopupLayer component.

Client-Side API

All client-side API methods are listed in the following table:

Method Description
show() Makes the PopupLayer component visible. This method is described in the Basic Configuration section.
showAtXY(x, y) Shows the PopupLayer component at the specified absolute x and y coordinates
showCentered() Shows the PopupLayer component in the center of the browser window.
hide() Hides the PopupLayer component.
setLeft(x) Sets the x coordinate that will be used by the show() function.
setTop(y) Sets the y coordinate that will be used by the show() function.
isVisible() Returns true if the PopupLayer is visible.
getLeft() Returns the x coordinate of the top-left corner of the PopupLayer in pixels.
getTop() Returns the y coordinate of the top-left corner of the PopupLayer in pixels.
OpenFaces