Element: <oj-c-popup>

CORE PACK

Oracle® JavaScript Extension Toolkit (JET)
17.1.0
G12196-01

Since:
  • 17.0.0
Module:
  • popup

QuickNav

Slots

Attributes

Events

Methods

Type Definitions

Other Topics


JET Popup

Description: A popup temporarily 'pops up' content in the foreground.


<oj-c-popup>
   Popup content
</oj-c-popup>

<oj-c-popup edge="end" opened="true">
   Opened Popup
</oj-c-popup>

<oj-c-popup placement="bottom">
   Popup positioned at the bottom of the anchor
</oj-c-popup>

Main section content

Keyboard End User Information

Target Key Action
Focus within Popup Tab or Shift + Tab Navigate the content of the popup.
F6 Move focus to the launcher for a popup with modeless modality.
Esc Close the open popup.
Popup Launcher F6 Move focus to the first tab stop within the open popup. If there is not a tab stop within the content, focus is established on the popup.

Accessibility

For WAI-ARIA compliance, JET automatically adds role="tooltip" to the non-modal popup root dom element, or role="dialog" to the modal popup root dom element, if not already specificed. This is not a component property but rather the standard html role attribute. Depending on how the popup is used in the page, the page developer should choose from the following when overriding the default values:

  • "tooltip" defines contextual popup that displays a description for an element. Although this is the default role for non-modal popups, it should only be used for popups that include simple textual content and no interactive elements. The "tooltip" role should never be used with modal popups.
  • "dialog" defines an application window that is designed to interrupt the current processing of an application in order to prompt the user to enter information or require a response. It is the default role for modal popups, but can (and should) be used for non-modal windows too, if the popup includes interactive content.
  • "alertdialog" defines type of popup that contains an alert message, where initial focus goes to an element within the popup.

The page developer should consider adding the aria-haspopup="dialog" to the launcher element.

Depending on the aria role and popup content, the page developer may also need to set the aria-labelledby and (optionally) aria-describedby attributes on the oj-popup element in order to make the popup and its content accessible.

One point often overlooked is making the gestures that launch a popup accessible. There are no constraints to what events a page developer might choose to trigger opening a popup. The choice should be accessible for screen reader users. Page developers should take care when using mouse events to trigger opening of a popup. This is especially important if the content of the popup can't be derived from other visible areas on the page. In cases that mouseover, mouseout, mouseenter, mouseleave and hover events are used to launch popups, there needs to be a keyboard functional equivalency.

Reparenting

When popups are open, they will be reparented in the document and reparented back when closed. When open, the location of the popup within the document will be in context of how it's used. Popups open from other popups will be relocated in the document into the nearest parent popup's layer. The popups layer defines its z-index weight "stacking context". The ojPopup's layer is marked with the "oj-popup-layer" style. The context of opening is defined by the launcher argument passed to the open method. If not open from another popup, the popup will be reparented to a container in the document body. Popups of the same type are assigned the same z-index values. The layering between peer popups reflect the opening order.

There are known caveats with this design. However, these scenarios are considered "bad use" based on our JET popup strategy.

  1. Events raised within the popup will not bubble up to the popup's original ancestors. Instead, listeners for popup events should be applied to either the popup's root element, or the document.
  2. Likewise, developers should not use CSS descendant selectors, or similar logic, that assumes that the popup will remain a child of its original parent.
  3. Popups containing iframes are problematic. The iframe elements "may" fire a HTTP GET request for its src attribute each time the iframe is reparented in the document.
  4. If an iframe is added to the popup's content, it must not be the first or last tab stop within the popup or keyboard and VoiceOver navigation will not remain within the popup.
  5. In some browsers, reparenting a popup that contains elements having overflow, will cause these overflow elements to reset their scrollTop.

Event Handling

  • ojBeforeClose(event) - Triggered before a popup closes. Event can prevent closing the popup; However, there are cases the framework must veto, such as when the popup is destroyed.
  • ojClose(event) - Triggered after the popup has closed.
  • ojFocus(event) - Triggered when initial focus is established on opening, depending on the value of the initalFocus property, or F6 focus toggle from the associated launcher.
  • ojOpen(event) - Triggered after the popup has been made visible.

Reading direction

Setting the reading direction (LTR or RTL) is supported by setting the "dir" attribute on the <html> element of the page. As with any JET component, in the unusual case that the reading direction is changed post-init, the page must be reloaded.


Usage

Signature:

interface CPopupElement

Typescript Import Format
//To typecheck the element APIs, import as below.
import { CPopupElement } from "oj-c/popup";

//For the transpiled javascript to load the element's module, import as below
import "oj-c/popup";

For additional information visit:

Note: Application logic should not interact with the component's properties or invoke its methods until the BusyContext indicates that the component is ready for interaction.


Slots

JET components that allow child content support slots. Please see the slots section of the JET component overview doc for more information on allowed slot content and slot types.

Default

The default slot is the content of the Popup.

Attributes

anchor :(string|Element|oj-c.Popup.Coords)

Specifies Popup's anchor. Popup is placed relatively to its anchor.
Names
Item Name
Property anchor
Property change event anchorChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-anchor-changed

auto-dismiss :"none"|"focusLoss"

Specifies the auto dismissal behavior.
Default Value:
  • "focusLoss"
Names
Item Name
Property autoDismiss
Property change event autoDismissChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-auto-dismiss-changed

collision :"none"|"flip"|"fit"|"flipfit"|"flipcenter"

Specifies rule for alternate placement alignment.
Default Value:
  • "fit"
Names
Item Name
Property collision
Property change event collisionChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-collision-changed

height :(number|string)

Specifies height of the Popup content.
Names
Item Name
Property height
Property change event heightChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-height-changed

initial-focus :"auto"|"none"|"popup"|"firstFocusable"

Specifies if the Popup sets focus to its content when initially open.
Default Value:
  • "auto"
Names
Item Name
Property initialFocus
Property change event initialFocusChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-initial-focus-changed

launcher :(string|Element)

Specifies Popup's launcher. After Popup closes, it returns focus to launcher.
Names
Item Name
Property launcher
Property change event launcherChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-launcher-changed

max-height :(number|string)

Specifies maxHeight of the Popup content.
Default Value:
  • calc(100vw - 3rem)
Names
Item Name
Property maxHeight
Property change event maxHeightChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-max-height-changed

max-width :(number|string)

Specifies maxWidth of the Popup content.
Default Value:
  • calc(100vw - 3rem)
Names
Item Name
Property maxWidth
Property change event maxWidthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-max-width-changed

min-height :(number|string)

Specifies minHeight of the Popup content.
Names
Item Name
Property minHeight
Property change event minHeightChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-min-height-changed

min-width :(number|string)

Specifies minWidth of the Popup content.
Names
Item Name
Property minWidth
Property change event minWidthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-min-width-changed

modality :"modal"|"modeless"

Specifies modality of the Popup.
Default Value:
  • "modeless"
Names
Item Name
Property modality
Property change event modalityChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-modality-changed

offset :oj-c.Popup.PopupOffset

Specifies displacement of the Popup from the anchor element placement along the specified axes.
Names
Item Name
Property offset
Property change event offsetChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-offset-changed

opened* :boolean

Specifies whether the Popup is open.
Default Value:
  • false
Supports writeback:
  • true
Names
Item Name
Property opened
Property change event openedChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-opened*-changed

placement :"center"|"end"|"start"|"top"|"bottom"|"top-start"|"top-end"|"bottom-end"|"bottom-start"|"top-start-corner"|"top-end-corner"|"start-top"|"start-bottom"|"start-top-corner"|"start-bottom-corner"|"bottom-start-corner"|"bottom-end-corner"|"end-top"|"end-bottom"|"end-top-corner"|"end-bottom-corner"

Specifies displacement of the Popup from the anchor element placement along the specified axes. The offset object consists of mainAxis and crossAxis properties. The direction in which these properties are applied depends on the current value of the position property. The mainAxis property represents the distance between the Popup and the anchor. The crossAxis property represents the deviation in the opposite axis to the main axis - the skidding between the Popup and the anchor.
Names
Item Name
Property placement
Property change event placementChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-placement-changed

tail :"none"|"simple"

Specifies Popup's tail. Simple tail is an arrow pointing to Popup's anchor.
Default Value:
  • "none"
Names
Item Name
Property tail
Property change event tailChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-tail-changed

width :(number|string)

Specifies width of the Popup content.
Names
Item Name
Property width
Property change event widthChanged
Property change listener attribute (must be of type function, see Events and Listeners for additional information.) on-width-changed

Events

ojBeforeClose

Triggered immediately before the popup closes. Call event.preventDefault() in the event listener to veto the event synchronously, which prevents the popup from closing. Call event.detail.accept(Promise.reject()); in the event listener to veto the event asynchronously, which prevents the popup from closing.
Properties:

All of the event payloads listed below can be found under event.detail. See Events and Listeners for additional information.

Name Type Description
accept function This method can be called with an application-created Promise to cancel this event asynchronously. The Promise should be resolved or rejected to accept or cancel the event, respectively.

ojClose

Triggered immediately after the popup closes.

See Events and Listeners for additional information.

ojFocus

Triggered immediately after the popup receives focus.

See Events and Listeners for additional information.

ojOpen

Triggered immediately after the popup opens.

See Events and Listeners for additional information.

Methods

getProperty(property) : {any}

Retrieves the value of a property or a subproperty.
Parameters:
Name Type Description
property The property name to get. Supports dot notation for subproperty access.
Returns:
Type
any

setProperties(properties) : {void}

Performs a batch set of properties.
Parameters:
Name Type Description
properties An object containing the property and value pairs to set.
Returns:
Type
void

setProperty(property, value) : {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a corresponding event.
Parameters:
Name Type Description
property The property name to set. Supports dot notation for subproperty access.
value The new value to set the property to.
Returns:
Type
void

Type Definitions

Coords

Properties:
Name Type Argument
contextElement Element <optional>
x number
y number

PopupOffset

Properties:
Name Type Argument
x number <optional>
y number <optional>