Confirmation

The Confirmation component is a DHTML modal window containing a main instruction and two buttons that allow the user to confirm or reject execution of some operation. The Confirmation works asynchronously, i.e. it does not stop a script's execution when called: it returns "false" and waits for user input. When the user clicks OK, the Confirmation component runs the JavaScript function that was intended for confirmation.

Key Features

Invoking the Confirmation

To add the Confirmation component to the page, use the <q:confirmation> tag. You can invoke the Confirmation component in two ways:

  • Assign the Confirmation component to a JavaScript event of any given component. In this case, the Confirmation component will be shown when the event it is associated with occurs. The registered handlers for the event will be invoked only if the user confirms the action (it is assumed that the event handler is not changed on the client side).
  • Display the Confirmation component by a JavaScript function. In this case, the Confirmation component is invoked from JavaScript code, and when the user confirms the action, the function passed as a parameter to the Confirmation component will be invoked.

To assign the Confirmation component to a component's JavaScript event, you should specify the invokerId and invokerEventName attributes of the Confirmation. The invokerId attribute is the id of a JSF component or id of any HTML element, whose event is listened to. It should be defined in the same way as the for property of the standard HTMLOutputLabel:

  • First, the Confirmation component tries to find the component specified in invokerId. If the component is not found, the client-side id is used for getting the corresponding component on the client side.
  • If no component is found and invokerId is prefixed with ':', it means that it is an absolute path and is used as the client-side id of the component, but without ':'. This is especially useful for HTML elements that are not related to JSF components.
  • In other cases, invokerId is regarded as a relative path to the component that is placed in the same container as the Confirmation component.

The invokerEventName string attribute is the name of a JavaScript function or event that should be confirmed before execution.

In the example below, when the user clicks the Delete button, the Confirmation component catches the onclick event and gets displayed. If the user clicks OK in the Confirmation, the action specified in the onclick event of the Delete button is performed. If the user clicks Cancel, nothing will happen.

<h:form id="form1">
  <h:commandButton id="button1"
                   value="Delete"
                   onclick="deleteSelectedItems()"/>
  <q:confirmation id="conf1"
                  invokerId="form1:button1"
                  invokerEventName="onclick"/>
</h:form>

When you need to call the Confirmation component from JavaScript code, use the following functions:

  • q_runConfirmedFunction (confirmationId, func)
    Where:
    • confirmationId String id of the Confirmation component.
    • func Variant that defines the JavaScript function's pointer or String with the JavaScript code that should be executed.
  • q_runConfirmedFunctionByName (confirmationId, funcName, parameters)
    Where:
    • confirmationId String id of the Confirmation component.
    • funcName String name of the JavaScript function.
    • parameters Array of parameters to be passed to the function in funcName.

Note that in these functions, you should use the client-side id of the Confirmation component.

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

<h:form id="form1">
  <q:confirmation id="conf1"/>
  <input id="button1"
         type="button"
         value="Delete"
         onclick="q_runConfirmedFunctionByName('form1:conf1',
                  'deleteSelectedItems', []);"/>
</h:form>

Customizing the Content Area

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 the main instruction text, 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 this text, 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 is opened, 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 by 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 captionText 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:

<q:confirmation id="conf"
                invokerId="button1"
                invokerEventName="onclick"
                captionText="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()"/>

Also, there is an ability to set text for the main instruction, supplementary details and buttons by using the JavaScript function q_setConfirmationTexts (confirmationId, messageText, detailsText,okButtonText, cancelButtonText). Note that in this function, you should use the client-side id of the Confirmation component.

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.

<q:confirmation id="conf"/>
<h:outputLink id="linkInvoker" value=""
              onclick="q_setConfirmationTexts('form1:conf', 'Delete selected items?',
                                       'Click Yes to delete selected items',
                                       'Yes', 'No');
                q_runConfirmedFunctionByName('form1:conf',
                                             '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 can be 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 that calls it. If the Confirmation is aligned with the component it was called from (invoker), it is displayed right under this component. It is important that the invoker and the Confirmation component should not be placed in different containers with absolute positions.

Setting the Display Behavior

When the Confirmation component is opened, it retains this state until the user performs an action within it. You can modify this behavior by hiding the Confirmation component even if the user didn't do anything. Using the closeOnOuterClick attribute set to "true" closes the Confirmation component when the user clicks anywhere outside it. By default, this attribute is set to "false".

The Confirmation component can be dragged around the page. By default, the dragging feature is turned off. You can enable it using 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 Confirmation, the Confirmation component is closed with no action executed.

<q:confirmation id="conf"
                invokerId="button1"
                invokerEventName="onclick"
                width="250px"
                alignToInvoker="true"
                draggable="true"
                closeOnOuterClick="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 using the style, styleClass, rolloverStyle, and rolloverStyleClass attributes. Also, you can define styles for any part of the Confirmation component using the following attributes:

Part of Confirmation Attributes
Title bar captionStyle, captionClass
Area where instructions are located middleAreaStyle, rolloverMiddleAreaStyle, middleAreaClass, rolloverMiddleAreaClass
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:

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

And here is the result:

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

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:

Confirmation object functions Public functions Description
runConfirmedFunction(func) q_runConfirmedFunction (confirmationId, func) Runs the function that is specified in the func parameter.
runConfirmedFunctionByName(funcName, parameters) q_runConfirmedFunctionByName (confirmationId, funcName, parameters) Runs the function whose name is specified in the funcName parameter with an array of parameters passed to the function in funcName.
setTexts(headerText, detailsText, yesButtonText, noButtonText) q_setConfirmationTexts (confirmationId, headerText, detailsText, yesButtonText, noButtonText) Sets the main instruction, supplementary text, buttons text for the Confirmation component with the id specified in the confirmationId parameter.

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

QuipuKit