15.1 About Popup Dialogs, Menus, and Windows

You can use the popup component with a number of other ADF Faces components to create a variety of dialogs, menus, and windows that provide information or request input from end users. Using these components, you can configure functionality to allow your end users to show and hide information in secondary windows, input additional data, or invoke functionality. The capabilities offered by these components allow you to render content or functionality that is supplemental to the content rendered on the primary interface and, as a result, develop uncluttered and user friendly interfaces.

The popup component is an invisible layout control, used in conjunction with other components to display inline (that is, belonging to the same page) dialogs, windows, and menus. The popup component is invoked from within the primary interface and the application manages the content that renders in the popup component like content in the primary interface without interference from popup blockers. It is recommended that the content type you render in a popup component be HTML. Other types of content, such as Flash or PDF files, may not render appropriately in a popup component.

Figure 15-1 shows examples where the popup component works with other ADF Faces components to render secondary windows.

Figure 15-1 ADF Faces Components for Dialogs, Menus, and Windows

To provide support for building pages for a process displayed separate from the parent page, ADF Faces provides a dialog framework. 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 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.

Using a context parameter named LAST_WINDOW_SESSION_TIMEOUT in your application's web.xml file, you can specify the maximum inactive period of time before session timeout when an application has only one open window. The maximum inactive period of time that you specify for the context parameter should be less than the value you specify for session timeout. If you enable this feature and there is only one window open in a session, the session timeout is set to the value that you specify for this context parameter. Example 15-1 shows how to set the value of the LAST_WINDOW_SESSION_TIMEOUT context parameter in a web.xml file to 1800 seconds.

Example 15-1 Specifying the Session Timeout for the Last Window in an Application

<!-- Sets the session timeout to 1800 seconds when there is only one window open
in the session and 1800 seconds is smaller then the original session timeout. This
gives your application the option to end the session when an end user closes the
last window. Specify a value in seconds. A negative value disables this feature.
The default value is -1. -->
<context-param>
<param-name>LAST_WINDOW_SESSION_TIMEOUT</param-name>
<param-value>1800</param-value>
</context-param>

15.1.1 Popup Dialogs, Menus, Windows Use Cases and Examples

You can place a dialog component as a child to a popup component and render a dialog in a popup at runtime. The dialog component must be the only immediate child component of the popup component. At runtime, end users can view or enter information (for example, search criteria) and use the dialog component's default command component buttons to invoke a dialogEvent when clicked. Figure 15-2 shows an example where an end user can dismiss the dialog by clicking the Close button.

Figure 15-2 af:dialog Component

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 15-3.

Figure 15-3 With Mouseover, Larger Icon with Note is Displayed

When the user clicks the note icon, the associated popup displays its enclosed content.

15.1.2 Additional Functionality for Popup Dialogs, Menus, and Windows

You may find it helpful to understand other ADF Faces features before you use a popup component to create dialogs, menus, and windows. Additionally, once you have added a popup component (or related components) to your page, you may find that you need to add functionality such as accessibility and localization. Following are links to other functionality that these components can use.

Using parameters in text: You can use the ADF Faces EL format tags if you want the text displayed in a component to contain parameters that will resolve at runtime. For more information, see Section 3.5.2, "How to Use the EL Format Tags."

Events: The dialog component renders ADF Faces command components. You also use a command component in conjunction with the showPopupBehavior tag to launch a popup. These ADF Faces command components deliver ActionEvent events when activated. For more information about how to handle events on the server as well as on the client, see Chapter 6, "Handling Events."

Localization: Instead of directly entering text for labels in the popup dialogs, menus, and windows that you create, you can use property files. These files allow you to manage translation of the text strings. For more information, see Chapter 29, "Internationalizing and Localizing Pages."

Dialog framework: If your application uses the full Fusion technology stack, note that the dialog framework is integrated with ADF Controller for use with ADF task flows. For more information, see the "Using Dialogs in Your Application" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

15.2 Declaratively Creating Popups

The dialog, panelWindow, menu, and noteWindow components can all be used inside the popup component to display inline popups, as shown in Table 15-1. When no child component exists for the popup component, a very simple inline popup appears.

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 15.2.4, "How to Create a Note Window."

popup component without one of the following components as an immediate child component: dialog, panelWindow, menu, or noteWindow

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). The dialog and panelWindow components do not support instruction help. For more information, see Chapter 19, "Displaying Tips, Messages, and Help."

Typically, you use a command component in conjunction with the showPopupBehavior tag to launch a popup. You associate the showPopupBehavior tag with the component it should launch. This tag also controls the positioning of the popup (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 15.3, "Declaratively Invoking a Popup."

As an alternative to using the showPopupBehavior tag in conjunction with a command component, you can launch, cancel, or hide a popup by writing a backing bean method. The backing bean method you write takes the actionEvent returned by the command component as an argument. For more information about this alternative, see Section 15.4, "Programmatically Invoking a Popup."

By default, the content of the popup is not sent from the server until the popup is displayed. This represents a trade-off between the speed of showing the popup when it is opened and the speed of rendering the parent page. Once the popup 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 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 popups that are consistently used by all users every time they use the page.

lazyUncached - The content is not loaded until the popup displays, and then the content reloads every time you show the popup. Use this strategy if the popup shows data that can become stale or outdated.

If you choose to set the popup component's contentDelivery attribute to lazy, 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.

15.2.1 How to Create a Dialog

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 15.6, "Controlling the Automatic Cancellation of Inline Popups."

In the ADF Faces page of the Component Palette, from the Layout panel, in the Secondary Windows group, drag a Popup and drop it on the 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 15.2.5, "What Happens at Runtime: Popup Component Events."

Optionally, in the Property Inspector, expand the Common section and set the following attributes:

ChildCreation: Set to deferred to defer the creation of the popup component's child components until the application delivers the content. The default value for the childCreation attribute is immediate. For more information, see Section 15.2, "Declaratively Creating Popups."

ResetEditableValues: Select whenCanceled to reset editable values that an end user entered to null if the end user cancels the dialog.

For example, if you set the type attribute to yesNoCancel, the dialog displays 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. The 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.

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 handles 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 15-2. 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.

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. Any values entered into input components rendered in the popup component do not get sent to the server. Any editable components that have changed their values since the popup component rendered do not send the changed values to the server. 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 Appearance 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 32, "Allowing User Customization on JSF Pages."

Note:

If you use a command component without the showPopupBehavior tag to launch the dialog, and if that command component has values for the windowHeight and windowWidth attributes, the values on the command component override the contentHeight and contentWidth values. The dialog framework allows you to use a command component to launch a dialog without the showPopupBehavior tag. 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. For more information about the showPopupBehavior tag, see Section 15.3, "Declaratively Invoking a Popup."

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

15.2.2 How to Create a Panel Window

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 to invoke logic to handle data in the panelWindow, 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.

In the ADF Faces page of the Component Palette, from the Layout panel, in the Secondary Windows group, drag a Popup and drop it on the 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").

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

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 Appearance 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 32, "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 15.3, "Declaratively Invoking a Popup."

Insert components to display or collect data for the window. Use a layout component like panelGroupLayout to contain the components.

15.2.3 How to Create a Context Menu

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 16.3, "Using Toolbars."

In the ADF Faces page of the Component Palette, from the Layout panel, in the Secondary Windows group, drag a Popup and drop it on the 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 15.2.5, "What Happens at Runtime: Popup Component Events."

In the ADF Faces page of the Component Palette, from the Layout panel, in the Secondary Windows group, drag a Popup and drop it on the 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 15.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.

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

Optionally, in the Property Inspector, expand the Behavior 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.

15.2.5 What Happens at Runtime: Popup Component Events

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 15-5.

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'sfullName property used by the window, using a setPropertyListener and clientAttribute tag, as shown in Example 15-6.

Example 15-6 Setting the Value of a Component in a Popup Using the launcherVar Property

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.

15.2.6 What You May Need to Know About Dialog Events

The dialog component raises a dialogEvent when the end user clicks the OK, Yes, No or Cancel buttons. A dialog component automatically hides itself when the end user clicks the OK, Yes or No buttons provided that no message with a severity of error or greater exists on the page. An end user selecting the Cancel button or close icon cancels the parent popup component and raises a popup canceled event.

You can configure a dialogListener attribute to intercept the dialogEvent returned by the OK, Yes, No, and Cancel buttons. Only the dialogEvent returned by the OK, Yes and No buttons get propagated to the server. The dialogEvent returned by the Cancel button, the ESC key, and close icon queue a client dialog event and do not get propagated to the server.

If you configure an actionListener for the command component that invokes a dialog component to carry out an action (for example, update an inputText component) after the dialog component returns, you also need to call resetValue() on the inputText component if the command component's immediate value is set to true.

15.3 Declaratively Invoking a Popup

With ADF Faces components, JavaScript is not needed to show or hide popups. The showPopupBehavior tag provides a declarative solution, so that you do not have to write JavaScript to open a popup component or register a script with the popup component. For more information about client behavior tags, see Section 6.6, "Using ADF Faces 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 programmatically launch the popup component as documented in Section 15.4, "Programmatically Invoking a Popup."

15.3.1 How to Declaratively Invoke a Popup Using the af:showPopupBehavior Tag

You use the showPopupBehavior tag in conjunction with the component that invokes the popup, for example a commandButton component that invokes a dialog, or an inputText component that, when right-clicked, will invoke a context menu.

In the Component Palette, from the Operations panel, in the Behavior group, drag a Show Popup Behavior and drop it as a child to the component that invokes the popup.

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 and click OK.

In the Property Inspector, from the TriggerType dropdown menu, choose the trigger to 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 documentation for the showPopupBehavior tag in the Oracle Fusion Middleware Tag Reference for Oracle ADF Faces.

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.

15.3.2 What Happens When You Use af:showPopupBehavior Tag to Invoke a Popup

At design time, JDeveloper generates the corresponding values in the source files that you selected in the Property Inspector. Example 15-7 shows sample code that displays some text in the af:popup component with the id “popup1" when the button "Click Me" is clicked.

The code in Example 15-7 tells ADF Faces to align the popup contents with the commandButton identified by the id attribute, and to use the alignment position of afterStart, which aligns the popup underneath the button, as shown in Figure 15-5.

Figure 15-5 Button and Popup Contents

15.4 Programmatically Invoking a Popup

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 15.3, "Declaratively Invoking a Popup" 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 15.2, "Declaratively Creating Popups." 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 15-8.

Example 15-8 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 15-9 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.

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 8, "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 2 passes an actionEvent.

15.4.2 What Happens When You Programmatically Invoke 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 15-6 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.

Figure 15-6 Popup Component Invoked by a Server-Side Method

15.5 Displaying Contextual Information in Popups

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

Figure 15-7 contextInfo Displays a Square

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 15-8.

In the ADF Faces page of the Component Palette, from the General Controls 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 6.4, "Sending Custom Events from the Client to the Server."

In the Component Palette, from the Operations panel, in the Behavior group, drag a Show Popup Behavior and drop it as a child to the contextInfo component.

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 8, "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 9.9, "Displaying and Hiding Contents Dynamically."

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.

15.6.1 How to Disable the Automatic Cancellation of an Inline Popup

You disable the automatic cancellation of an inline popup by setting the popup component's autoCancel property to disabled.

15.6.2 What Happens When You Disable the Automatic Cancellation of an Inline Popup

Example 15-12 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.

15.7 Resetting Input Fields in a Popup

You can use the resetListener component in conjunction with a popup component to allow end users to reset input values in an input field. Example use cases where you may want to implement this functionality for input components that render in a popup component include:

Permitting end users to reset an incorrect value that they previously entered

Removing values where the popup component invokes a popupCanceledEvent before the application submits the values to the server that an end user entered.

End user gestures that invoke a popupCancelEvent include clicking a command button (for example, a button labelled Close), the cancel icon in the title bar of a popup dialog or pressing the Esc key.

Depending on how you configure the popup component, data may be cached on the client. For example, if you set the popup component's contentDelivery attribute to immediate, the application always caches data on the client.

Example 15-13 shows the metadata for a popup component where the contentDelivery attribute is set to immediate and the user's popup renders a dialog component with preconfigured controls that raise dialogEvents, as described in Section 15.2.1, "How to Create a Dialog." In this scenario, data that the end user entered is cached on the client. The application does not submit data that you want to reset to the server. Also, the preconfigured controls rendered by the dialog component may prevent the popup from closing if they encounter validation errors.

Setting the resetListener component's type attribute to popupCanceled provides the same functionality as setting the popup component's resetEditableValues attribute to whenCanceled. For more information about setting the resetEditableValues attribute of the popup component, see Section 15.2.1, "How to Create a Dialog."

15.7.1 How to Reset the Input Fields in a Popup

You enable end users to reset the data in a popup's input fields to null by setting the resetListener component's type attribute to popupCanceled.

From the Component Palette, drag and drop a Reset Listener as a direct child to the popup component.

In the Insert Reset Listener dialog that JDeveloper displays, enter popupCanceled as the type of event that the resetListener component responds to.

Click Help in the Insert Reset Listener dialog to view a complete list of supported values.

15.7.2 What Happens When You Configure a Popup to Reset Its Input Fields

JDeveloper writes entries similar to those shown in Example 15-14 when you configure a popup component and a resetListener component to allow end users to reset the input field(s) in the popup component to null.

At runtime, an end user gesture that raises a popupCanceled event results in the resetListener component resetting values in the input fields of the popup component to null, as illustrated in Figure 15-10.

Figure 15-10 Popup Component Resetting Input Fields

Scripting on this page enhances content navigation, but does not change the content in any way.