Window 2.x - roberts-sandbox/test-wiki-page-title GitHub Wiki

TOCSTART

TOCEND

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.

Online Demo

• Draggable
• Resizeable
• Can be made modal
• Built-in minimize, maximize, close functions
• Support for custom caption buttons
• Client-side API

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>
&lt;h:outputText value=<span class="code-quote">"Window Content"</span>/&gt;

<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 position 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. It is possible to restrict the area where the window can be moved using the containment attribute.

This attribute can take the following values:

• "document" – doesn't allow to move the window across document's boundaries;
• "viewport" – doesn't allow to move the window out of the current viewport (the currently visible portion of the document);
• "containingBlock" – doesn't allow to move the window out of its containing block (the nearest parent node which has its position CSS property equal to "absolute", "relative" or "fixed";
• "#clientSideId", where the clientSideId part is an arbitrary client-side element id – doesn't allow to move the window out of the element with the specified id.

The containment attribute can also be used to avoid displaying the window larger than the available space. This can be achieved using the containmentRole attribute, which can additionally be specified to define how the containment area defined by the containment attribute should be treated:

• "restrictMovement" – this is the default value, which as described above just makes it impossible for the user to move the window out of the containment area;
• "restrictSize" – contrary to the previous "restrictMovement" value, when this value is specified, the user will still be able to move the window out of the containment area, but, instead of this, when the window is shown, its size is checked, and if it is greater than the containment area then the window's size is reduced to be not larger than the containment area. Note that this attribute still does not affect the window's position, so if you require this functionality, it's useful to use the showCentered() client-side function which will ensure that the window will be shown inside of the containment area;
  "restrictMovementAndSize" – combines the functionality of the two previous values, which means that the window is shown not bigger than the containment area, and the user is not allowed to move the window out of the containment area.

By default the size of the window does not depend on the content displayed therein. In particular, if the size of the content exceeds the size of the window then the window displays the scroll-bars to be able to scroll through the entire content. It is possible, however, to make the window adjust its size to the size of its content automatically by setting its autosizing attribute to the value of "on". Note that if the window's dragging containment is specified using the containment attribute, then the automatically detected size is ensured not to exceed the size of the containment area. In some cases, such as when displaying long text paragraphs inside of a window, the content might not have its natural width (due to the fact that text can be wrapped at any point). In such cases, the window's width is detected as the width of its container – dragging containment, if specified, or a document. If the automatically-detected width is not acceptable, or if you'd like to avoid calculating width automatically, then you can specify the width attribute of <o:window> tag, which will "freeze" window's width, and only window's height will be detected automatically.

Note that when the autosizing feature is turned on, the window cannot be resized manually by the user, and the value of the resizable attribute is ignored.

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".

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.

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:

In addition they have the following attributes of their own.

For <o:maximizeWindowButton>:

For <o:minimizeWindowButton>:

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

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.

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