Oracle Fusion Middleware Tag Reference for Oracle ADF Faces
12c (12.2.1.4.0)
E81455-02

<af:showPopupBehavior>

The af:showPopupBehavior tag is a declarative way to show a af:popup in response to a client-side event. The client event is specified using the triggerType attribute. The "action" event is the default triggerType if one is not provided. When the showPopupBehavior tag is associated with a component, the popup specified via the popupId attribute will automatically be shown when the associated client event is activated. This tag only acts on client events similar to the af:clientListener tag.

Popup Alignment

The tag's alignId and align attributes are used to specify the location a popup should be opened. These attributes are required for most types of popups (See af:popup for popup types). However, there are a few exceptions to this rule. The af:dialog and af:panelWindow popup types do not require alignment attributes. These types of popups can be manually repositioned using drag-and-drop and will open by default at the center of the browser window. The third exception that doesn't require alignment attributes is for popup's using the "contextMenu" triggerType. The "contextMenu" event is fired on a right mouse click. For this trigger type, popup alignment is by mouse position.

Popup Tail

The tag's tail attribute is used to specify whether popup tail has to be shown or not. The default value will be "none". The popup tail will be positioned based on the final alignment value.

Cancels Client Events

The showPopupBehavior tag cancels the client event defined by the triggerType. Canceling the client event will prevent delivery to the server. This is significant for action events raised by command family components because the server-side action listeners will be ignored. All actionListener method bindings and associated action listeners will not be invoked when the triggerType of "action" is used.

Subscriber of Client Events

The showPopupBehavior tag is only a subscriber of component events meaning that it can only react to client component events. The various client events and sequences in which client events are raised are component specific, unknown to the showPopupBehavior tag. Developers that need to also trigger server-side functionality can either use manual JavaScript to show a popup, or add an additional af:clientListener that uses AdfCustomEvent and af:serverListener to deliver a server-side event.

Special Behaviors

The various types of popup's have built in "behaviors" such as auto-dismissal and if the popup steals focus when shown. There is a special behavior added to the showPopupBehavior tag when working with an inline selector type of popup. An inline selector type of popup will toggle visibility of the associated popup if the popup is already shown. So, if you are using this tag with a command button and use the default triggerType of "action", the first click on the launching command will show the popup. A second click on the command will hide the popup. This behavior only applies to the inline selector type of popup used with the showPopupBehavior tag. To learn more about the types of popups see the af:popup tag documentation.

A single popup can be opened by several launching sources using the showPopupBehavior tag. If a popup is already visible and a request to open using a showPopupBehavior tag from another launching source is made, the shared popup will be dismissed before showing again. If the popup is already visible and another request to show it is made from the same launching source the request is ignored (excluding the inline selector).

The "mouseOver" or "mouseHover" event types have a built in 500-millisecond launch delay that is implicitly canceled if a "mouseOut" event is triggered for the same component within the delay period.

All popup types have determined auto-dismissal behaviors. See the af:popup tag documentation for a breakdown of popup types and assumed behaviors.

Note: If EL is used in the EL supported attributes of this tag, this tag will not be stampable.

Examples:

This example will show the popup with the id "somePopup" when the button is clicked.

<af:commandButton id="button" text="Click me">
  <af:showPopupBehavior popupId="somePopup" alignId="button"
                           align="endBefore" triggerType="action" tail="simple" />
</af:commandButton>

This example will shows a menu popup with the id "someMenuPopup" when anything within the panelGroupLayout is right-clicked.

<af:panelGroupLayout>
  <af:showPopupBehavior popupId="someMenuPopup"
                triggerType="contextMenu"/>
                .... any other content ...
</af:panelGroupLayout>

Accessibility Guidelines

Trigger types action/contextInfo are recommended over other native trigger types as it is more accessible. Trigger types of mouseHover, mouseMove, mouseOver, and mouseOut may cause unwanted and unexpected visits away from the host page to a popup screen. If you use one of these triggerTypes, make sure you provide alternate access to the same content.

Do not create popups that are only available by mouse! If you are using one of the mouse triggerTypes, make sure that your popup is also accessible via the keyboard. For example, if you want to display a noteWindow on mouseOver, you could setup two showPopupBehavior tags, one triggering on mouseOver and one triggering on action, so that a keyboard only can also access the popup.

Do not show a popup on focus or blur event types. This will cause a change in context making your application hard to use by a keyboard only user, and confusing for someone using a screen reader. While these are available event types, they should not be used in any real application with showPopupBehavior.

Client Event Trigger Types

The following table lists component family-specific event types that can be assigned to the triggerType attribute:

Event Type	Component Family	Description
action	Command	Fires when user triggers the command component. Owning component's server-side action listeners will be ignored since the event will be canceled.
contextInfo	ContextInfo	Fires when user clicks the icon in a contextInfo
dialog	Dialog	Fires when user clicks dialog OK/Cancel buttons
disclosure	ShowDetail	Fires when disclosure state is toggled
inlineFrameLoad	InlineFrame	Queued when the internal iframe fires its load event
load	Document	Fires when the document finishes loading
fetch	Popup	Content fetch event fired before opening if the content delivery of the popup is lazy or lazyUncached. This is the first of two events required for content delivery.
contentLoaded	Popup	Partial content delivery has been delivered to the browser. This event notifies the popup component that it can be shown. Second content delivery event.
popupOpening	Popup	Fired prior to opening a popup
popupOpened	Popup	Fired after popup is opened
popupClosed	Popup	Fired after popup is closed
query	Query	Fired when a query action happens(when user clicks the search icon in quickQuery or the search button in the query component)
rowDisclosure	Tree, TreeTable	Fired row disclosure state is toggled
selection	Table, Tree, TreeTable	Fires when selection state changes
sort	Table	Fires when user sorts data
valueChange	Input, Select\*	Fires when the value of an input control is changed

The following table lists input (mouse/keyboard) event types. These events are delivered for all components (though in some cases may be consumed by the peer implementation) and can be assigned to the triggerType attribute:

Event Type	Description
click	Fires when user clicks on component. When the event source is a command family component, the component will still raise the action event.
contextMenu	Shows the popup on right mouse click. Assumes aligment is by mouse position.
dblClick	Fires when user double clicks on component
mouseDown	Fires when user performs mouse down on component
mouseUp	Fires when user performs mouse up on component
mouseMove	Fires when user moves mouse while over a component. Note that showPopupBehaviors with trigger type "mouseMove" are suppressed in screen reader mode.
mouseOver	Fires when mouse enters a component. Assumes a 500-millisecond delay before launching the popup. A "mouseOut" raised within the delay period, cancels a pending launch request. Note that showPopupBehaviors with trigger type "mouseOver" are suppressed in screen reader mode.
mouseOut	Fires when mouse leaves a component. Note that showPopupBehaviors with trigger type "mouseOut" are suppressed in screen reader mode.
keyDown	Fires when user presses key down while focused on a component
keyUp	Fires when user releases key while focused focused on a component
keyPress	Fires when successful key press occurs while focused on a component
focus	Fires when component gains keyboard focus
blur	Fires when component loses keyboard focus

The following table lists hybrid event types that combine multiple event types:

mnemonic Description

mouseHover Hybrid event type that shows the popup on "mouseOver" and hides the popup on "mouseOut". This event assumes a 500ms delay before launching the popup. A "mouseOut" event fired within the 500ms delay, cancels a pending launch request. This event type requires alignment to an element by using the alignId and align attributes. Note that showPopupBehaviors with trigger type "mouseHover" are suppressed in screen reader mode.

mnemonic	Description
mouseHover	Hybrid event type that shows the popup on "mouseOver" and hides the popup on "mouseOut". This event assumes a 500ms delay before launching the popup. A "mouseOut" event fired within the 500ms delay, cancels a pending launch request. This event type requires alignment to an element by using the `alignId` and `align` attributes. Note that showPopupBehaviors with trigger type "mouseHover" are suppressed in screen reader mode.

Attributes

Name	Type	Supports EL?	Description

popupId String yes the ID of the popup, relative to the containing component. An ID beginning with a colon will be treated as absolute (after trimming off the colon). This is a required attribute. disabled Boolean yes the default value is false. Determines whether the client behavior should be disabled. Use this behavior attribute to conditionally disable showing the target popup identified by popupId. alignId String no the ID of the component relative to which the popup will be aligned. An ID beginning with a colon will be treated as absolute (after trimming off the colon). All other ids will be resolved relative to the component which contains the showPopupBehavior. align String no

indicates how the popup should aligned relative to the alignId component. Valid values include:

afterStart: The popup appears underneath the element with the popup's upper-left corner aligned with the lower-left corner of the element. The left edges of the element and the popup are aligned.
afterEnd: The popup appears underneath the element with the popup's upper-right corner aligned with the lower-right corner of the element. The right edges of the element and the popup are aligned.
beforeStart: The popup appears above the element with the popup's lower-left corner aligned with the upper-left corner of the element. The left edges of the element and the popup are aligned.
beforeEnd: The popup appears above the element with the popup's lower-right corner aligned with the upper-right corner of the element. The right edges of the element and the popup are aligned.
endAfter: The popup appears to the right of the element with the popup's lower-left corner aligned with the lower-right corner of the element. The bottom edges of the element and the popup are aligned.
endBefore: The popup appears to the right of the element with the popup's upper-left corner aligned with the upper-right corner of the element. The top edges of the element and the popup are aligned.
startAfter: The popup appears to the left of the element with the popup's lower-right corner aligned with the lower-left corner of the element. The bottom edges of the element and the popup are aligned.
startBefore: The popup appears to the left of the element with the popup's upper-right corner aligned with the upper-left corner of the element. The top edges of the element and the popup are aligned.

triggerType String no the event type which will trigger the popup being shown. By default, this is "action". To show a popup menu, use "contextMenu". To show a non-modal popup upon the mouse appearing over the trigger component and also to hide it upon the mouse leaving the trigger component, use "mouseHover". Note that showPopupBehaviors with trigger type "mouseHover", "mouseMove", "mouseOver", and "mouseOut" are suppressed in screen reader mode. See "Client Event Trigger Types" section above for a complete list of trigger types. tail String no

indicates whether popup tail has to be shown or not. The tail value is associated with its visual presentation defined in the active skin. Out of the box values include:

none: Popup tail will not be shown.
simple: Popup tail will be shown with out of the box styling provided.