Confirmation |
|||||||||||||||||||||||||||||
Developer’s Guide Home
Installation and Configuration Components Index Calendar Chart Confirmation Data Table Date Chooser Drop Down Field Dynamic Image Folding Panel Hint Label Popup Layer Suggestion Field Tab Set Tabbed Pane Tree Table Two List Selection Utility Components Validation Framework Tag Reference |
The Confirmation component is a DHTML modal window with 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 ConfirmationTo add the Confirmation component to the page, use the <q:confirmation> tag. You can invoke the Confirmation component in two ways:
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:
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:
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 AreaCustomizing the Content with AttributesBy 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 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:
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()"/> Customizing the Content with Arbitrary ComponentsAnother 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: <q: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> </q:confirmation> Note that customizing the Confirmation using facets has a priority over attributes. Customizing the Content with a JavaScript FunctionThere is an ability to set text for the main instruction, supplementary details and buttons by using a 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 PresentationTo 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:
Setting the Display BehaviorWhen 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 of 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".
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. <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 StylesYou 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:
The following example shows the styles defined for all the parts of the Confirmation component: 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: 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 EventsThe 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 APIThe Confirmation component supports the following client-side API. All of them are described in the sections Invoking the Confirmation and Customizing the Content Area:
In addition to these functions, the Confirmation component supports all the functions of the PopupLayer component. |
||||||||||||||||||||||||||||
© 2007 TeamDev Ltd. | ![]() |