Confirmation

The Confirmation component allows users to confirm or reject critical actions before their execution. It is displayed over other page elements like a modal dialog and can be attached to a client-side event of any component or invoked from JavaScript explicitly. The Confirmation component has a lot of options to customize its appearance and provides a flexible invocation mechanism.


API Reference | Tag Reference
Online Demo

Key Features

Invoking the Confirmation

To add the Confirmation component to the page, use the <o:confirmation> tag. The most common way of using the Confirmation component is attaching it to some event of some particular component, which will result a confirmation to be shown prior to executing a handler for the specified event. For example you can attach the Confirmation component to the "click" event of a <h:commandButton> component to show a confirmation before performing that button's action. Note that the event string should be without the "on" prefix, for example "click" instead of "onclick".

You can attach the Confirmation component to another component in two ways. The first way is to place the <o:confirmation> tag right into a component whose action should be confirmed. The event whose execution should be confirmed can be customized using the event attribute. The default value for this attribute is "onclick".

<h:commandButton value="Delete" onclick="deleteSelectedItems()">
  <o:confirmation event="click"/>
</h:commandButton>

Note that the event attribute in this example is declared for demonstration purposes only, and since "onclick" is the default value for this attribute, its declaration can simply be omitted.

The second way of attaching the Confirmation component is placing the <o:confirmation> tag besides the component (or tag) whose action should be confirmed, and binding the Confirmation to that component explicitly using the for attribute of the <o:confirmation> tag. This way can be used for attaching to JSF components as in the first approach, though this way also allows binding to events of arbitrary HTML elements.

The for attribute should be assigned with the id of a JSF component or id of any HTML element, whose event should be listened to:

  • The first way of specifying this attribute is for referencing JSF components and it is similar to the way of specifying the for attribute of the standard <h:outputLabel> and <h:message> tags. It can either be an "absolute" identifier that begins with a colon and includes ids of all naming container parents, such as ":form:button1", or it can be a relative identifier that refers to another child in the same naming container, for example "button2". The formal rules of finding the component by identifier are described in API reference for the UIComponent.findComponent() method.
  • The second way of specifying this attribute is for referring HTML elements rather than JSF components. Referring to HTML elements is similar to referring JSF components with an absolute identifier – you just need to prepend actual element id with a colon symbol. For example in order to refer a an HTML button tag declared as <input id="myHtmlButton" type="button" value="Test"/> you should use the ":myHtmlButton" value of the for attribute.

As for the case with inserting <o:confirmation> into the associated component, the event attribute specifies the event whose execution should be confirmed. Here's an example of attaching to a HTML "span" tag.

<span id="editData" ondblclick="editData()">...</span>
<o:confirmation for=":editData"
                event="dblclick"/>

In addition to the automatic attaching of the Confirmation component to another component, it is also possible to invoke Confirmation programmatically using the client-side API, which allows making a flexible logic for showing confirmation dialogs. When using the Confirmation component's client-side API you would usually need to turn off automatic attachment mechanism to fully control the behavior with explicit JavaScript invocations. To do this you should declare the standalone attribute and assign it the true value. When you need to call the Confirmation component from JavaScript code, you can use the runConfirmedFunction(func) function. The the func is a parameter that specifies a function that should be executed.

In the following example, when the onclick event occurs, the Confirmation component with "form1:confirmaion" client-side id is called. When the user clicks OK, the deleteSelectedItems() function is executed.

<h:form id="form1">
  <o:confirmation id="confirmation" standalone="true"/>
  <input id="button1"
         type="button"
         value="Delete"
         onclick="O$('form1:confirmation').runConfirmedFunction(function() {deleteSelectedItems();})"/>
</h:form>

Customizing Caption Buttons

By default Confirmation component displays the close button on the right side of its caption, 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 close button;
  • specifying custom caption buttons near the close button;
  • 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:confirmation> 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 close button 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:closeWindowButton> tag – displays the close button and allows customizing its appearance.
  • <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: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 confirmation 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 confirmation 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 confirmation 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 confirmation 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:

<h:commandButton value="Delete" onclick="deleteSelectedItems()">
  <o:confirmation event="click">
    <o:captionArea>
      <o:closeWindowButton imageUrl="close.gif" hint="Close"/>
    <o:captionArea>
  </o:confirmation>
</h:commandButton>

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

Customizing the Content Area

Customizing the Content with Attributes

By default, the Confirmation component shows a main instruction, supplementary text below, and an icon with an exclamation mark on the left. The default instruction text is "Confirm your action". To change it, use the message attribute. If you don't want to show any instruction, set an empty string for this attribute. The text specified in the message attribute is bold by default. You can customize a style for the main instruction in the normal and rollover states using the messageStyle, messageClass, rolloverMessageStyle, and rolloverMessageClass attributes.

The default supplementary text is "Press OK to perform the action". To change it, use the details attribute. If you want no supplementary text to be displayed, set an empty string for this attribute. You can specify a style for the supplementary text in the normal and rollover states with the detailsStyle, detailsClass, rolloverDetailsStyle, and rolloverDetailsClass attributes.

Note
The text set by the message and details attributes is not escaped and can contain HTML tags. Any user-entered text should be escaped prior to being used in these attributes.

To set a different graphic for the icon to the left of the main instuction, use the messageIconUrl attribute. You can specify whether the icon is to be displayed using the showMessageIcon attribute. By default, this attribute is set to "true".

The Confirmation component has two buttons labeled "OK" and "Cancel" by default. You can specify the button texts by using the okButtonText and cancelButtonText attributes. When the Confirmation component opens, one of the buttons is always focused. By default, it is the OK button. You can change this setting by using the defaultButton attribute. Note that this attribute is an enumeration, where the valid values are "ok" for the OK button and "cancel" for the Cancel button. You can customize styles for the OK and Cancel buttons in the normal and rollover states using the following attributes:

Button Attributes
OK okButtonStyle, rolloverOkButtonStyle, okButtonClass, rolloverOkButtonClass
Cancel cancelButtonStyle, rolloverCancelButtonStyle, cancelButtonClass, rolloverCancelButtonClass

By default, the Confirmation component has no title bar. To add it, use the caption attribute. You can customize a style for the title with the captionStyle and captionClass attributes. If you want to have a Close button on the title bar, set the showCloseWindowButton attribute to "true" (by default, it is "false"). To change the default icon of the Close button, use the closeButtonImageUrl attribute.

The following example shows some of the attributes defining the content of the Confirmation component:

<o:confirmation id="conf"
                for="button1"
                event="click"
                caption="Confirm"
                message="Delete selected items?"
                details="Click Yes to delete selected items"
                showMessageIcon="false"
                okButtonText="Yes"
                cancelButtonText="No"/>
<input id="button1"
       type="button"
       value="Delete"
       onclick="deleteSelectedItems()"/>

Customizing the Content with Arbitrary Components

Another way to customize the content areas of the Confirmation component is by using facets. There are four facets to configure four Confirmation areas: "message", "details", "icon", "caption". Here is an example of using all of these facets:

<o:confirmation id="conf"
                okButtonText="Yes"
                cancelButtonText="No">
  <f:facet name="message">
    <h:outputText value="Delete selected items?"/>
  </f:facet>
  <f:facet name="details">
    <h:panelGroup>
      <h:outputText value="Click Yes to delete selected items."/>
      <f:verbatim><br/></f:verbatim>
      <h:outputText value="Click No to cancel the action."/>
    </h:panelGroup>
  </f:facet>
  <f:facet name="caption">
    <h:outputText value="Confirm"/>
  </f:facet>
  <f:facet name="icon">
    <h:graphicImage url="warningIcon.gif"/>
  </f:facet>
</o:confirmation>

Note that customizing the Confirmation using facets has a priority over attributes.

Customizing the Content with a JavaScript Function

There is an ability to set text for the main instruction, supplementary details and buttons by using a JavaScript function setTexts(messageText, detailsText,okButtonText, cancelButtonText).

In the example below, the Confirmation component with the id "conf" uses the default values of the main instruction and buttons. However, when the user clicks the Delete button, the main instruction text and button labels are changed to the values specified in the JavaScript function before the Confirmation is displayed.

<o:confirmation id="conf" standalone="true"/>
<h:outputLink id="linkInvoker" value=""
              onclick="O$('form1:conf').setConfirmationTexts('Delete selected items?',

                                       'Click Yes to delete selected items',
                                       'Yes', 'No');
                O$('form1:conf').runConfirmedFunction(function(){deleteSelectedItems();});
                return false;">
  <h:outputText value="Remove"/>
</h:outputLink>

Configuring the Presentation

To set the size for the Confirmation component, use the width and height attributes, which you can set in pixels, centimeters, etc. By default, the Confirmation component has the width of 275 px and its height is defined by the content.

By default, the Confirmation component is displayed as a modal window in the center of the visible area of the page. There are a number of ways to specify the location of a Confirmation component:

  • Use the left and top attributes to locate the Confirmation component relative to the upper-left corner of the document or an absolutely positioned immediate container. You should indicate the number of pixels for both attributes without writing "px" or similar units. Note that the Confirmation component has absolute position and its left and top CSS style properties have the same effect as for any HTML element with absolute position.
  • Use the alignToInvoker boolean attribute to align the Confirmation component with the component calling it. If the Confirmation is aligned with the component it was called from (invoker), it is displayed right under this component. Note that if you use the alignToInvoker attribute, the for and event attributes should be specified too. It is important that the invoker and the Confirmation component should not be placed in different containers with absolute positions.

Setting the Display Behavior

There are two ways to close the confirmation dialog besides choosing between one of the OK/Cancel buttons or pressing the "close" caption button:

  • The user can press the Esc button to close the dialog, which is identical to choosing the "Cancel" option. This behavior can be turned off by setting the hideOnEsc attribute to false.
  • It is possible to let the user close the dialog (and thus implicitly chosing the "Cancel" option) by clicking outside of the dialog. This behavior is turned off by default, and can be turned on by setting the hideOnOuterClick attribute to "true".


The Confirmation component can be dragged around the page. By default, the dragging feature is turned off. You can enable it with the draggable attribute.

In the example below, the Confirmation component is aligned with the Delete button and has the width of 250 px. It can be dragged by the mouse. If the user clicks outside of the Confirmation component, it is closed with no action executed.

<o:confirmation id="conf"
                for="button1"
                width="250px"
                alignToInvoker="true"
                draggable="true"
                hideOnOuterClick="true"/>
<input id="button1"
       type="button"
       value="Delete"
       onclick="deleteSelectedItems()"/>

Customizing Styles

You can define a style for the Confirmation component when it is in the normal and rollover states with the style, styleClass, rolloverStyle, and rolloverStyleClass attributes. If you want to apply styles for a specific of the Confirmation component, use the following attributes:

Part of Confirmation Attributes
Title bar captionStyle, captionClass
Area where instructions are located contentStyle, rolloverContentStyle, contentClass, rolloverContentClass
Area where the icon is located iconAreaStyle, rolloverIconAreaStyle, iconAreaClass, rolloverIconAreaClass
Area where the buttons are located buttonAreaStyle, rolloverButtonAreaStyle, buttonAreaClass, rolloverButtonAreaClass

The following example shows the styles defined for all the parts of the Confirmation component:

captionStyle="border:2px solid red;"
contentStyle="border:2px solid blue;"
iconAreaStyle="border:2px solid orange;"
buttonAreaStyle="border:2px solid green;"

And here is the result:

By using the modalLayerStyle and modalLayerClass attributes, you can also apply a style to the visible part of the page which is not covered by the Confirmation component.

Client-Side Events

The Confirmation component supports a set of standard client-side events that can be customized to alter the component's behavior. These are onclick, ondblclick, onmousedown, onmouseover, onmouseup, onmouseout, onmousemove, onkeydown, onkeypress, onkeyup.

Client-Side API

The Confirmation component supports the following client-side API. All of them are described in the sections Invoking the Confirmation and Customizing the Content Area:

Method Description
runConfirmedFunction(func) Runs the function that is specified in the func parameter.
setTexts(headerText, detailsText, yesButtonText, noButtonText) Sets the main instruction, supplementary text, buttons text for the Confirmation component.

In addition to these functions, the Confirmation component supports all the functions of the PopupLayer component.

OpenFaces