Oracle® Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition) 11g Release 5 (11.1.1.6.3) Part Number E28163-03 |
|
|
PDF · Mobi · ePub |
This chapter describes how to create and use popup elements in secondary windows including dialogs, menus, and windows on JSF pages. The chapter also describes how to use the ADF Faces dialog framework to create dialogs with a separate page flow.
This chapter includes the following sections:
ADF Faces provides a set of rich client components for hiding and showing information in a secondary window. The popup
component is an invisible layout control, typically used in conjunction with other components to display inline (that is, belonging to the same page) dialogs, windows, and menus.
For example, Figure 13-1 shows a dialog box created by placing a dialog
component as a child to a popup
component. A user can enter search criteria and click OK to submit the entry, or exit the dialog by clicking Cancel or closing the dialog.
You can also use components within a popup to display contextual information related to another component. When so configured, the related component displays a small square. When moused over, the icon grows and also displays a note icon as shown in Figure 13-2.
When the user clicks the note icon, the associated popup displays its enclosed content.
ADF Faces also provides a dialog framework to support building pages for a process displayed separate from the parent page. This framework supports multiple dialog pages with a control flow of their own. For example, say a user is checking out of a web site after selecting a purchase and decides to sign up for a new credit card before completing the checkout. The credit card transaction could be launched using the dialog framework in an external browser window. The completion of the credit card transaction does not close the checkout transaction on the original page.
This dialog framework can also be used inline as part of the parent page. This can be useful when you want the pages to have a control flow of their own, but you don't want the external window blocked by popup blockers.
If your application uses the full Fusion technology stack, note that this dialog framework is integrated with ADF Faces Controller for use with ADF task flows. For more information, see the "Running a Bounded Task Flow in a Modal Dialog" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
The dialog
, panelWindow
, menu
, and noteWindow
components can all be used inside the popup
component to display inline popup elements, as shown in Table 13-1. When no child component exists for the popup
component, a very simple inline popup is displayed.
Table 13-1 Components Used with the popup Component
Component | Displays at Runtime |
---|---|
|
Displays its children inside a dialog and delivers events when the |
|
Displays its children in a window that is similar to a dialog, but does not support events. For more information, see Section 13.2.2, "How to Create a Panel Window." |
|
Displays a context menu for an associated component. For more information, see Section 13.2.3, "How to Create a Context Menu." |
|
Displays read-only information associated with a particular UI component. Note windows are used to display help and messages and are commonly shown on mouseover or on focus gestures. For more information, see Section 13.2.4, "How to Create a Note Window." ![]() |
|
Displays content inline. |
Both the dialog
and panelWindow
components support definition help, content displayed when a user moves the cursor over a help icon (a blue circle with a question mark). For more information, see Section 17.5, "Displaying Help for Components."
Typically, you use a command component in conjunction with the showPopupBehavior
tag to launch a popup element. You associate the showPopupBehavior
tag with the component it should launch. This tag also controls the positioning of the popup element (when needed).
In addition to being used with action events on command components, the showPopupBehavior
tag can be used in conjunction with other events, such as the showDetail
event and the selection
event. For more information, see Section 13.4, "Invoking Popup Elements."
By default, the content of the popup element is not sent from the server until the popup element is displayed. This represents a trade-off between the speed of showing the popup element when it is opened and the speed of rendering the parent page. Once the popup element is loaded, by default the content will be cached on the client for rapid display.
You can modify this content delivery strategy by setting the contentDelivery
attribute on the popup
component to one of the following options:
lazy
- The default strategy previously described. The content is not loaded until you show the popup element once, after which it is cached.
immediate
- The content is loaded onto the page immediately, allowing the content to be displayed as rapidly as possible. Use this strategy for popup elements that are consistently used by all users every time they use the page.
lazyUncached
- The content is not loaded until the popup element is displayed, and then the content is reloaded every time you show the popup element. Use this strategy if the popup element shows data that can become stale or outdated.
If you choose to set the popup
component's contentDelivery
attribute to lazy
or lazyUncached
, you can further optimize the performance of the popup
component and the page that hosts it by setting another popup
component attribute (childCreation
) to deferred
. This defers the creation of the popup
component's child components until the application delivers the content. The default value for the childCreation
attribute is immediate
.
Create a dialog when you need the dialog to raise events when dismissed. Once you add the dialog
component as a child to the popup
component, you can add other components to display and collect data.
By default, the dialog
component can have the following combination of buttons:
Cancel
OK
OK and Cancel
Yes and No
Yes, No, and Cancel
None
These buttons launch a dialogEvent
when clicked. You can add other buttons to a dialog using the buttonBar
facet. Any buttons that you add do not invoke the dialogEvent
. Instead, they invoke the standard actionEvent
. It is recommended that any of these buttons that you add have their partialSubmit
attribute set to true
. This makes sure that an actionEvent
invokes only on components within the dialog. However, you can add buttons and set their partialSubmit
attribute to false
if you set the af:popup
component's autoCancel
property's value to disabled
. Choosing this latter option (partialSubmit
set to false
) results in increased wait times for end users because your application reloads the page and reinitializes components on the page before it restores the popup
component's visibility (and by extension, the dialog
component). Note that you must set the command component's partialSubmit
attribute to true
if the af:popup
component's autoCancel
property's value is set to enabled
(the default value). For more information about the use of the af:popup
component's autoCancel
property, see Section 13.6, "Controlling the Automatic Cancellation of Inline Popups."
To create an inline dialog:
In the Component Palette, from the Common Components panel, drag and drop a Popup onto the JSF page.
Tip:
It does not matter where the popup
component appears on the page, as the position is driven by the component used to invoke the popup
. However, the popup
component must be within a form
component.
In the Property Inspector, expand the Common section and set the following attributes:
ContentDelivery: Select how the content is delivered to the component in the popup.
Tip:
Values of input components in a dialog are not reset when a user clicks the dialog's Cancel button. If the user opens the dialog a second time, those values will still display. If you want the values to match the current values on the server, then set the contentDelivery
attribute to lazyUncached
.
Animate: Select true
to enable animation. Animation is determined by configuration in the trinidad-config.xml
file and by its skin properties (for more information, see Section A.6.2.1, "Animation Enabled"). You can override this setting by selecting false
.
LauncherVar: Enter a variable to be used to reference the launch component. This variable is reachable only during event delivery on the popup or its child components, and only if the EventContext is set to launcher
.
EventContext: Set to launcher
if the popup is shared by multiple objects, for example if the dialog within the popup will display information for the selected row in a table. Setting this attribute to launcher
makes the row clicked current before the event listener is called, and returns data only for that row. For more information, see Section 13.2.5, "What Happens at Runtime: Popup Component Events."
Optionally, in the Property Inspector, expand the Other section and set a value for the AutoCancel property to determine the automatic cancel behavior. For more information, see Section 13.6, "Controlling the Automatic Cancellation of Inline Popups."
From the Component Palette, drag and drop a Dialog as a direct child to the popup
component.
In the Property Inspector, expand the Common section and set the following attributes:
Type: Select the built-in partial-submit command buttons you want to display in your dialog.
For example, if you set the type
attribute to yesNoCancel
, the dialog will display Yes, No, and Cancel buttons. When any of these buttons are pressed, the dialog dismisses itself, and the associated outcome (either ok
, yes
, no
, or cancel
) is delivered with an event. Ok, yes, and no outcomes are delivered with the dialogEvent
. Cancel outcomes are sent with the PopupCanceled
event. You can use the appropriate listener property to bind to a method to handle the event, using the outcome to determine the logic.
Tip:
A dialog will not dismiss if there are any ADF Faces messages with a severity of error or greater.
Title: Enter text to be displayed as the title on the dialog window.
CloseIconVisible: Select whether or not you want the Close icon to display in the dialog.
Modal: Select whether or not you want the dialog to be modal. Modal dialogs do not allow the user to return to the main page until the dialog has been dismissed.
Resize: Select whether or not you want users to be able to change the size of the dialog. The default is off
.
StretchChildren: Select whether or not you want child components to stretch to fill the dialog. When set to first
, the dialog stretches a single child component. However, the child component must allow stretching. For more information, see Section 8.2.1, "Geometry Management and Component Stretching."
Note:
If you set Resize to on
or set StretchChildren to first
, you must also set ContentWidth and ContentHeight (see Step 8). Otherwise, the size will default to 250x250 pixels.
Expand the Appearance section and set the text attributes.
Instead of specifying separate button text and an access key, you can combine the two, so that the access key is part of the button text. Simply precede the letter to be used as an access key with an ampersand (&).
For example, if you want the text for the affirmative button to be OK, and you want the O in OK to be the access key, enter &OK
.
Expand the Behavior section and if needed, enter a value for the dialogListener attribute. The value should be an EL expression method reference to a dialog listener method that will handle the event.
For example, suppose you create a dialog to confirm the deletion of an item. You might then create a method on a managed bean similar to the deleteItem
method shown in Example 13-1. This method accesses the outcome from the event. If the outcome is anything other than yes
, the dialog is dismissed. If the outcome is yes
(meaning the user wants to delete the item), the method then gets the selected item and deletes it.
Example 13-1 Handler for dialogEvent That Deletes an Item
public void deleteItem(DialogEvent dialogEvent) { if (dialogEvent.getOutcome() != DialogEvent.Outcome.yes) { return; } // Ask for selected item from FileExplorerBean FileItem selectedFileItem = _feBean.getLastSelectedFileItem(); if (selectedFileItem == null) { return; } else { // Check if we are deleting a folder if (selectedFileItem.isDirectory()) { _feBean.setSelectedDirectory(null); } } this.deleteSelectedFileItem(selectedFileItem); }
Example 13-2 shows how the dialogListener
attribute is bound to the deleteItem
method.
Example 13-2 Binding the dialogListener attribute to a Method
<af:dialog title="#{explorerBundle['deletepopup.popuptitle']}"
type="yesNo"
dialogListener="#{explorer.headerManager.deleteItem}"
id="d1">
The dialogEvent
is propagated to the server only when the outcome is ok
, yes
, or no
. You can block this if needed. For more information, see Section 5.3.5, "How to Prevent Events from Propagating to the Server.")
If the user instead clicks the Cancel button (or the Close icon), the outcome is cancel
, the popupCancel
client event is raised on the popup
component, and any other events (including the dialogEvent
) are prevented from getting to the server. However, the popupCancel
event is delivered to the server.
If you want to set a fixed size for the dialog, or if you have set resize to on
or set stretchChildren to first
, expand the Other section and set the following attributes:
ContentHeight: Enter the desired height in pixels.
ContentWidth: Enter the desired width in pixels.
Tip:
While the user can change the values of these attributes at runtime (if the resize
attribute is set to on
), the values will not be retained once the user leaves the page unless you configure your application to use change persistence. For information about enabling and using change persistence, see Chapter 31, "Allowing User Customization on JSF Pages."
Note:
If a command component without the showPopupBehavior
tag is used to launch the dialog, and if that command component has values for the windowHeight
and windowWidth
attributes, the values on the command component will override the contentHeight
and contentWidth
values. For more information about the showPopupBehavior
tag, see Section 13.4, "Invoking Popup Elements."
If needed, add command components to the buttonBar
facet. It is recommended that you set the partialSubmit
attribute to true
for every added command component. However, you can set the command component's partialSubmit
attribute to false
if the af:popup
component's autoCancel
property is set to disabled
. The values an af:popup
component's autoCancel
property and a command component partialSubmit
property determine how a command component dismisses and reloads a dialog. For more information, see Section 13.6, "Controlling the Automatic Cancellation of Inline Popups."
Tip:
If the facet is not visible in the visual editor:
Right-click the dialog
component in the Structure window.
From the context menu, choose Facets - Dialog > ButtonBar. Facets in use on the page are indicated by a checkmark in front of the facet name.
By default, added command components do not dismiss the dialog. You need to bind the actionListener
on the command component to a handler that manages closing the dialog, as well as any needed processing. For examples on how to do this, see the tag documentation.
Insert components to display or collect data for the dialog. Use a layout component like panelGroupLayout
to contain the components.
Tip:
Normally, clicking a dialog's Cancel button or Close icon prevents any data entered into an inputText
component from being submitted. However, setting the autoSubmit
attribute to true
on an inputText
component in a dialog overrides the dialog's cancel behavior, as this setting causes a submit.
Add logic on the parent page to invoke the popup and dialog. For more information, see Section 13.4, "Invoking Popup Elements."
The panelWindow
component is similar to the dialog
component, but it does not allow you to configure the buttons or to add buttons to a facet. If you need some logic to be invoked to handle data in the panelWindow
, then you need to create a listener for the popup
component's cancel
event.
The popup
component that contains the panelWindow
component must be contained within a form
component.
Tip:
If you are using the panelWindow
as an inline popup in an application that uses the Fusion technology stack, and you want to emulate the look of a dialog, place the panelWindow
component in the center facet of a panelStretchLayout
component, and place command buttons in the bottom
facet.
To create an inline window:
In the Component Palette, from the Common Components panel, drag and drop a Popup onto the JSF page.
Tip:
It does not matter where the popup
component appears on the page, as the position is driven by the component used to invoke the popup. However, the popup
component must be within a form
component.
In the Property Inspector, expand the Common section and set the following attributes:
ContentDelivery: Select how the content is to be delivered to the component in the popup.
Tip:
Values of input components are not reset when a user closes the panelWindow
component. If the user opens the window a second time, those values will still display. If you want the values to match the current values on the server, then set the contentDelivery
attribute to lazyUncached
.
Animate: Select true
to enable animation. Animation is determined by configuration in the trinidad-config.xml
file and by its skin properties (for more information, see Section A.6.2.1, "Animation Enabled"). You can override this setting by selecting false
.
LauncherVar: Enter a name (for example, source
) for a variable. Similar to the var
attribute on a table, this variable is used to store reference in the Request scope to the component containing the showPopupBehavior
tag. The variable is reachable only during event delivery on the popup
or its child components, and only if EventContext is set to launcher
.
EventContext: Set to launcher
if the popup is shared by multiple objects, for example if the window within the popup will display information for the selected row in a table. Setting this attribute to launcher
makes the row clicked current before the event listener is called, and returns data only for that row. For more information, see Section 13.2.5, "What Happens at Runtime: Popup Component Events."
PopupCancelListener: set to an EL expression that evaluates to a handler with the logic that you want to invoke when the window is dismissed.
Optionally, in the Property Inspector, expand the Other section and set a value for the AutoCancel property to determine the automatic cancel behavior. For more information, see Section 13.6, "Controlling the Automatic Cancellation of Inline Popups."
In the Component Palette, from the Layout panel, drag and drop a Panel Window as a direct child to the popup
component.
In the Property Inspector, expand the Common section and set the following attributes:
Modal: Select whether or not you want the window to be modal. Modal windows do not allow the user to return to the main page until the window has been dismissed.
CloseIconVisible: Select whether or not you want the Close icon to display in the window.
Title: The text displayed as the title in the window.
Resize: Select whether or not you want users to be able to change the size of the dialog. The default is off
.
StretchChildren: Select whether or not you want child components to stretch to fill the window. When set to first
, the window stretches a single child component. However, the child component must allow stretching. For more information, see Section 8.2.1, "Geometry Management and Component Stretching."
Note:
If you set Resize to on
or set StretchChildren to first
, you must also set ContentWidth and ContentHeight (see Step 6). Otherwise, the size will default to 250x250 pixels.
If you want to set a fix size for the window, or if you have set resize to on
or set stretchChildren to first
, expand the Other section and set the following attributes:
ContentHeight: Enter the desired height in pixels.
ContentWidth: Enter the desired width in pixels.
Tip:
While the user can change the values of these attributes at runtime (if the resize
attribute is set to on
), the values will not be retained once the user leaves the page unless you configure your application to use change persistence. For information about enabling and using change persistence, see Chapter 31, "Allowing User Customization on JSF Pages."
Note:
If a command component without the showPopupBehavior
tag is used to launch the dialog, and if that command component has values for the windowHeight
and windowWidth
attributes, the values on the command component will override the contentHeight
and contentWidth
values. For more information about the showPopupBehavior
tag, see Section 13.4, "Invoking Popup Elements."
Insert components to display or collect data for the window. Use a layout component like panelGroupLayout
to contain the components.
Add logic on the parent page to invoke the popup and panel window. For more information, see Section 13.4, "Invoking Popup Elements."
You create a context menu by using menu components within the popup component. You can then invoke the context menu popup from another component, based on a given trigger. If instead, you want toolbar buttons in a toolbar to launch popup menus, then see Section 14.3, "Using Toolbars."
To create an inline context menu:
In the Component Palette, from the Common Components panel, drag and drop a Popup onto the JSF page.
Tip:
It does not matter where the popup component appears on the page, as the position is driven by the component used to invoke the popup. However, the popup
component must be within a form
component.
In the Property Inspector, expand the Common section and set the following attributes.
ContentDelivery: Determines how the content is delivered to the component in the popup.
Animate: Select true
to enable animation. Animation is determined by configuration in the trinidad-config.xml
file and by its skin properties (for more information, see Section A.6.2.1, "Animation Enabled"). You can override this setting by selecting false
.
LauncherVar: Enter a variable name (for example, source
) to be used to reference the launch component. This variable is reachable only during event delivery on the popup
or its child components, and only if the EventContext is set to launcher
.
EventContext: Set to launcher
if the popup is shared by multiple objects, for example if the menu within the popup will display information for the selected row in a table. Setting this attribute to launcher
makes the row clicked current before the event listener is called, and returns only data for that row. For more information, see Section 13.2.5, "What Happens at Runtime: Popup Component Events."
Optionally, in the Property Inspector, expand the Other section and set a value for the AutoCancel property to determine the automatic cancel behavior. For more information, see Section 13.6, "Controlling the Automatic Cancellation of Inline Popups."
From the Component Palette, drag and drop a Menu as a direct child to the popup
component, and build your menu using commandMenuItem
components, as documented starting with Step 6 in Section 14.2.1, "How to Create and Use Menus in a Menu Bar."
Tip:
Because this is a context menu, you do not need to create a menu bar or multiple menus, as documented in Steps 1 through 5 in Section 14.2.1, "How to Create and Use Menus in a Menu Bar."
Add logic on the parent page to invoke the popup and context menu. For more information, see Section 13.4, "Invoking Popup Elements."
Use the noteWindow
component to display read-only text. The popup
component that contains the noteWindow
component must be contained within a form
component.
To create an inline window:
In the Component Palette, from the Common Components panel, drag and drop a Popup onto the JSF page.
Tip:
It does not matter where the popup component appears on the page, as the position is driven by the component used to invoke the popup. However, the popup
component must be within a form
component.
In the Property Inspector, expand the Common section and set the following attributes.
ContentDelivery: Determines how the content is delivered to the component in the popup.
Animate: Select true
to enable animation. Animation is determined by configuration in the trinidad-config.xml
file and by its skin properties (for more information, see Section A.6.2.1, "Animation Enabled"). You can override this setting by selecting false
.
LauncherVar: Enter a variable to be used to reference the launch component. This variable is reachable only during event delivery on the popup
or its child components, and only if the EventContext is set to launcher
.
EventContext: Set to launcher
if the popup is shared by multiple objects, for example if the window within the popup will display information for the selected row in a table. Setting this attribute to launcher
makes the row clicked current before the event listener is called, and returns only data for that row. For more information, see Section 13.2.5, "What Happens at Runtime: Popup Component Events."
PopupCancelListener: set to an EL expression that evaluates to a handler with the logic that you want to invoke when the window is dismissed.
Optionally, in the Property Inspector, expand the Other section and set a value for the AutoCancel property to determine the automatic cancel behavior. For more information, see Section 13.6, "Controlling the Automatic Cancellation of Inline Popups."
From the Component Palette, drag and drop a Note Window as a direct child to the popup
component.
To enter the text to display in the window:
Click the Source tab to view the page source code.
Remove the closing slash (/) from the af:noteWindow
tag.
Below the af:noteWindow tag
, enter the text to display, using simple HTML tags, and ending with a closed af:noteWindow tag
.
Example 13-3 shows text for a note window.
Example 13-3 Text Within an af:noteWindow Tag
<af:popup id="popupHead" contentDelivery="lazyUncached"> <af:noteWindow inlineStyle="width:200px" id="nw3"> <p>In anatomy, the head of an animal is the rostral part (from anatomical position) that usually comprises the brain, eyes, ears, nose, and mouth (all of which aid in various sensory functions, such as sight, hearing, smell, and taste). Some very simple animals may not have a head, but many bilaterally symmetric forms do.</p> </af:noteWindow> </af:popup>
Figure 13-3 shows how the note would display.
Optionally, in the Property Inspector, expand the Other section and specify a number of seconds for the AutoDismissalTimeout property. The value you specify determines the time in seconds that the note window displays before the application automatically dismisses it. Any value you specify overrides the default automatic dismissal behavior. This override is revoked if the end user moves the mouse over the content of the note window because this gesture reverts the automatic dismissal behavior back to the default automatic dismissal behavior for the note window. The default automatic dismissal behavior is to dismiss the note window when focus changes from the launching source or from the content of the popup.
Note:
The feature enabled by this property is not accessible friendly because a mouse over triggers the timeout cancellation period and there is no keyboard equivalent.
Add logic on the parent page to invoke the popup and note window. For more information, see Section 13.4, "Invoking Popup Elements."
When content is delivered to the popup, and the contentDelivery
attribute is set to either lazy
or lazyUncached
, the popupFetch
server-side event is invoked. This event has two properties, eventContext
and launcherVar
. The eventContext
property determines the context from which the event is delivered, either from the context of the popup (self
) or from the component that launched the popup (launcher
). Setting the context to launcher
can be very useful if the popup is shared by multiple components, because the framework will behave as though the component that launched the popup had launched the event, and not the popup. The launcherVar
property is used to keep track of the current launcher, similar to the way in which variables are used to stamp out rows in a table.
For example, say you have a column in a table that displays a person's first name using a command link. When the command link is hovered over, a popup noteWindow
is invoked that shows the person's full name. Because this noteWindow
will be used by all rows in the table, but it needs to display the full name only for the row containing the command link that was clicked, you need to use the eventContext
property to ensure that the context is that row, as shown in Example 13-4.
Example 13-4 Using eventContext for Shared Popup elements
<af:popup id="noteWindow" contentDelivery="lazyUncached" eventContext="launcher" launcherVar="source"> <af:noteWindow> <af:outputText value="#{testBean.fullName}"/> </af:noteWindow> </af:popup> <af:table var="person" value="#{testBean.people}"> <af:column id="firstName"> <af:commandLink text="#{person.firstName}"> <af:showPopupBehavior popupId="::noteWindow" triggerType="mouseHover"/> </af:commandLink> </af:column> </af:table>
Using the variable source, you can take values from the source and apply them, or you can set values. For example, you could get the full name value of the people
object used in the table, and set it as the value of the testBean's
fullName
property used by the window, using a setPropertyListener
and clientAttribute
tag, as shown in Example 13-5.
Example 13-5 Setting the Value of a Component in a Popup Using the launcherVar Property
<af:popup id="noteWindow" contentDelivery="lazyUncached" eventContext="launcher" launcherVar="source"> <af:noteWindow> <af:outputText value="#{testBean.fullName}"/> </af:noteWindow> <af:setPropertyListener from="#{source.attributes.fullName}" to="#{testBean.fullName}" type="popupFetch"/> </af:popup> <af:table var="person" value="#{testBean.people}"> <af:column id="firstName"> <f:facet name="header"> <af:outputText value="First Name"/> </f:facet> <af:commandLink text="#{person.firstName}"> <af:showPopupBehavior popupId="::noteWindow" triggerType="mouseHover"/> <af:clientAttribute name="fullName" value="#{person.fullName}"/> </af:commandLink> </af:column> </af:table>
In this example, the launcherVar
property source gets the full name for the current row using the popupFetch
event. For more information about using the setPropertyListener
tag, see Section 4.7.2, "How to Use the pageFlowScope Scope Without Writing Java Code." For more information about using client attributes, see Section 3.8, "Using Bonus Attributes for Client-Side Components." For more information about the showPopupBehavior
tag, see Section 13.4, "Invoking Popup Elements."
Popups also invoke the following client-side events:
popupOpening
: Fired when the popup is invoked. If this event is canceled in a client-side listener, the popup will not be shown.
popupOpened
: Fired after the popup becomes visible. One example for using this event would be to create custom rules for overriding default focus within the popup.
popupCanceled
: Fired when a popup is unexpectedly dismissed by auto-dismissal or by explicitly invoking the popup client component's cancel method. This client-side event also has a server-side counterpart.
popupClosed
: Fired when the popup is hidden or when the popup is unexpectedly dismissed. This client-side event also has a server-side counterpart.
When a popup is closed by an affirmative condition, for example, when the Yes button is clicked, it is hidden. When a popup is closed by auto-dismissal, for example when either the Close icon or the Cancel button is clicked, it is canceled. Both types of dismissals result in raising a popupClosed
client-side event. Canceling a popup also raises a client-side popupCanceled
event that has an associated server-side counterpart. The event will not be propagated to the server unless there are registered listeners for the event. If it is propagated, it prevents processing of any child components to the popup, meaning any submitted values and validation are ignored. You can create a listener for the popupCanceled
event that contains logic to handle any processing needed when the popup is canceled.
If you want to invoke some logic based on a client-side event, you can create a custom client listener method. For more information, see Section 3.2, "Listening for Client Events." If you want to invoke server-side logic based on a client event, you can add a serverListener
tag that will invoke that logic. For more information, see Section 5.4, "Sending Custom Events from the Client to the Server."
You can programmatically show, hide, or cancel a popup in response to an actionEvent
generated by a command component. Implement this functionality if you want to deliver the actionEvent
to the server immediately so you can invoke server-side logic and show, hide, or cancel the popup in response to the outcome of invoking the server-side logic.
Programmatically invoking a popup as described here differs to the method of invoking a popup described in Section 13.2, "Declaratively Creating Popup Elements" where the showPopupBehavior
tag does not deliver the actionEvent
to the server immediately.
You create the type of popup that you want by placing one of the components (dialog
, panelWindow
, menu
, or noteWindow
) inside the popup
component as described in Section 13.2, "Declaratively Creating Popup Elements." Make sure that the popup
component is in the right context when you invoke it. One of the easier ways to do this is to bind it to the backing bean for the page, as in Example 13-6.
Example 13-6 Binding a popup Component to a Backing Bean
<af:popup id="p1" binding="#{mybean.popup}" ... />
Once you have done this, you configure a command component's actionListener
attribute to reference the popup
component by calling an accessor for the popup binding.
Write code for the backing bean method that invokes, cancels, or hides the popup. Example 13-7 shows a showPopup
backing bean method that uses the HINT_LAUNCH_ID
hint to identify the command component that passes the actionEvent
to it and p1
to reference the popup on which we invoke the show
method.
Example 13-7 Backing Bean Method Invoking a Popup
public void showPopup(ActionEvent event) { { FacesContext context = FacesContext.getCurrentInstance(); UIComponent source = (UIComponent)event.getSource(); String alignId = source.getClientId(context); RichPopup.PopupHints hints = new RichPopup.PopupHints(); hints.add(RichPopup.PopupHints.HintTypes.HINT_ALIGN_ID,source) .add(RichPopup.PopupHints.HintTypes.HINT_LAUNCH_ID,source) .add(RichPopup.PopupHints.HintTypes.HINT_ALIGN, RichPopup.PopupHints.AlignTypes.ALIGN_AFTER_END); p1.show(hints); }
Example 13-8 shows a backing bean method that cancels a popup in response to an actionEvent
:
Example 13-8 Backing Bean Method Canceling a Popup
public void cancelPopupActionListener(ActionEvent event) {
FacesContext context = FacesContext.getCurrentInstance();
p1.cancel();
}
Example 13-9 shows a backing bean method that hides a popup
in response to an actionEvent
:
Example 13-9 Backing Bean Method Hiding a Popup
public void hidePopupActionListener(ActionEvent event) {
FacesContext context = FacesContext.getCurrentInstance();
p1.hide();
}
The p1
object in the previous examples refers to an instance of the RichPopup
class from the following package:
oracle.adf.view.rich.component.rich.RichPopup
For more information about RichPopup
, see the Oracle Fusion Middleware Java API Reference for Oracle ADF Faces.
You configure the command component's actionListener
attribute to reference the backing bean method that shows, cancels or hides the popup.
Before you begin:
Create the type of popup that you want the server-side method to invoke, as described in Section 13.2, "Declaratively Creating Popup Elements."
It may be helpful to have an understanding of the configuration options available to you if you want to invoke a popup component programmatically. For more information, see Section 13.3, "Programmatically Invoking a Popup."
To programmatically invoke a popup:
In the Component Palette, from the General Controls panel, drag and drop a command component onto the JSF page.
For example, a Button component.
In the Property Inspector, expand the Behavior section and set the following attributes:
PartialSubmit: set to true
if you do not want the Fusion web application to render the entire page after an end user clicks the command component. The default value (false
) causes the application to render the whole page after an end user invokes the command component. For more information about page rendering, see Chapter 7, "Rerendering Partial Page Content."
ActionListener: set to an EL expression that evaluates to a backing bean method with the logic that you want to execute when the end user invokes the command component at runtime.
Write the logic for the backing bean that is invoked when the command component in step 1 passes an actionEvent
.
For more information, see Example 13-7, "Backing Bean Method Invoking a Popup", Example 13-8, "Backing Bean Method Canceling a Popup", or Example 13-9, "Backing Bean Method Hiding a Popup".
At runtime, end users can invoke the command components you configure to invoke the server-side methods to show, cancel, or hide a popup. For example, Figure 13-4 shows a panelWindow
component that renders inside a popup
component. It exposes two command buttons (Cancel and Hide) that invoke the cancel
and hide
methods respectively. End users invoke a commandLink
component rendered in the SupplierName column of the table
component in the underlying page to show the popup.
With ADF Faces rich client components, JavaScript is not needed to show or hide popups. The showPopupBehavior
client behavior tag provides a declarative solution, so that you do not have to write JavaScript to open the popup or register the script with the component. For more information about client behavior tags, see Section 5.6, "Using Client Behavior Tags."
The showPopupBehavior
tag listens for a specified event, for example the actionEvent
on a command component, or the disclosureEvent
on a showDetail
component. However, the showPopupBehavior
tag also cancels delivery of that event to the server. Therefore, if you need to invoke some server-side logic based on the event that the showPopupBehavior
tag is listening for, then you need to use either JavaScript to launch the popup, or to use a custom event as documented in Section 5.4, "Sending Custom Events from the Client to the Server."
You use the showPopupBehavior
tag in conjunction with the component that will invoke the popup element, for example a commandButton
component that will invoke a dialog, or an inputText
component that, when right-clicked, will invoke a context menu.
Before you begin:
Create a popup component and its holder.
Create the component that will invoke the popup.
To use the showPopupBehavior tag:
In the Component Palette, from the Operations panel, drag a Show Popup Behavior and drop it as a child to the component that will be used to invoke the popup element.
In the Property Inspector, use the dropdown menu for the PopupId attribute to choose Edit. Use the Edit Property: PopuId dialog to select the popup component to invoke.
From the TriggerType dropdown menu, choose the trigger that should invoke the popup. The default is action
which can be used for command components. Use contextMenu
to trigger a popup when the right-mouse is clicked. Use mouseHover
to trigger a popup when the cursor is over the component. The popup closes when the cursor moves off the component. For a detailed list of component and mouse/keyboard events that can trigger the popup, see the showPopupBehavior
tag documentation.
Note:
The event selected for the triggerType
attribute will not be delivered to the server. If you need to invoke server-side logic based on this event, then you must launch the popup using either JavaScript or a custom event as documented in Section 5.4, "Sending Custom Events from the Client to the Server."
From the AlignId dropdown, choose Edit, and then use the Edit Property: AlignId dialog to select the component with which you want the popup to align.
From the Align dropdown menu, choose how the popup should be positioned relative to the component selected in the previous step.
Note:
The dialog
and panelWindow
components do not require alignId
or align
attributes, as the corresponding popup can be moved by the user. If you set AlignId, the value will be overridden by any manual drag and drop repositioning of the dialog or window. If no value is entered for AlignId or Align, then the dialog or window is opened in the center of the browser.
Additionally, if the triggerType
attribute is set to contextMenu
, the alignment is always based on mouse position.
Example 13-10 shows sample code that displays some text in the af:popup
component with the id “popup1
" when the button "Click Me" is clicked.
Example 13-10 showPopupBehavior Associated with commandButton component
<af:commandButton text="Click me" id="button"> <af:showPopupBehavior popupId="popup1" alignId="button" align="afterEnd"/> </af:commandButton> <af:popup id="popup1"> <af:panelGroupLayout layout="vertical"> <af:outputText value="Some"/> <af:outputText value="popup"/> <af:outputText value="content"/> </af:panelGroupLayout> </af:popup>
The code in Example 13-10 tells ADF Faces to align the popup contents with the commandButton
that is identified by the id
button, and to use the alignment position of afterEnd
, which aligns the popup element underneath the button, as shown in Figure 13-5.
There may be cases when you think the user may need more information to complete a task on a page, but you don't want to clutter the page with information that may not be needed each time the page is accessed, or with multiple buttons that might launch dialogs to display information. While you could put the information in a popup element that was launched with a right-click on a component, the user would have no way of knowing the information was available in a popup.
The contextInfo
component allows you to display additional information in a popup element and also notifies users that additional information is available. When you place the contextInfo
component into the context facet of a component that supports contextual information, a small orange square is shown in the upper left-hand corner of the component, as shown in Figure 13-6.
When the user places the cursor over the square, a larger triangle with a note icon and tooltip is displayed, indicating that additional information is available, as shown in Figure 13-7
Because a showPopupBehavior
tag is a child to the contextInfo
component, the referenced popup will display when the user clicks the information icon, as shown in Figure 13-8.
You use the showPopupBehavior
component as a child to the contextInfo
component, which allows the popup component to align with the component that contains the contextInfo
component.
Before you begin:
Create the component that will be the parent to the contextInfo
component. The following components support the contextInfo
component:
column
commandLink
inputComboboxListOfValues
inputListOfValues
inputText
outputFormatted
outputText
selectOneChoice
Create the popup element to display, as documented in Section 13.2, "Declaratively Creating Popup Elements."
To use a contextInfo component:
In the Component Palette, from the Common Components panel, drag a Context Info and drop it into the Context
facet of the component that is to display the additional information icons.
Tip:
If the facet is not visible in the visual editor:
Right-click the outputText
component in the Structure window.
From the context menu, choose Facets - component name > Context. Facets in use on the page are indicated by a checkmark in front of the facet name.
If you need server-side logic to execute when the contextInfo
component displays, bind the contextInfoListener
attribute to a handler that can handle the event.
Note:
If you use the showPopupBehavior
tag to launch the popup, then delivery of the contextInfoEvent to the server is cancelled. If you need to invoke server-side logic based on this event, then you must launch the popup by using either JavaScript or a custom event as documented in Section 5.4, "Sending Custom Events from the Client to the Server."
In the Component Palette, from the Operations panel, drag a Show Popup Behavior and drop it as a child to the contextInfo
component.
With the showPopupBehavior
tag selected in the editor, in the Property Inspector, set the attributes as described in Section 13.4.1, "How to Use the af:showPopupBehavior Tag." For the triggerType value, be sure to enter contextInfo
.
You can use the af:popup
component with a number of other components to create inline popups. That is, inline windows, dialogs, and context menus. These other components include the:
Dialog component to create an inline dialog
For more information, see Section 13.2.1, "How to Create a Dialog."
panelWindow
component to create an inline window
For more information, see Section 13.2.2, "How to Create a Panel Window."
Menu components to create context menus
For more information, see Section 13.2.3, "How to Create a Context Menu."
noteWindow
component to create a note window
For more information, see Section 13.2.4, "How to Create a Note Window."
By default, a Fusion web application automatically cancels an inline popup if the metadata that defines the inline popup is replaced. Scenarios where this happens include the following:
Invocation of a command component that has its partialSubmit
property set to false
. The Fusion web application renders the entire page after it invokes such a command component. In contrast, a command component that has its partialSubmit
property set to true
causes the Fusion web application to render partial content. For more information about page rendering, see Chapter 7, "Rerendering Partial Page Content."
A component that renders a toggle icon for end users to display or hide content hosts the popup
component. Examples include the showDetailItem
and panelTabbed
components. For more information about the use of components that render toggle icons, see Section 8.8, "Displaying and Hiding Contents Dynamically."
Failover occurs when the Fusion web application displays an inline popup. During failover, the Fusion web application replaces the entire page.
You can change the default behavior described in the previous list by disabling the automatic cancellation of an inline popup component. This means that the Fusion web application does not automatically cancel the inline popup if any of the above events occur. Instead, the Fusion web applications restores the inline popup.
You disable the automatic cancellation of an inline popup by setting the popup
component's autoCancel
property to disabled
.
Before you begin:
It may be helpful to understand how other components can affect functionality. For more information, see Section 13.6, "Controlling the Automatic Cancellation of Inline Popups."
To control the automatic cancellation of inline popups:
In the Structure window, right-click the af:popup
component for which you want to configure the automatic cancellation behavior and choose Go to Properties.
In the Property Inspector, expand the Other section and use the dropdown menu for the AutoCancel property to choose disabled.
JDeveloper sets the af:popup
component autoCancel
property's value to disabled
, as shown in Example 13-11:
Example 13-11 Metadata to Prevent the Automatic Cancellation of an Inline Popup
<af:popup id="p1" autoCancel="disabled">
...
</af:popup>
At runtime, the Fusion web application restores an inline popup after it rerenders a page if the inline popup displayed before invocation of the command to rerender the page.