Class: ojPopup

Oracle® Fusion Middleware Oracle JavaScript Extension Toolkit (JET)
12c (12.1.4)
E54107-01

QuickNav

Fields

Events

Methods


Non-public methods

oj. ojPopup extends oj.baseComponent

JET Popup Component

Description: Themeable, WAI-ARIA-compliant popup that can display arbitrary content.

A JET popup can be created from a block ( <div> ) or inline element ( <span> ). This element will become the immediate child of the content element. Dynamic content can be inserted under this element.

<span id="popup">
  Hello World!
</span>

For WAI-ARIA compliance, JET automatically adds role="tooltip" to the root popup dom element. It also adds the aria-describedby="popup-id" to the launcher while the popup is open.

Keyboard interaction

Key Use
Tab Forward or backward (Shift+Tab) tabbing will traverse within the content of the popup.
F6 Focus can be toggled from the launcher to the popups content and back using the F6 function key.
Esc Esc key from within the content of the popup or from the launcher will close the popup.


There are two general configurations for a ojPopup, basic popup and notewindow. However, both types share common behaviors.

Common Popup Behaviors

The following are behaviors common to both general types of popups:
  • The popup will auto-dismiss when Esc is pressed and focus is within the content.
  • It will auto-dismiss if Esc is pressed when focus is on the launcher node.
  • Forward or backward tabbing at the first or last tab stop will cycle back within the content of the popup.
  • The popup will always be aligned to the launcher. If a launcher is not provided, the default will be the active element in the document. The fallback will be to the document body.
  • At the point when a popup is closed and active focus is within its content, and attempt will be made to establish focus back to the launcher.
  • The popup will have a border, shadow, and z-index defined by the active theme.
  • After creation, the popup will be hidden. Calling the open method will show the popup aligned to the provided position option object.
  • Focus can be toggled from the launcher to the popup's content and back using the F6 function key.
  • After the component binding with the associated element, the popup's content will be hidden by default. The root dom element that defines the popup will be positioned in the document reltative to the binding element. This means that the page developer will need to manage the stacking context of the document.

Basic Popup Behaviors

Default options define the following basic popup behaviors:
  • It will steal focus from the launcher to the first focusable element within its content, provided that a focusable element exists. The default initialFocus option is firstFocusable.
  • The popup will not auto dismiss when focus moves from the popups content or associated launcher. The default for the autoDismiss option is none.

Notewindow Popup Behaviors

  • This type of popup will not initially grab focus when open. The initialFocus option is none.
  • When focus leaves the content of the popup or the launcher, the popup will auto dismiss. The autoDismiss option is set to focusLoss
  • A tail overlaping the border will point to the launcher the popup is aligned to. The tail option of simple.

Event Handling

  • beforeClose(event, ui) - Triggered before a popup closes. Event can prevent closing the popup.
  • beforeOpen(event, ui) - Triggered before a popup closes. Event can prevent opening the popup.
  • close(event, ui) - Triggered after the popup has closed.
  • create(event, ui) - Triggered after the component has been bound to an associated dom element.
  • focus(event, ui) - Triggered when initial focus is established on opening, depending on the value of the initalFocus option, or F6 focus toggle from the associated launcher.
  • open(event, ui) - Triggered after the popup has been made visible.

Constructor

new ojPopup(options)

Creates a JET Popup. If called after the popup is already created, it is equivalent to the "set many options" overload of option().
Parameters:
Name Type Argument Description
options Object <optional>
 a map of option-value pairs to set on the component
Source:
Examples

Initialize the popup with no options specified:

$( ".selector" ).ojPopup();

Initialize the popup with behaviors of a notewindow:

$( ".selector" ).ojPopup({initialFocus: 'none', autoDismiss: 'focusLoss', tail: 'simple'});

Initialize a popup via the JET ojComponent binding:

<div id="popup1" data-bind="ojComponent: {component: 'ojPopup'}">This is a popup!</div>

Fields

#autoDismiss :string

Defines conditions that will cause an open popup to auto close dismiss. A value of focusLoss defines the dismissal condition where focus has left the content of the popup or from the associated launcher.
Supported Values:
Name Type Description
"none" string disables auto dismissal behaviors.
"focusLoss" string defines auto dismissal behavior when focus leaves the content of the popup or associated launcher.
Default Value:
  • "none"
Source:
Examples

Initialize the popup with autoDismiss option specified:

$( ".selector" ).ojPopup( { "autoDismiss": "focusLoss" } );

Get or set the autoDismiss option, after initialization:

// getter
var autoDismiss = $( ".selector" ).ojPopup( "option", "autoDismiss" );
// setter
$( ".selector" ).ojPopup( "option", "autoDismiss", "none" );

#chrome :string

Defines the presents of border, shadow and background color of the root popup dom. Value of none applies the oj-popup-no-chrome selector defined by the active theme to the root dom of the popup to remove the default chrome.
Supported Values:
Name Type Description
"default" string describes the popups border, shadow, and background color defined by the active theme.
"none" string turns of the outer chrome defined by the active theme.
Default Value:
  • "default"
Source:
Examples

Initialize the popup with chrome option specified:

$( ".selector" ).ojPopup( { "chrome": "none" } );

Get or set the chrome option, after initialization:

// getter
var chrome = $( ".selector" ).ojPopup( "option", "chrome" );

// setter
$( ".selector" ).ojPopup( "option", "chrome", "none" );

#contextMenu :Object

JQ selector identifying the JET Menu that the component should launch as a context menu on right-click or Shift-F10. If specified, the browser's native context menu will be replaced by the specified JET Menu.

To specify a JET context menu on a DOM element that is not a JET component, see the ojContextMenu binding.

To make the page semantically accurate from the outset, applications are encouraged to specify the context menu via the standard HTML5 syntax shown in the below example. When the component is initialized, the context menu thus specified will be set on the component.

The JET Menu should be initialized before any component using it as a context menu.

Default Value:
  • null
Inherited From:
Source:
Examples

Initialize a JET component with a context menu:

// via recommended HTML5 syntax:
<div id="myComponent" contextmenu="myMenu" data-bind="ojComponent: { ... }>

// via JET initializer (less preferred) :
$( ".selector" ).ojFoo({ "contextMenu": "#myMenu" });

Get or set the contextMenu option, after initialization:

// getter
var menu = $( ".selector" ).ojFoo( "option", "contextMenu" );

// setter
$( ".selector" ).ojFoo( "option", "contextMenu", ".my-marker-class" );

Set a JET context menu on an ordinary HTML element:

<a href="#" id="myAnchor" contextmenu="myMenu" data-bind="ojContextMenu: {}">Some text

#initialFocus :string

Determines if the popup should steal focus to its content when initially open. A value of none prevents the popup from grabbing focus when open.
Supported Values:
Name Type Description
"none" string prevents the popup from stealing focus when open.
"initialFocus" string defines that a popup should grab focus to its content when open.
Default Value:
  • "firstFocusable"
Source:
Examples

Initialize the popup with initialFocus option specified:

$( ".selector" ).ojPopup( { "initialFocus": "none" } );

Get or set the initialFocus option, after initialization:

// getter
var initialFocus = $( ".selector" ).ojPopup( "option", "initialFocus" );

// setter
$( ".selector" ).ojPopup( "option", "initialFocus", "none" );

#oj.ojpopup#widget

Returns a jQuery object containing the generated wrapper. This method does not accept any arguments.
Source:
Example

Invoke the widget method:

var widget = $( ".selector" ).ojPopup( "widget" );

#position :Object

Position object is defined by the jquery position API and is used to establish the location the popup will appear relative to another element. The postion object contains the following properties: "my", "at", "of", "colision", "using" and "within".

The "my" and "at" properties defines aligment points relative to the popup and other element. The "my" property represents the popups alignment where the "at" property represents the other element that can be identified by "of" or defauts to the launcher when the popup opens. The values of these properties describe a "horizontal vertical" location.

Acceptable "horizontal" alignments values are: "right", "center", "left", "start", "end". Note: Jet has added "start" and "end" options to be more RTL friendly. The Jet values of "start" and "end" normalize to "right" or "left" depending on the direction of the document.

Acceptable "vertical" alignment values are: "top", "center" and "bottom".

The following is a short summary of the most interesting positon properties:
  • my - A "vertical horizontal" rule that defines the location of the popup used for alignment.
  • at - A "vertical horizontal" rule that defines the location of the other element for used alignment. The other element is defined by "of" or defaults to the open launcher argument if not specified.
Default Value:
  • {my: "start top", at: "start bottom", collision: "flip"}
Source:
Examples

Initialize the popup with position option specified:

$( ".selector" ).ojPopup( { "position": {"my": "left top", "at": "right top"} } );

Get or set the position option, after initialization:

// getter
var position = $( ".selector" ).ojPopup( "option", "position" );

// setter
$( ".selector" ).ojPopup( "option", "position", {"my": "start bottom", "at": "end+14 top" } );

#rootAttributes :Object|undefined

Attributes specified here will be set on the component's root DOM element at creation time. This is particularly useful for components like Dialog that wrap themselves in a root element at creation time.

The specified class and style are appended to the current class and style, respectively. All other attributes overwrite any existing value.

Setting this option after component creation has no effect.

Default Value:
  • undefined
Inherited From:
Source:
Example

Initialize a JET component, specifying a set of attributes to be set on the component's root DOM element:

$( ".selector" ).ojFoo({ "rootAttributes": {
  'id': 'myId', 
  'style': 'max-width:100%; color:blue;', 
  'class': 'my-class'
}});

#tail :string

Determines if a decoration will be displayed from the popup that points to the element the popup is aligned to. The simple value enables the tail defined by the current theme. In addtion, the oj-popup-tail-simple selector will be applied to the root dom element. This is to allow the box-shadow, z-index and other chrome styling to vary per tail decoration.
Supported Values:
Name Type Description
"none" string no decoration will be displayed from the popup pointing to the launcher.
"simple" string enables showing the tail defined by the current theme.
Default Value:
  • "none"
Source:
Examples

Initialize the popup with tail option specified:

$( ".selector" ).ojPopup( { "tail": "simple" } );

Get or set the tail option, after initialization:

// getter
var tail = $( ".selector" ).ojPopup( "option", "tail" );

// setter
$( ".selector" ).ojPopup( "option", "tail", "simple" );

Events

#beforeClose

Triggered before the popup is dismissed via the close() method. The close can be cancelled by calling event.preventDefault().
Properties:
Name Type Description
event Event jQuery event object
ui Object dom element that the popup was bound to
Source:
Examples

Initialize the popup with the beforeClose callback specified:

$( ".selector" ).ojPopup({
    "beforeClose": function( event, ui ) {}
});

Bind an event listener to the ojbeforeclose event:

$( ".selector" ).on( "ojbeforeclose", function( event, ui ) {} );

#beforeOpen

Triggered before the popup is launched via the open() method. The launch can be cancelled by calling event.preventDefault().
Properties:
Name Type Description
event Event jQuery event object
ui Object dom element that the popup was bound to
Source:
Examples

Initialize the popup with the beforeOpen callback specified:

$( ".selector" ).ojPopup({
    "beforeOpen": function( event, ui ) {}
});

Bind an event listener to the ojbeforeopen event:

$( ".selector" ).on( "ojbeforeopen", function( event, ui ) {} );

#close

Triggered after the popup is dismissed via the close() method.
Properties:
Name Type Description
event Event jQuery event object
ui Object dom element that the popup was bound to
Source:
Examples

Initialize the popup with the close callback specified:

$( ".selector" ).ojPopup({
    "close": function( event, ui ) {}
});

Bind an event listener to the ojclose event:

$( ".selector" ).on( "ojclose", function( event, ui ) {} );

#focus

Triggered after focus has been transfered to the popup. This will occur after the open() method is called, depending on the value of the initialFocus option. It's also triggered when using the F6 key to toggle focus from the associated launcher element to the content of the popup.
Properties:
Name Type Description
event Event jQuery event object
ui Object dom element that the popup was bound to
Source:
Examples

Initialize the popup with the focus callback specified:

$( ".selector" ).ojPopup({
    "focus": function( event, ui ) {}
});

Bind an event listener to the ojfocus event:

$( ".selector" ).on( "ojfocus", function( event, ui ) {} );

#open

Triggered after the popup is launched via the open() method.
Properties:
Name Type Description
event Event jQuery event object
ui Object dom element that the popup was bound to
Source:
Examples

Initialize the popup with the open callback specified:

$( ".selector" ).ojPopup({
    "open": function( event, ui ) {}
});

Bind an event listener to the ojopen event:

$( ".selector" ).on( "ojopen", function( event, ui ) {} );

Methods

#close() → {void}

Closes the popup. This method does not accept any arguments.
Source:
Fires:
Returns:
Type
void
Example

Invoke the close method:

var close = $( ".selector" ).ojPopup( "close" );

#getNodeBySubId(locator) → {Element|null}

Return the subcomponent node represented by the documented locator attribute values.
Parameters:
Name Type Description
locator Object An Object containing at minimum a subId property whose value is a string, documented by the component, that allows the component to look up the subcomponent associated with that string. It contains:

component: optional component name - in the future there may be more than one component contained within a page element

subId: the string, documented by the component, that the component expects in getNodeBySubId to locate a particular subcomponent.
Inherited From:
Source:
Returns:
the subcomponent located by the subId string passed in locator, if found.
Type
Element | null

#getSubIdByNode(node) → {string|null}

Return the subId string for the given child DOM node
Parameters:
Name Type Description
node Element child DOM node
Inherited From:
Source:
Returns:
- the subId for the DOM node or null when none is found
Type
string | null

#isOpen() → {boolean}

Returns the state of whether the popup is currently open. This method does not accept any arguments.
Source:
Returns:
true if the popup is open.
Type
boolean
Example

Invoke the isOpen method:

var isOpen = $( ".selector" ).ojPopup( "isOpen" );

#open(launcher, position) → {void}

Opens the popup. This method accepts two arguments but both are optional.
Parameters:
Name Type Argument Description
launcher string | jQuery | Element <nullable>
 of the popup
position Object <nullable>
 an element relative to another
Source:
Fires:
Returns:
Type
void
Example

Invoke the open method:

var open = $( ".selector" ).ojPopup( "open" );

#option(optionName, value) → {Object|undefined}

This method has several overloads, which gets and set component options.

The first overload accepts a single optionName param as a string, and returns the current value of that option.

The second overload accepts two params, an optionName string and a new value to which that option will be set.

The third overload accepts no params, and returns a map of key/value pairs representing all the component options and their values.

The fourth overload accepts a single map of option-value pairs to set on the component.

Parameters:
Name Type Argument Description
optionName string | Object <optional>
 the option name (string, first two overloads), or the map (Object, last overload). Omitted in the third overload.
value Object <optional>
 a value to set for the option. Second overload only.
Inherited From:
Source:
Returns:
The getter overloads return the retrieved value(s). When called via the public jQuery syntax, the setter overloads return the object on which they were called, to facilitate method chaining.
Type
Object | undefined
Examples

First overload: get one option:

var isDisabled = $( ".selector" ).ojFoo( "option", "disabled" ); // Foo is Button, Menu, etc.

Second overload: set one option:

$( ".selector" ).ojFoo( "option", "disabled", true ); // Foo is Button, Menu, etc.

Third overload: get all options:

var options = $( ".selector" ).ojFoo( "option" ); // Foo is Button, Menu, etc.

Fourth overload: set one or more options:

$( ".selector" ).ojFoo( "option", { disabled: true } ); // Foo is Button, Menu, etc.

#refresh()

Refreshes the widget.
Inherited From:
Source:

Non-public Methods

<protected> #_AfterCreate()

This method is called after _ComponentCreate. The JET base component does tasks here that must happen after the component (subclass) has created itself in its override of _ComponentCreate. Notably, the base component handles the rootAttributes and contextMenu options here, since those options operate on the component root node, which for some components is created in their override of _ComponentCreate.

Subclasses should override this method only if they have tasks that must happen after a superclass's implementation of this method, e.g. tasks that must happen after the context menu is set on the component.

Overrides of this method should call this._super first.

Inherited From:
Source:

<protected> #_ComponentCreate() → {void}

Source:
Returns:
Type
void

<protected> #_destroy() → {void}

Source:
Returns:
Type
void

<protected> #_GetReadingDirection() → {string}

Determines whether the component is LTR or RTL.

Component responsibilities:

  • All components must determine directionality exclusively by calling this protected superclass method. (So that any future updates to the logic can be made in this one place.)
  • Components that need to know the directionality must call this method from _create() and refresh(), and cache the value.
  • Components should not call this at other times, and should instead use the cached value. (This avoids constant DOM queries, and avoids any future issues if directional islands and component reparenting (e.g. popups) should coexist.)

App responsibilities:

  • The app specifies directionality by setting the HTML "dir" attribute on the <html> node. When omitted, the default is "ltr". (Per-component directionality / directional islands are not currently supported due to inadequate CSS support.)
  • As with any DOM change, the app must refresh() the component if the directionality changes dynamically. (This provides a hook for component housekeeping, and allows caching.)
Default Value:
  • "ltr"
Inherited From:
Source:
Returns:
the reading direction, either "ltr" or "rtl"
Type
string

<protected> #_GetSavedAttributes(element) → {Object}

Gets the saved attributes for the provided element. This is usually the original list of attributes set on the element.
Parameters:
Name Type Description
element Object jQuery selection, should be a single entry
Inherited From:
Source:
Returns:
savedAttributes - attributes that were saved for this element.
Type
Object

<protected> #_InitOptions()

This method is called before _ComponentCreate, at which point the component has not yet been rendered. Component options should be initialized in this method, so that their final values are in place when _ComponentCreate is called.

This includes getting option values from the DOM, where applicable, and coercing option values (however derived) to their appropriate data type. No other work should be done in this method. See below for details.

Overrides of this method should call this._super first.

Usage:

  • If the component has an option like disabled that can be set from the DOM at create time, then the "get from DOM" logic should live in this method. E.g. a typical override might say "if the disabled option still has its initial value of undefined (i.e., the option has not been set), then get the DOM property and set it on the option." (See also next bullet.)
  • For attributes that live on the component's root node, keep in mind that anything specified via the rootAttributes option will not be placed on the DOM until _AfterCreate. So when getting attributes from the root node, components must first look in the rootAttributes option, and then, only if the attribute is not found there, look on the component root (if it already exists).
  • For options that, unlike disabled, have no corresponding DOM property, and are not otherwise set from the DOM, there is nothing to do in this method.
  • Do NOT set anything on the DOM in this method (like the resolved disabled value, or any rootAttributes values). The resolved option values should be set on the DOM later, in _ComponentCreate, and the rootAttributes values are set in baseComponent._AfterCreate.
Inherited From:
Source:

<protected> #_RestoreAttributes()

Restores the saved element's attributes
Inherited From:
Source:

<protected> #_SaveAttributes(element)

Saves the element's attributes within an internal variable to be reset during the destroy function The JSON variable will be held as : [ { "element" : element[i], "attributes" : { attributes[m]["name"] : {"attr": attributes[m]["value"], "prop": $(element[i]).prop(attributes[m]["name"]) } } ]
Parameters:
Name Type Description
element Object jQuery selection to save attributes for
Inherited From:
Source:

<protected> #_setOption(key, value)

Parameters:
Name Type Argument Description
key string option name
value Object <nullable>
 of the target option identified by the key
Source:

<protected> #_SetRootAttributes()

Reads the rootAttributes option, and sets the root attributes on the component's root DOM element.

class and style are appended to the current class and style, respectively. All other attributes overwrite any existing value.

Inherited From:
Source: