Element: <oj-dialog>

Slots

JET elements can have up to two types of child content:

• Any child element with a slot attribute will be moved into that named slot, e.g. <span slot='startIcon'>...</span>. All supported named slots are documented below. Child elements with unsupported named slots will be removed from the DOM.
• Any child element lacking a slot attribute will be moved to the default slot, also known as a regular child. This is documented under the "Default" heading below.

Default

The default slot is the dialog's body. The <oj-dialog> element accepts DOM nodes as children for the default slot. The default slot can also be named with "body". For styling, the default body slot will be rendered with the oj-dialog-body class.

Since:

• 4.0.0

Examples

Initialize the Dialog with body content:

<oj-dialog>
  <div>Dialog Content</div>
</oj-dialog>

Initialize the Dialog with body content, explicitly naming the body slot:

<oj-dialog>
  <div slot="body">Dialog Content</div>
</oj-dialog>

contextMenu

The contextMenu slot is set on the oj-menu within this element. This is used to designate the JET Menu that this component should launch as a context menu on right-click, Shift-F10, Press & Hold, or component-specific gesture. If specified, the browser's native context menu will be replaced by the JET Menu specified in this slot.

The application can register a listener for the Menu's ojBeforeOpen event. The listener can cancel the launch via event.preventDefault(), or it can customize the menu contents by editing the menu DOM directly, and then calling refresh() on the Menu.

To help determine whether it's appropriate to cancel the launch or customize the menu, the ojBeforeOpen listener can use component API's to determine which table cell, chart item, etc., is the target of the context menu. See the JSDoc and demos of the individual components for details.

Keep in mind that any such logic must work whether the context menu was launched via right-click, Shift-F10, Press & Hold, or component-specific touch gesture.

Example

Initialize the component with a context menu:

<oj-some-element>
    <-- use the contextMenu slot to designate this as the context menu for this component -->
    <oj-menu slot="contextMenu" style="display:none" aria-label="Some element's context menu">
...
    </oj-menu>
</oj-some-element>

footer

The footer slot is for the dialog's footer area. The <oj-dialog> element accepts DOM nodes as children with the footer slot. For styling, the footer body slot will be rendered with the oj-dialog-footer class.

Since:

• 4.0.0

Example

Initialize the Dialog with body and footer content:

<oj-dialog>
  <div>Dialog Content</div>
  <div slot='footer'>Footer Content</div>
</oj-dialog>

header

The header slot is for the dialog's header area. The <oj-dialog> element accepts DOM nodes as children with the header slot. For styling, the header slot will be rendered with the oj-dialog-header class.

If a header slot is not specified by the user, a header will automatically be created. The automatically generated header will contain a close button, and the header title will be set to the dialog title.

Since:

• 4.0.0

Example

Initialize the Dialog with header and body content:

<oj-dialog>
  <div slot='header'>Header Content</div>
  <div>Dialog Content</div>
</oj-dialog>

Attributes

cancel-behavior :string

Specifies the cancel behavior of the dialog. The default value depends on the theme. In the alta-web theme, the default is "icon", and in alta-android, alta-ios and alta-windows themes, the default is "none".

Note that the cancelBehavior applies to both automatic and user-defined headers. So by default, a user-defined header in the alta-web theme will have a system generated close icon.

Supported Values:

Name	Type	Description
"escape"	string	The dialog will close when it has focus and user presses the escape (ESC) key. A close icon will not be created.
"icon"	string	A close icon will automatically be created. The dialog will close when it has focus and user presses the escape (ESC) key.
"none"	string	A close icon will not be created. No actions will be associated with the escape key.

Default Value:

• "icon"

Names

Item	Name
Property	cancelBehavior
Property change event	cancelBehaviorChanged
Property change listener attribute (must be of type function)	on-cancel-behavior-changed

Examples

Initialize the dialog to disable the default cancelBehavior

<oj-dialog cancel-behavior="none" ></oj-dialog>

Get or set the cancelBehavior property, after initialization:

// getter
var cancelBehavior = myDialog.cancelBehavior;

// setter
myDialog.cancelBehavior = "none";

Set the default in the theme (SCSS) :

$dialogCancelBehaviorOptionDefault: none !default;

drag-affordance :string

Specifies the drag affordance. The default value depends on the theme. In the alta-web theme, the default is "title-bar", and in alta-android, alta-ios and alta-windows themes, the default is "none".

Supported Values:

Name	Type	Description
"none"	string	The dialog will not be draggable.
"title-bar"	string	The dialog will be draggable by the title bar.

Default Value:

• "title-bar"

Names

Item	Name
Property	dragAffordance
Property change event	dragAffordanceChanged
Property change listener attribute (must be of type function)	on-drag-affordance-changed

Examples

Initialize the dialog to disable dragging dragAffordance

<oj-dialog drag-affordance="none" ></oj-dialog>

Get or set the dragAffordance property, after initialization:

// getter
var dragAffordance = myDialog.dragAffordance;

// setter
myDialog.dragAffordance = "none";

initial-visibility :string

Set the initial visibility of the dialog.

Supported Values:

Name	Type	Description
"hide"	string	The dialog will stay hidden until the open() method is called.
"show"	string	The dialog will automatically open upon initialization.

Default Value:

• "hide"

Names

Item	Name
Property	initialVisibility
Property change event	initialVisibilityChanged
Property change listener attribute (must be of type function)	on-initial-visibility-changed

Examples

Initialize the dialog with the initialVisibility property:

<oj-dialog initial-visibility="show" ></oj-dialog>

Get or set the initialVisibility property, after initialization:

// getter
var initialVisibility = myDialog.initialVisibility;

// setter
myDialog.initialVisibility = "show";

modality :string

Defines the modality of the dialog.

Supported Values:

Name	Type	Description
"modal"	string	The dialog is modal. Interactions with other page elements are disabled. Modal dialogs overlay other page elements.
"modeless"	string	Defines a modeless dialog.

Default Value:

• "modal"

Names

Item	Name
Property	modality
Property change event	modalityChanged
Property change listener attribute (must be of type function)	on-modality-changed

Examples

Initialize the dialog to a specific modality modality

<oj-dialog modality="modeless" ></oj-dialog>

Get or set the modality property, after initialization:

// getter
var modality = myDialog.modality;

// setter
myDialog.modality = "modeless";

position :oj.ojDialog.Position

Position object is used to establish the location the dialog will appear relative to another element. oj.ojDialog.Position defines "my" alignment "at" the alignment "of" some other thing which can be "offset" by so many pixels.

The "my" and "at" properties defines aligment points relative to the dialog and other element. The "my" property represents the dialog's alignment where the "at" property represents the other element that can be identified by "of". The values of these properties describe horizontal and vertical alignments.

Deprecated v3.0.0 jQuery UI position syntax; Use of a percent unit with "my" or "at" is not supported.

Names

Item	Name
Property	position
Property change event	positionChanged
Property change listener attribute (must be of type function)	on-position-changed

Examples

Initialize the dialog with position property specified:

<oj-dialog position.my.horizontal="left"
          position.my.vertical="top"
          position.at.horizontal="right"
          position.at.vertical="top" ></oj-dialog>

Get or set the position property, after initialization:

// getter
var position = myDialog.position;

// setter
myDialog.position =
   {"my": {"horizontal": "start", "vertical": "bottom"},
    "at": {"horizontal": "end", "vertical": "top" },
    "offset": {"x": 0, "y":5}};

position.at :Object

Defines which position on the target element ("of") to align the positioned element against.

Names

Item	Name
Property	position.at

position.at.horizontal :string

Supported Values:

Name	Type	Description
"center"	string
"end"	string	evaluates to "right" in LTR mode and "left" in RTL mode.
"left"	string
"right"	string
"start"	string	evaluates to "left" in LTR mode and "right" in RTL mode.

Default Value:

• "center"

Names

Item	Name
Property	position.at.horizontal

position.at.vertical :string

Supported Values:

Name	Type
"bottom"	string
"center"	string
"top"	string

Default Value:

• "center"

Names

Item	Name
Property	position.at.vertical

position.collision :string

Rule for alternate alignment.

Supported Values:

Name	Type	Description
"fit"	string	shift the element away from the edge of the window.
"flip"	string	the element to the opposite side of the target and the collision detection is run again to see if it will fit. Whichever side allows more of the element to be visible will be used.
"flipfit"	string	first applies the flip logic, placing the element on whichever side allows more of the element to be visible. Then the fit logic is applied to ensure as much of the element is visible as possible.
"none"	string	no collision detection.

Default Value:

• "fit"

Names

Item	Name
Property	position.collision

position.my :Object

Defines which edge on the dialog to align with the target ("of") element.

Names

Item	Name
Property	position.my

position.my.horizontal :string

Supported Values:

Name	Type	Description
"center"	string
"end"	string	evaluates to "right" in LTR mode and "left" in RTL mode.
"left"	string
"right"	string
"start"	string	evaluates to "left" in LTR mode and "right" in RTL mode.

Default Value:

• "center"

Names

Item	Name
Property	position.my.horizontal

position.my.vertical :string

Supported Values:

Name	Type
"bottom"	string
"center"	string
"top"	string

Default Value:

• "center"

Names

Item	Name
Property	position.my.vertical

position.of :string|Object

Which element to position the dialog against. If the value is a string, it should be a selector or the literal string value of window. Otherwise, a point of x,y. When a point is used, the values are relative to the whole document. Page horizontal and vertical scroll offsets need to be factored into this point - see UIEvent pageX, pageY.

Default Value:

• "window"

Names

Item	Name
Property	position.of

Example

Finding the point for an svg element:

var rect = svgDom.getBoundingClientRect();
var position = {of:{x:rect.left + window.pageXOffset, y:rect.top + window.pageYOffset}};

position.offset :Object

Defines a point offset in pixels from the ("my") alignment.

Names

Item	Name
Property	position.offset

position.offset.x :number

Horizontal aligment offset.

Default Value:

• 0

Names

Item	Name
Property	position.offset.x

position.offset.y :number

Vertical alignment offset.

Default Value:

• 0

Names

Item	Name
Property	position.offset.y

resize-behavior :string

Defines the resizeBehavior of the dialog. The default value depends on the theme. In the alta-web theme, the default is "resizable", and in alta-android, alta-ios and alta-windows themes, the default is "none".

Supported Values:

Name	Type	Description
"none"	string	The dialog will not be interactively resizable.
"resizable"	string	Thie dialog will be interactively resizable.

Default Value:

• "resizable"

Names

Item	Name
Property	resizeBehavior
Property change event	resizeBehaviorChanged
Property change listener attribute (must be of type function)	on-resize-behavior-changed

Examples

Initialize the dialog to a specific resizeBehavior resizeBehavior

<oj-dialog resize-behavior="none" ></oj-dialog>

Get or set the resizeBehavior property, after initialization:

// getter
var resizeBehavior = myDialog.resizeBehavior;

// setter
myDialog.resizeBehavior = "none";

Set the default in the theme (SCSS) :

$dialogResizeBehaviorOptionDefault: none !default;

role :string

The WAI-ARIA 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"

Names

Item	Name
Property	role
Property change event	roleChanged
Property change listener attribute (must be of type function)	on-role-changed

Examples

Initialize the dialog with the role property specified:

<oj-dialog role="alertdialog" ></oj-dialog>

Get or set the role property, after initialization:

// getter
var role = myDialog.role;

// setter
myDialog.role = "alertdialog";

translations :Object|null

A collection of translated resources from the translation bundle, or null if this component has no resources. Resources may be accessed and overridden individually or collectively, as seen in the examples.

If the component does not contain any translatable resource, the default value of this attribute will be null. If not, an object containing all resources relevant to the component.

If this component has translations, their documentation immediately follows this doc entry.

Names

Item	Name
Property	translations
Property change event	translationsChanged
Property change listener attribute (must be of type function)	on-translations-changed

Examples

Initialize the component, overriding some translated resources and leaving the others intact:

<!-- Using dot notation -->
<oj-some-element translations.some-key='some value' translations.some-other-key='some other value'></oj-some-element>

<!-- Using JSON notation -->
<oj-some-element translations='{"someKey":"some value", "someOtherKey":"some other value"}'></oj-some-element>

Get or set the translations property after initialization:

// Get one
var value = myComponent.translations.someKey;

// Set one, leaving the others intact. Always use the setProperty API for 
// subproperties rather than setting a subproperty directly.
myComponent.setProperty('translations.someKey', 'some value');

// Get all
var values = myComponent.translations;

// Set all.  Must list every resource key, as those not listed are lost.
myComponent.translations = {
    someKey: 'some value',
    someOtherKey: 'some other value'
};

(nullable) translations.label-close-icon :string

Label for the dialog close button.

See the translations attribute for usage examples.

Default Value:

• "Close"

Since:

• 3.0

Names

Item	Name
Property	translations.labelCloseIcon

Events

ojAnimateEnd

Triggered when a default animation has ended, such as when the component is being opened/closed or a child item is being added/removed. This event is not triggered if the application has called preventDefault on the animateStart event.

Properties:

All of the event payloads listed below can be found under event.detail.

Name	Type	Argument	Description
element	Element	<not nullable>	target of animation
action	"open" | "close"		The action that is ending the animation. The number of actions can vary from component to component. Suggested values are: "open" - when a dialog component is opened "close" - when a dialog component is closed

Examples

Bind an event listener to the onOjAnimateEnd property to listen for the "close" ending animation:

myDialog.onOjAnimateEnd = function( event )
  {
    // verify that the component firing the event is a component of interest and action
     is close
    if (event.detail.action == "close") {}
  };

The default open and close animations are controlled via the theme (SCSS) :

$dialogOpenAnimation: (effect: "zoomIn", fade: true)  !default;
$dialogCloseAnimation: (effect: "zoomOut", fade: true)  !default;

Specify an ojAnimateEnd listener via the DOM attribute:

<oj-dialog on-oj-animate-end='[[listener]]'></oj-dialog>

Specify an ojAnimateEnd listener via the JavaScript property:

myDialog.onOjAnimateEnd = listener;

Add an ojAnimateEnd listener via the addEventListener API:

myDialog.addEventListener('ojAnimateEnd', listener);

ojAnimateStart

Triggered when a default animation is about to start, such as when the component is being opened/closed or a child item is being added/removed. The default animation can be cancelled by calling event.preventDefault.

Properties:

All of the event payloads listed below can be found under event.detail.

Name	Type	Argument	Description
action	"open" | "close"		The action that is starting the animation. The number of actions can vary from component to component. Suggested values are: "open" - when a dialog component is opened "close" - when a dialog component is closed
element	Element	<not nullable>	target of animation
endCallback	function():void	<not nullable>	If the event listener calls event.preventDefault to cancel the default animation, It must call the endCallback function when it finishes its own animation handling and any custom animation has ended.

Examples

Bind an event listener to the onOjAnimateStart property to override the default "close" animation:

myDialog.onOjAnimateStart = function( event )
  {
    // verify that the component firing the event is a component of interest and action
     is close
    if (event.detail.action == "close") {
      event.preventDefault();
      oj.AnimationUtils.slideOut(event.detail.element).then(event.detail.endCallback);
  };

The default open and close animations are controlled via the theme (SCSS) :

$dialogOpenAnimation: ((effect: "zoomIn"), "fadeIn")  !default;
$dialogCloseAnimation: ((effect: "zoomOut", persist: "all"), "fadeOut")  !default;

Specify an ojAnimateStart listener via the DOM attribute:

<oj-dialog on-oj-animate-start='[[listener]]'></oj-dialog>

Specify an ojAnimateStart listener via the JavaScript property:

myDialog.onOjAnimateStart = listener;

Add an ojAnimateStart listener via the addEventListener API:

myDialog.addEventListener('ojAnimateStart', listener);

ojBeforeClose

Triggered before the dialog is dismissed via the close() method. The close can be cancelled by calling event.preventDefault().

Properties:

All of the event payloads listed below can be found under event.detail.

Name	Type	Description
event	Event	a custom event

Examples

Specify an ojBeforeClose listener via the DOM attribute:

<oj-dialog on-oj-before-close='[[listener]]'></oj-dialog>

Specify an ojBeforeClose listener via the JavaScript property:

myDialog.onOjBeforeClose = listener;

Add an ojBeforeClose listener via the addEventListener API:

myDialog.addEventListener('ojBeforeClose', listener);

ojBeforeOpen

Triggered before the dialog is launched via the open() method. The open can be cancelled by calling event.preventDefault().

Properties:

All of the event payloads listed below can be found under event.detail.

Name	Type	Description
event	Event	a custom event

Examples

Specify an ojBeforeOpen listener via the DOM attribute:

<oj-dialog on-oj-before-open='[[listener]]'></oj-dialog>

Specify an ojBeforeOpen listener via the JavaScript property:

myDialog.onOjBeforeOpen = listener;

Add an ojBeforeOpen listener via the addEventListener API:

myDialog.addEventListener('ojBeforeOpen', listener);

ojClose

Triggered after the dialog is dismissed via the close() method.

Properties:

All of the event payloads listed below can be found under event.detail.

Name	Type	Description
event	Event	a custom event

Examples

Specify an ojClose listener via the DOM attribute:

<oj-dialog on-oj-close='[[listener]]'></oj-dialog>

Specify an ojClose listener via the JavaScript property:

myDialog.onOjClose = listener;

Add an ojClose listener via the addEventListener API:

myDialog.addEventListener('ojClose', listener);

ojFocus

Triggered after focus has been transfered to the dialog.

Properties:

All of the event payloads listed below can be found under event.detail.

Name	Type	Description
event	Event	a custom event

Examples

Specify an ojFocus listener via the DOM attribute:

<oj-dialog on-oj-focus='[[listener]]'></oj-dialog>

Specify an ojFocus listener via the JavaScript property:

myDialog.onOjFocus = listener;

Add an ojFocus listener via the addEventListener API:

myDialog.addEventListener('ojFocus', listener);

ojOpen

Triggered after the dialog is launched via the open() method.

Properties:

All of the event payloads listed below can be found under event.detail.

Name	Type	Description
event	Event	a custom event

Examples

Specify an ojOpen listener via the DOM attribute:

<oj-dialog on-oj-open='[[listener]]'></oj-dialog>

Specify an ojOpen listener via the JavaScript property:

myDialog.onOjOpen = listener;

Add an ojOpen listener via the addEventListener API:

myDialog.addEventListener('ojOpen', listener);

ojResize

Triggered when the dialog is being resized.

Properties:

All of the event payloads listed below can be found under event.detail.

Name	Type	Description
event	Event	a custom event

Examples

Specify an ojResize listener via the DOM attribute:

<oj-dialog on-oj-resize='[[listener]]'></oj-dialog>

Specify an ojResize listener via the JavaScript property:

myDialog.onOjResize = listener;

Add an ojResize listener via the addEventListener API:

myDialog.addEventListener('ojResize', listener);

ojResizeStart

Triggered when the user starts resizing the dialog.

Properties:

All of the event payloads listed below can be found under event.detail.

Name	Type	Description
event	Event	a custom event 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.

Examples

Specify an ojResizeStart listener via the DOM attribute:

<oj-dialog on-oj-resize-start='[[listener]]'></oj-dialog>

Specify an ojResizeStart listener via the JavaScript property:

myDialog.onOjResizeStart = listener;

Add an ojResizeStart listener via the addEventListener API:

myDialog.addEventListener('ojResizeStart', listener);

ojResizeStop

Triggered when the user stops resizing the dialog.

Properties:

All of the event payloads listed below can be found under event.detail.

Name	Type	Description
event	Event	a custom event 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.

Examples

Specify an ojResizeStop listener via the DOM attribute:

<oj-dialog on-oj-resize-stop='[[listener]]'></oj-dialog>

Specify an ojResizeStop listener via the JavaScript property:

myDialog.onOjResizeStop = listener;

Add an ojResizeStop listener via the addEventListener API:

myDialog.addEventListener('ojResizeStop', listener);

Methods

close() → {void}

Closes the dialog.

Fires:

• oj.ojDialog#event:beforeClose
• oj.ojDialog#event:close
• oj.ojDialog#event:ojAnimationStart
• oj.ojDialog#event:ojAnimationEnd

Returns:

Type

void

Example

Invoke the close method:

myDialog.close();

getProperty(property) → {any}

Retrieves a value for a property or a single subproperty for complex properties.

Parameters:

Name	Type	Description
property	string	The property name to get. Supports dot notation for subproperty access.

Since:

• 4.0.0

Returns:

Type

any

Example

Get a single subproperty of a complex property:

var subpropValue = myComponent.getProperty('complexProperty.subProperty1.subProperty2');

isOpen() → {boolean}

Returns true if the dialog is currently open. This method does not accept any arguments.

The "open" state reflects the period of time the dialog is visible, including open and close animations.

Returns:

true if the dialog is open.

Type

boolean

Example

Invoke the isOpen method:

var isOpen = myDialog.isOpen();

open() → {void}

Opens the dialog.

Fires:

• oj.ojDialog#event:beforeOpen
• oj.ojDialog#event:open
• oj.ojDialog#event:ojAnimationStart
• oj.ojDialog#event:ojAnimationEnd

Returns:

Type

void

Example

Invoke the open method:

var open = myDialog.open();

refresh() → {void}

Refresh the dialog. Typically used after dynamic content is added to a dialog.

Returns:

Type

void

Example

Invoke the refresh method:

myDialog.refresh();

setProperties(properties) → {void}

Performs a batch set of properties.

Parameters:

Name	Type	Description
properties	Object	An object containing the property and value pairs to set.

Since:

• 4.0.0

Returns:

Type

void

Example

Set a batch of properties:

myComponent.setProperties({"prop1": "value1", "prop2.subprop": "value2", "prop3": "value3"});

setProperty(property, value) → {void}

Sets a property or a single subproperty for complex properties and notifies the component of the change, triggering a [property]Changed event.

Parameters:

Name	Type	Description
property	string	The property name to set. Supports dot notation for subproperty access.
value	any	The new value to set the property to.

Since:

• 4.0.0

Returns:

Type

void

Example

Set a single subproperty of a complex property:

myComponent.setProperty('complexProperty.subProperty1.subProperty2', "someValue");

Type Definitions

Position

Properties:

Name	Type	Argument	Description
my	oj.ojDialog.PositionAlign	<optional>	Defines which edge on the popup to align with the target ("of") element.
at	oj.ojDialog.PositionAlign	<optional>	Defines which position on the target element ("of") to align the positioned element against.
offset	oj.ojDialog.PositionPoint	<optional>	Defines a point offset in pixels from the ("my") alignment.
of	string | oj.ojDialog.PositionPoint	<optional>	Which element to position the popup against. If the value is a string, it should be a selector or the literal string value of window. Otherwise, a point of x,y. When a point is used, the values are relative to the whole document. Page horizontal and vertical scroll offsets need to be factored into this point - see UIEvent pageX, pageY.
collision	"flip" | "fit" | "flipfit" | "none"	<optional>	Rule for alternate alignment. "flip" the element to the opposite side of the target and the collision detection is run again to see if it will fit. Whichever side allows more of the element to be visible will be used. "fit" shift the element away from the edge of the window. "flipfit" first applies the flip logic, placing the element on whichever side allows more of the element to be visible. Then the fit logic is applied to ensure as much of the element is visible as possible. "none" no collision detection.

PositionAlign

Properties:

Name	Type	Argument	Description
vertical	"top" | "bottom" | "center"	<optional>	Vertical alignment.
horizontal	"start" | "end" | "left" | "center" | "bottom"	<optional>	Horizontal alignment. "start" evaluates to "left" in LTR mode and "right" in RTL mode. "end" evaluates to "right" in LTR mode and "left" in RTL mode.

PositionPoint

Properties:

Name	Type	Argument	Description
x	number	<optional>	Horizontal aligment offset.
y	number	<optional>	Vertical alignment offset.