Class: ojDialog

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

E54107-01

QuickNav

oj. ojDialog

JET Dialog Component

Description: Themeable, WAI-ARIA-compliant dialog component. A dialog is a floating window that typically contains a title bar and a content area. The dialog window can be moved, resized and with the title area, and closed with the 'x' icon by default.

If the content length exceeds the maximum height, a scrollbar will automatically appear.

A bottom button bar and semi-transparent modal overlay layer are common options that can be added.

Focus

Upon opening a dialog, focus is automatically moved to the first item that matches the following:

  1. The first element within the dialog with the autofocus attribute
  2. The first :tabbable element within the dialog's content
  3. The first :tabbable element within the dialog's buttonpane
  4. The dialog's close button
  5. The dialog itself

While open, the dialog widget ensures that tabbing cycles focus between elements within the dialog itself, not elements outside of it. Modal dialogs additionally prevent mouse users fro clicking on elements outside of the dialog.

Upon closing a dialog, focus is automatically returned to the element that had focus when the dialog was opened.

HTML Markup and Style Classes

Three formatting classes are provided:
  • oj-dialog-header
  • Optional. If oj-dialog-header is omitted, a header will automatically be created.
  • oj-dialog-body
  • Expected. Formats the body of the dialog.
  • oj-dialog-footer
  • Expected. Formats the footer of the dialog.
For automically created headers, the title of the header is the dialog title. A close button will also be created.

Examples

The following defines a basic dialog.


<div id="dialog" class="ojDialog" title="ojDialog Title">
    <div class="oj-dialog-body">
        <p>Dialog Text</p>
    </div>
    <div class="oj-dialog-footer">
       <button id="buttonCancel" data-bind="ojComponent: 
             { component: 'ojButton', label: 'OK'}"> </button>
       <button data-bind="ojComponent: 
             { component: 'ojButton', label: 'Cancel'}"> </button>
    </div>
</div>

A dialog with user-defined header is shown next. Arbitrary header content can be defined using a user-defined header.


<div id="dialog" class="ojDialog" title="ojDialog Title">
  <div class="oj-dialog-header" aria-labelledby="dialog-title-id">
    <span id="dialog-title-id" class="oj-dialog-title"> User Defined Header</span>
   </div>
   <div class="oj-dialog-body">
       <p>Dialog Text</p>
       <br>
   </div>
   <div class="oj-dialog-footer">
      <button data-bind="ojComponent: 
          { component: 'ojButton', label: 'OK'}"> </button>
      <button id="buttonCancel" class="" data-bind="ojComponent: 
          { component: 'ojButton', label: 'Cancel'}"> </button>
   </div>
</div>

Initializer

.ojDialog(options)

Creates a JET Dialog.
Parameters:
Name Type Argument Description
options Object <optional>
a map of option-value pairs to set on the component
Source:
Examples

Initialize a (modal) dialog with no options specified:

$( ".selector" ).ojDialog();

Create a modeless dialog of width 400:

$("#dialog").ojDialog({width: '400', modality: "modeless"});

Options

<static> height :string|number

The height of the dialog.
Multiple types are supported:
  • Number: The height in pixels.
  • String: The only supported string value is "auto" which will allow the dialog height to adjust based on its content.
Source:
Examples

Initialize the dialog to a fixed height height

$(".selector" ).ojDialog( {height: 300 } );

Get or set the height option, after initialization:

// getter
var height = $(".selector" ).ojDialog( "option", "height" );

// setter
$(".selector" ).ojDialog( "option", "height", 300);

#cancelBehavior :string

Specifies the cancel behavior of the dialog. The following are valid values:
  • "icon" - (the default) (a) a close icon will automatically be created, and (b) the dialog will close when it has focus and user presses the escape (ESC) key.
  • "none" - no actions will be associated with the escape key.
  • "escape" - the dialog will close when it has focus and user presses the escape (ESC) key. A close icon will not automatically be created.
Note that the cancelBehavior applies to both automatic and user-defined headers. So by default, a user-defined header will have a system generated close icon.
Default Value:
  • "icon"
Source:
Examples

Initialize the dialog to disable the default cancelBehavior

$(".selector" ).ojDialog( {cancelBehavior: "none" } );

Get or set the cancelBehavior option, after initialization:

// getter
var cancelBehavior = $(".selector" ).ojDialog( "option", "cancelBehavior" );

// setter
$(".selector" ).ojDialog( "option", "cancelBehavior", "none");

#dragAffordance :string

Specifies the drag affordance. If set to "title-bar" (the default) the dialog will be draggable by the title bar. If "none", the dialog will not be draggable.
Default Value:
  • "title-bar"
Source:
Examples

Initialize the dialog to disable dragging dragAffordance

$(".selector" ).ojDialog( {dragAffordance: "none" } );

Get or set the dragAffordance option, after initialization:

// getter
var dragAffordance = $(".selector" ).ojDialog( "option", "dragAffordance" );

// setter
$(".selector" ).ojDialog( "option", "dragAffordance", "none");

#initialVisibility :string

Set the initial visibility of the dialog. If set to "show", the dialog will automatically open upon initialization. If "hide", the dialog will stay hidden until the open() method is called.

Default Value:
  • "hide"
Source:
Examples

Initialize the dialog with the initialVisibility option specified:

$(".selector" ).ojDialog( {initialVisibility: "show" } );

Get or set the initialVisibility option, after initialization:

// getter
var initialVisibility = $(".selector" ).ojDialog( "option", "initialVisibility" );

// setter
$(".selector" ).ojDialog( "option", "initialVisibility", "show");

#modality :string

The modality of the dialog. Valid values are:
  • "modal" - (the default) The dialog is modal. Interactions with other page elements are disabled. Modal dialogs overlay other page elements.
  • "modeless" - defines a modeless dialog.
Default Value:
  • "modal"
Source:
Examples

Initialize the dialog to a specific modality modality

$(".selector" ).ojDialog( {modality: "modal" } );

Get or set the modality option, after initialization:

// getter
var modality = $(".selector" ).ojDialog( "option", "modality" );

// setter
$(".selector" ).ojDialog( "option", "modality", "modal");

#position :Object

Position object is defined by the jquery position API and is used to establish the location the dialog 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 dialog and other element. The "my" property represents the dialogs alignment where the "at" property represents the other element that can be identified by "of" or defauts to the launcher when the dialog 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 dialog 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: "center", at: "center", collision: "fit"}
Source:
Examples

Initialize the dialog with position option specified:

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

Get or set the position option, after initialization:

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

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

#resizeBehavior :string

The resizeBehavior of the dialog. "resizable" (default) makes the dialog resizable. "none" disables dialog resizability.
Default Value:
  • "resizable"
Source:
Examples

Initialize the dialog to a specific resizeBehavior resizeBehavior

$(".selector" ).ojDialog( {resizeBehavior: "none" } );

Get or set the resizeBehavior option, after initialization:

// getter
var resizeBehavior = $(".selector" ).ojDialog( "option", "resizeBehavior" );

// setter
$(".selector" ).ojDialog( "option", "resizeBehavior", "none");

#role :string

The role of the dialog. By default, role="dialog" is added to the generated HTML markup that surrounds the dialog. When used as an alert dialog, the user should set role to "alertdialog".
Default Value:
  • "dialog"
Source:
Examples

Initialize the dialog with the role option specified:

$(".selector" ).ojDialog( {role: "alertdialog" } );

Get or set the role option, after initialization:

// getter
var role = $(".selector" ).ojDialog( "option", "role" );

// setter
$(".selector" ).ojDialog( "option", "role", "alertdialog");

#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" ).ojDialog( "widget" );

#width :string|number

The width of the dialog, in pixels
Multiple types are supported:
  • Number: The width in pixels.
  • String: The only supported string value is "auto" which will allow the dialog width to adjust based on its content.
Default Value:
  • 300
Source:
Examples

Initialize the dialog to a fixed width width

$(".selector" ).ojDialog( {width: 400 } );

Get or set the width option, after initialization:

// getter
var width = $(".selector" ).ojDialog("option", "width" );

// setter
$(".selector" ).ojDialog("option", "width", 400);

Events

#beforeClose

Triggered when a dialog is about to close. If cancelled, the dialog will not close.
Properties:
Name Type Description
event Event jQuery event object
ui Object Empty object included for consistency with other events
Source:
Examples

Initialize the dialog with the beforeClose callback specified:

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

Bind an event listener to the ojbeforeClose event:

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

#beforeOpen

Triggered when the dialog is about to to open.
Properties:
Name Type Description
event Event jQuery event object
ui Object Empty object included for consistency with other events
Source:
Examples

Initialize the dialog with the beforeOpen callback specified:

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

Bind an event listener to the ojbeforeOpen event:

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

#close

Close the dialog. this method does not accept any arguments.
Source:
Example

Invoke the close method:

$( ".selector" ).ojDialog("close");

#create

Triggered when the dialog is created.
Properties:
Name Type Description
event Event jQuery event object
ui Object Empty object included for consistency with other events
Source:
Examples

Initialize the buttonset with the create callback specified:

$( ".selector" ).ojDialog({
    "create": function( event, ui ) {}
});

Bind an event listener to the ojcreate event:

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

#focus

Triggered when the dialog gains focus.
Properties:
Name Type Description
event Event jQuery event object
ui Object Empty object included for consistency with other events
Source:
Examples

Initialize the dialog with the focus callback specified:

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

Bind an event listener to the ojfocus event:

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

#open

Triggered when the dialog is opened.
Properties:
Name Type Description
event Event jQuery event object
ui Object Empty object included for consistency with other events
Source:
Examples

Initialize the dialog with the open callback specified:

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

Bind an event listener to the ojopen event:

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

#resize

Triggered when the dialog is being resized.
Properties:
Name Type Description
event Event jQuery event object
ui Object Empty object included for consistency with other events
  • event
    Type: Event
  • ui
    Type: Object
    • originalPosition
      Type: Object
      The CSS position of the dialog prior to being resized.
    • position
      Type: Object
      The current CSS position of the dialog.
    • originalSize
      Type: Object
      The size of the dialog prior to being resized.
    • size
      Type: Object
      The current size of the dialog.
Source:
Examples

Initialize the dialog with the resize callback specified:

$( ".selector" ).ojDialog({
    "resize": function( event, ui ) {}
});

Bind an event listener to the ojresize event:

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

#resizeStart

Triggered when the user starts resizing the dialog.
Properties:
Name Type Description
event Event jQuery event object
ui Object Empty object included for consistency with other events
  • event
    Type: Event
  • ui
    Type: Object
    • originalPosition
      Type: Object
      The CSS position of the dialog prior to being resized.
    • position
      Type: Object
      The current CSS position of the dialog.
    • originalSize
      Type: Object
      The size of the dialog prior to being resized.
    • size
      Type: Object
      The current size of the dialog.
Source:
Examples

Initialize the dialog with the resizeStart callback specified:

$( ".selector" ).ojDialog({
    "resizeStart": function( event, ui ) {}
});

Bind an event listener to the ojresizeStart event:

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

#resizeStop

Triggered when the user stops resizing the dialog.
Properties:
Name Type Description
event Event jQuery event object
ui Object Empty object included for consistency with other events
  • event
    Type: Event
  • ui
    Type: Object
    • originalPosition
      Type: Object
      The CSS position of the dialog prior to being resized.
    • position
      Type: Object
      The current CSS position of the dialog.
    • originalSize
      Type: Object
      The size of the dialog prior to being resized.
    • size
      Type: Object
      The current size of the dialog.
Source:
Examples

Initialize the dialog with the resizeStop callback specified:

$( ".selector" ).ojDialog({
    "resizeStop": function( event, ui ) {}
});

Bind an event listener to the ojresizeStop event:

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

Methods

#close() → {void}

Closes the dialog.

This method does not accept any arguments.

Properties:
Name Type Description
event Event jQuery event object
Source:
Fires:
Returns:
Type
void
Example

Invoke the close method:

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

#destroy()

Remove the dialog functionality completely. This will return the element back to its pre-init state.

This method does not accept any arguments.

Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Example

Invoke the destroy method:

var destroy = $( ".selector" ).ojDialog( "destroy" );

#getNodeBySubId(locator) → {Element|null}

Return the subcomponent node represented by the documented locator attribute values. Test authors should target sub elements using the following names:
  • oj-dialog-header: dialog header div
  • oj-dialog-body: dialog body div
  • oj-dialog-footer: dialog footer div
  • oj-dialog-content: dialog content div
  • oj-dialog-header-close: dialog header-close button
  • oj-resizable-n: North resizable handle
  • oj-resizable-e: East resizable handle
  • oj-resizable-s: South resizable handle
  • oj-resizable-w: West resizable handle
  • oj-resizable-se: Southeast resizable handle
  • oj-resizable-sw: Southwest resizable handle
  • oj-resizable-ne: Northeast resizable handle
  • oj-resizable-nw: Northwest resizable handle
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 - 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

Source:
Returns:
the subcomponent located by the subId string passed in locator, if found.

Type
Element | null

#isOpen()

Returns true if the dialog is currently open.

This method does not accept any arguments.

Properties:
Name Type Description
event Event jQuery event object
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Example

Invoke the isOpen method:

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

#moveToTop()

Moves the dialog to the top of the dialog stack.

This method does not accept any arguments.

Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Example

Invoke the moveToTop method:

var moveToTop = $( ".selector" ).ojDialog( "moveToTop" );

#open() → {void}

Opens the dialog.
Source:
Fires:
Returns:
Type
void
Example

Invoke the open method:

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

#setOptions(options)

Sets one or more options for the dialog.
Parameters:
Name Type Description
options A map of option/value pairs to set
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Example

Invoke the method:

$( ".selector" ).ojDialog( "option", {disabled: true});

#setOptions(key, value)

Sets one or more options for the dialog.
Parameters:
Name Type Description
key The name of the option name to set.
value A value to set for the option.
Source:
Returns:
When called via the public jQuery syntax, this method returns the object on which it was called, to facilitate method chaining.
Example

Invoke the method:

$( ".selector" ).ojDialog( "option", disabled, true);