Window

The Window component is a window-styled container for other JSF components that is displayed over the page content. The Window component has a caption and a content area, it can be dragged around on the page, and resized. Besides, it has the usual maximize/restore, minimize and close buttons in the caption.


API Reference | Tag Reference
Online Demo

Key Features

General Configuration

The Window component can be added by placing the <o:window> tag onto the page and placing the window content components inside of that tag. The window's caption can be specified using the caption attribute for text captions or the "caption" facet for more complex caption content. Window visibility can be configured in two ways:

  • On the client-side, you can use show()/hide() and other functions (see the Client-Side API section) to change window's visibility.
  • On the server side you can use the visible boolean attribute that defines whether the window is visible when the page is laoded.

In the following example clicking a button shows a simple window using the show() client-side function.

<h:form id="form">
  <input type="button" value="Show Window"
         onclick="O$('form:window').show();"/>
  <o:window id="window">
    <f:facet name="caption">
      <h:outputText value="Window Caption"/>
    </f:facet>
  
    <h:outputText value="Window Content"/>
  <o:window>
</h:form>

The window that is shown in this example displays a caption with the caption buttons on the right that allow minimizing, maximizing and closing the window. The look and set of buttons can be customized as can be seen in the Customizing Caption Buttons section below.

The window's size and pisition can be customized with the width/height and top/left attributes respectively. By default, the window is displayed with a resizing capability, which means that the user can change window's size by dragging its edges and corners. The window can be made non-resizable by assigning false to its resizable attribute. The minimum window size during resizing is defined by the minWidth and minHeight attributes.

Analogously, there's the draggable attribute that can be used to make it impossible for the user to move the window. Note also that one more attribute is also applicable for draggable windows: specifying true in the draggableByContent attribute allows the window to be dragged not just by its caption but by the content area as well.

The visible window can be automatically dismissed when the user clicks outside of the component. This behavior is turned off by default and you can enable it by setting the hideOnOuterClick attribute to "true".

Showing a Modal Window

You can specify the Window component to be shown in a modal state by setting its modal attribute to "true". When this attribute is set this way and a window is shown (either using the client-side or server-side API) it is shown in the modal state, which means that all other components on the page are inaccessible until the window is closed. This behavior is often required for displaying modal dialogs in the application.

You can apply a style to the visible part of the page which is not covered by a modal window using the modalLayerStyle and modalLayerClass attributes. Note that this style is applied only if the modal attribute is set to "true". The following example defines a modal window with its modal layer filled with gray color:

<o:window modal="true" modalLayerStyle="background-color: silver;" ...>
  ...
</o:window>

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

Customizing Caption Buttons

By default the Window component displays the close button on the right side of its caption, along with minimize/maximize buttons in case of a resizable window, though a flexible way of customizing caption buttons is provided. Here are some of the scenarios that can be addressed:

  • changing the appearance of the standard minimize/maximize/close buttons;
  • changing the order and set of the default caption buttons;
  • specifying custom caption buttons near the default buttons;
  • moving the caption button(s) to the left side of a caption.

The basis for these customizations is the <o:captionArea> tag, which can be placed into the <o:window> tag to customize the set of buttons displayed in the caption. This tag has an alignment attribute, which defines the caption side where the area should be placed. It can take two values: "right" (the default value), and "left".

Adding the <o:captionArea> tag removes the default minimize/maximize/close buttons and allows you to customize the set of buttons by placing components inside of this tag. It is possible to place the following components into caption area tags:

  • <o:maximizeWindowButton> tag – displays the window maximizing button and allows customizing its appearance.
  • <o:minimizeWindowButton> tag – displays the window minimizing button and allows customizing its appearance.
  • <o:closeWindowButton> tag – displays the close button and allows customizing its appearance.
  • <o:captionButton> tag – displays a custom caption button that can be configured according to user's needs.
  • Any JSF component tags can also be placed into <o:captionArea>, which adds the flexibility of specifying virtually any controls in caption areas.

All of the button tags listed above have the following common attributes:

Attribute(s) Description
style, styleClass Define the general style applied to the button.
rolloverStyle, rolloverClass Define the style that is applied to the button when mouse cursor moves over it.
onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove The standard mouse events.
hint Specifies text for the tool tip that appears when mouse hovers over the button

In addition they have the following attributes of their own.

For <o:maximizeWindowButton>:

Attribute(s) Description
maximizeImageUrl, maximizeRolloverImageUrl, maximizePressedUrl Specify URLs for button's image when a window is in normal state: the general image, image that is shown when mouse hovers over the button, and image that is shown when mouse is pressed over the button but not released yet.
restoreImageUrl, restoreRolloverImageUrl, restorePressedUrl Specify URLs for button's image when a window is in maximized state: the general image, image that is shown when mouse hovers over the button, and image that is shown when mouse is pressed over the button but not released yet.

For <o:minimizeWindowButton>:

Attribute(s) Description
minimizeImageUrl, minimizeRolloverImageUrl, minimizePressedUrl Specify URLs for button's image when a window is in normal state: the general image, image that is shown when mouse hovers over the button, and image that is shown when mouse is pressed over the button but not released yet.
restoreImageUrl, restoreRolloverImageUrl, restorePressedUrl Specify URLs for button's image when a window is in minimized state: the general image, image that is shown when mouse hovers over the button, and image that is shown when mouse is pressed over the button but not released yet.

For <o:closeWindowButton> and <o:captionButton> tags:

Attribute(s) Description
imageUrl, rolloverImageUrl, pressedUrl Specify URLs for button's image: the general image, image that is shown when mouse hovers over the button, and image that is shown when mouse is pressed over the button but not released yet.

In addition to these attributes, the <o:captionButton> tag has the action attribute that specifies a server action that should be executed when the button is pressed, similar to the action attribute of the standard <h:commandButton> tag or the <o:commandButton> tag. In addition, like in the <o:commandButton> tag, it is possible to use built-in Ajax capabilities in the <o:captionButton> tag with the render and execute attributes (see the CommandButton documentation for details on using these attributes.

Here's an example of specifying a window closing button with a custom image and a hint:

<o:window ...>
    <o:captionArea>
      <o:minimizeWindowButton imageUrl="close.gif" hint="Close"/>
      <o:maximizeWindowButton imageUrl="close.gif" hint="Close"/>
      <o:closeWindowButton imageUrl="close.gif" hint="Close"/>
    <o:captionArea>
    ...
  </o:window>

You can also place more than one <o:captionArea> tags, which allows specifying custom areas on both caption sides.

Client-Side API

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

Method Description
show() Makes the Window component visible according to the modality state configured by the tag's modal attribute.
showAtXY(x, y) Shows the Window component at the specified absolute x and y coordinates.
showCentered() Shows the Window component in the center of the browser window.
hide() Hides the Window component.
setLeft(x) Sets the x coordinate of the window's top-left corner.
setTop(y) Sets the y coordinate of the window's top-left corner.
minimize() Minimizes the window, which means hiding the window content and retains just window's caption.
maximize() Maximizes the window, which makes the window occupy the whole browser's window.
restore() Restores original window size if the window is in minimized or maximized state.
isVisible() Returns true if the window is visible.
getLeft() Returns the x coordinate of the top-left corner of the window in pixels.
getTop() Returns the y coordinate of the top-left corner of the window in pixels.
isMinimized() Returns true if the window is currently in minimized state.
isMaximized() Returns true if the window is currently in maximized state.
isNormal() Returns true if the window is currently in normal (not minimized or maximized) state.
OpenFaces