Expand all

abstract OO.ui.ProcessDialog

Extends

Constructor

new OO.ui.ProcessDialog([config])abstract #

ProcessDialog windows encapsulate a process and all of the code necessary to complete it. If the process terminates with an error, a customizable error interface alerts users to the trouble, permitting the user to dismiss the error and try again when relevant. The ProcessDialog class is always extended and customized with the actions and content required for each process.

The process dialog box consists of a header that visually represents the ‘working’ state of long processes with an animation. The header contains the dialog title as well as two action widgets: a ‘safe’ action on the left (e.g., ‘Cancel’) and a ‘primary’ action on the right (e.g., ‘Done’).

Like other windows, the process dialog is managed by a window manager. Please see the [OOUI documentation on MediaWiki][1] for more information and examples.

Example

// Example: Creating and opening a process dialog window.
    function MyProcessDialog( config ) {
        MyProcessDialog.super.call( this, config );
    }
    OO.inheritClass( MyProcessDialog, OO.ui.ProcessDialog );

    MyProcessDialog.static.name = 'myProcessDialog';
    MyProcessDialog.static.title = 'Process dialog';
    MyProcessDialog.static.actions = [
        { action: 'save', label: 'Done', flags: 'primary' },
        { label: 'Cancel', flags: 'safe' }
    ];

    MyProcessDialog.prototype.initialize = function () {
        MyProcessDialog.super.prototype.initialize.apply( this, arguments );
        this.content = new OO.ui.PanelLayout( { padded: true, expanded: false } );
        this.content.$element.append( '<p>This is a process dialog window. The header ' +
            'contains the title and two buttons: \'Cancel\' (a safe action) on the left and ' +
            '\'Done\' (a primary action)  on the right.</p>' );
        this.$body.append( this.content.$element );
    };
    MyProcessDialog.prototype.getActionProcess = function ( action ) {
        if ( action ) {
            return new OO.ui.Process( () => {
                this.close( { action: action } );
            } );
        }
        return MyProcessDialog.super.prototype.getActionProcess.call( this, action );
    };

    const windowManager = new OO.ui.WindowManager();
    $( document.body ).append( windowManager.$element );

    const dialog = new MyProcessDialog();
    windowManager.addWindows( [ dialog ] );
    windowManager.openWindow( dialog );

[1]: https://www.mediawiki.org/wiki/OOUI/Windows/Process_Dialogs

Parameters:

Name Type Attributes Description
config Object optional

Configuration options
Source:

ProcessDialog windows encapsulate a process and all of the code necessary to complete it.

Properties

$focusTrapBefore #

Set focus traps

It is considered best practice to trap focus in a loop within a modal dialog, even though with 'inert' support we could allow focus to break out to the browser chrome.

Inherited from:
Source:

Set focus traps

It is considered best practice to trap focus in a loop within a modal dialog, even though with 'inert' support we could allow focus to break out to the browser chrome.

$overlay #

Overlay element to use for the $overlay configuration option of widgets that support it. Things put inside it are overlaid on top of the window and are not bound to its dimensions. See https://www.mediawiki.org/wiki/OOUI/Concepts#Overlays.

MyDialog.prototype.initialize = function () {
  ...
  const popupButton = new OO.ui.PopupButtonWidget( {
    $overlay: this.$overlay,
    label: 'Popup button',
    popup: {
      $content: $( '<p>Popup content.</p><p>More content.</p><p>Yet more content.</p>' ),
      padded: true
    }
  } );
  ...
};

Properties:

Type Description
jQuery
Inherited from:
Source:
Overlay element to use for the $overlay configuration option of widgets that support it.

Methods

attachActions()protected #

Attach action actions.

Overrides:
Source:
Attach action actions.

close([data]) → {OO.ui.WindowInstance} #

Close the window.

This method is a wrapper around a call to the window manager’s closeWindow method.

The window's #getHoldProcess and #getTeardownProcess methods are called during the closing phase of the window’s lifecycle and can be used to specify closing behavior each time the window closes.

Parameters:

Name Type Attributes Description
data Object optional

Window closing data
Inherited from:
Source:

Throws:

An error is thrown if the window is not attached to a window manager

Type
Error

Returns:

See OO.ui.WindowManager#closeWindow

Type
OO.ui.WindowInstance
Close the window.

detachActions() → {OO.ui.Dialog}protectedchainable #

Detach action actions.

Inherited from:
Source:

Returns:

The dialog, for chaining

Type
OO.ui.Dialog
Detach action actions.

executeAction(action) → {jQuery.Promise} #

Execute an action.

Parameters:

Name Type Description
action string

Symbolic name of action to execute
Overrides:
Source:

Returns:

Promise resolved when action completes, rejected if it fails

Type
jQuery.Promise
Execute an action.

focus([focusLast]) → {OO.ui.Window}chainable #

Focus the window

Parameters:

Name Type Attributes Default Description
focusLast boolean optional
 false

Focus the last focusable element in the window, instead of the first
Inherited from:
Source:

Returns:

The window, for chaining

Type
OO.ui.Window
Focus the window

getActionProcess([action]) → {OO.ui.Process} #

Get a process for taking action.

When you override this method, you can create a new OO.ui.Process and return it, or add additional accept steps to the process the parent method provides using the 'first' and 'next' methods of OO.ui.Process.

Parameters:

Name Type Attributes Description
action string optional

Symbolic name of action
Inherited from:
Source:

Returns:

Action process

Type
OO.ui.Process
Get a process for taking action.

getActions() → {OO.ui.ActionSet} #

Get the set of actions used by the dialog.

Inherited from:
Source:

Returns:

Type
OO.ui.ActionSet
Get the set of actions used by the dialog.

getActionWidget(config) → {OO.ui.ActionWidget} #

Get action widget from config

Override this method to change the action widget class used.

Parameters:

Name Type Description
config Object

Action widget config
Inherited from:
Source:

Returns:

Action widget

Type
OO.ui.ActionWidget

Get action widget from config

Override this method to change the action widget class used.

getActionWidgetConfig(config) → {Object} #

Get action widget config

Override this method to modify the action widget config

Parameters:

Name Type Description
config Object

Initial action widget config
Overrides:
Source:

Returns:

Action widget config

Type
Object

Get action widget config

Override this method to modify the action widget config

getActionWidgets(actions) → {Array.<OO.ui.ActionWidget>} #

Get action widgets from a list of configs

Parameters:

Name Type Description
actions Array.<Object>

Action widget configs
Inherited from:
Source:

Returns:

Action widgets

Type
Array.<OO.ui.ActionWidget>
Get action widgets from a list of configs

getBodyHeight() → {number} #

Get the height of the window body.

To get the height of the full window contents (the window body, head, and foot together), use #getContentHeight.

When this function is called, the window will temporarily have been resized to height=1px, so .scrollHeight measurements can be taken accurately.

Inherited from:
Source:

Returns:

Height of the window body in pixels

Type
number
Get the height of the window body.

getClosestScrollableElementContainer() → {HTMLElement} #

Get closest scrollable container.

Inherited from:
Source:

Returns:

Closest scrollable container

Type
HTMLElement
Get closest scrollable container.

getContentHeight() → {number} #

Get the height of the full window contents (i.e., the window head, body and foot together).

What constitutes the head, body, and foot varies depending on the window type. A message dialog displays a title and message in its body, and any actions in the foot. A process dialog displays a title and special actions in the head, and dialog content in the body.

To get just the height of the dialog body, use the #getBodyHeight method.

Inherited from:
Source:

Returns:

The height of the window contents (the dialog head, body and foot) in pixels

Type
number
Get the height of the full window contents (i.e., the window head, body and foot together).

getData() → {any} #

Get element data.

Inherited from:
Source:

Returns:

Element data

Type
any
Get element data.

getDir() → {string} #

Get the directionality of the frame (right-to-left or left-to-right).

Inherited from:
Source:

Returns:

Directionality: 'ltr' or 'rtl'

Type
string
Get the directionality of the frame (right-to-left or left-to-right).

getElementDocument() → {HTMLDocument} #

Get the DOM document.

Inherited from:
Source:

Returns:

Document object

Type
HTMLDocument
Get the DOM document.

getElementGroup() → {OO.ui.mixin.GroupElement|null} #

Get group element is in.

Inherited from:
Source:

Returns:

Group element, null if none

Type
OO.ui.mixin.GroupElement | null
Get group element is in.

getElementId() → {string} #

Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.

Inherited from:
Source:

Returns:

Type
string

Ensure that the element has an 'id' attribute, setting it to an unique value if it's missing, and return its value.

getElementWindow() → {Window} #

Get the DOM window.

Inherited from:
Source:

Returns:

Window object

Type
Window
Get the DOM window.

getHoldProcess([data]) → {OO.ui.Process} #

Get the 'hold' process.

The hold process is used to keep a window from being used in a particular context, based on the data argument. This method is called during the closing phase of the window’s lifecycle (before the closing animation). You can close dropdowns of elements in the window in this process, if they do not get closed automatically.

Override this method to add additional steps to the 'hold' process the parent method provides using the first and next methods of OO.ui.Process.

Parameters:

Name Type Attributes Description
data Object optional

Window closing data
Inherited from:
Source:

Returns:

Hold process

Type
OO.ui.Process
Get the 'hold' process.

getManager() → {OO.ui.WindowManager} #

Get the window manager.

All windows must be attached to a window manager, which is used to open and close the window and control its presentation.

Inherited from:
Source:

Returns:

Manager of window

Type
OO.ui.WindowManager
Get the window manager.

getReadyProcess([data]) → {OO.ui.Process} #

Get the ‘ready’ process.

The ready process is used to ready a window for use in a particular context, based on the data argument. This method is called during the opening phase of the window’s lifecycle, after the window has been setup (after the opening animation). You can focus elements in the window in this process, or open their dropdowns.

Override this method to add additional steps to the ‘ready’ process the parent method provides using the first and next methods of OO.ui.Process.

Parameters:

Name Type Attributes Description
data Object optional

Window opening data
Inherited from:
Source:

Returns:

Ready process

Type
OO.ui.Process
Get the ‘ready’ process.

getSetupProcess([data]) → {OO.ui.Process} #

Get the 'setup' process.

The setup process is used to set up a window for use in a particular context, based on the data argument. This method is called during the opening phase of the window’s lifecycle (before the opening animation). You can add elements to the window in this process or set their default values.

Override this method to add additional steps to the ‘setup’ process the parent method provides using the first and next methods of OO.ui.Process.

To add window content that persists between openings, you may wish to use the #initialize method instead.

Parameters:

Name Type Attributes Description
data Object optional

Window opening data
Inherited from:
Source:

Returns:

Setup process

Type
OO.ui.Process
Get the 'setup' process.

getSize() → {string} #

Get the symbolic name of the window size (e.g., small or medium).

Inherited from:
Source:

Returns:

Symbolic name of the size: small, medium, large, larger, full

Type
string
Get the symbolic name of the window size (e.g., small or medium).

getSizeProperties() → {Object} #

Get the size properties associated with the current window size

Inherited from:
Source:

Returns:

Size properties

Type
Object
Get the size properties associated with the current window size

getTagName() → {string} #

Get the HTML tag name.

Override this method to base the result on instance information.

Inherited from:
Source:

Returns:

HTML tag name

Type
string
Get the HTML tag name.

getTeardownProcess([data]) → {OO.ui.Process} #

Get the ‘teardown’ process.

The teardown process is used to teardown a window after use. During teardown, user interactions within the window are conveyed and the window is closed, based on the data argument. This method is called during the closing phase of the window’s lifecycle (after the closing animation). You can remove elements in the window in this process or clear their values.

Override this method to add additional steps to the ‘teardown’ process the parent method provides using the first and next methods of OO.ui.Process.

Parameters:

Name Type Attributes Description
data Object optional

Window closing data
Overrides:
Source:

Returns:

Teardown process

Type
OO.ui.Process
Get the ‘teardown’ process.

hold([data]) → {jQuery.Promise} #

Hold window.

This is called by OO.ui.WindowManager during window closing (before the animation), and should not be called directly by other systems.

Parameters:

Name Type Attributes Description
data Object optional

Window closing data
Inherited from:
Source:

Returns:

Promise resolved when window is held

Type
jQuery.Promise
Hold window.

initialize() → {OO.ui.Window}chainable #

Initialize window contents.

Before the window is opened for the first time, #initialize is called so that content that persists between openings can be added to the window.

To set up a window with new content each time the window opens, use #getSetupProcess.

Overrides:
Source:

Throws:

An error is thrown if the window is not attached to a window manager

Type
Error

Returns:

The window, for chaining

Type
OO.ui.Window
Initialize window contents.

isClosing() → {boolean} #

Check if the window is closing.

This method is a wrapper around the window manager's isClosing method.

Inherited from:
Source:

Returns:

Window is closing

Type
boolean
Check if the window is closing.

isElementAttached() → {boolean} #

Check if the element is attached to the DOM

Inherited from:
Source:

Returns:

The element is attached to the DOM

Type
boolean
Check if the element is attached to the DOM

isInitialized() → {boolean} #

Check if the window has been initialized.

Initialization occurs when a window is added to a manager.

Inherited from:
Source:

Returns:

Window has been initialized

Type
boolean
Check if the window has been initialized.

isOpened() → {boolean} #

Check if the window is opened.

This method is a wrapper around the window manager's isOpened method.

Inherited from:
Source:

Returns:

Window is opened

Type
boolean
Check if the window is opened.

isOpening() → {boolean} #

Check if the window is opening.

This method is a wrapper around the window manager's isOpening method.

Inherited from:
Source:

Returns:

Window is opening

Type
boolean
Check if the window is opening.

isVisible() → {boolean} #

Check if the window is visible.

Inherited from:
Source:

Returns:

Window is visible

Type
boolean
Check if the window is visible.

onFocusTrapFocused(event) #

Called when someone tries to focus the hidden element at the end of the dialog. Sends focus back to the start of the dialog.

Parameters:

Name Type Description
event jQuery.Event

Focus event
Inherited from:
Source:
Called when someone tries to focus the hidden element at the end of the dialog.

open([data]) → {OO.ui.WindowInstance} #

Open the window.

This method is a wrapper around a call to the window manager’s openWindow method.

To customize the window each time it opens, use #getSetupProcess or #getReadyProcess.

Parameters:

Name Type Attributes Description
data Object optional

Window opening data
Inherited from:
Source:

Throws:

An error is thrown if the window is not attached to a window manager

Type
Error

Returns:

See OO.ui.WindowManager#openWindow

Type
OO.ui.WindowInstance
Open the window.

ready([data]) → {jQuery.Promise} #

Ready window.

This is called by OO.ui.WindowManager during window opening (after the animation), and should not be called directly by other systems.

Parameters:

Name Type Attributes Description
data Object optional

Window opening data
Inherited from:
Source:

Returns:

Promise resolved when window is ready

Type
jQuery.Promise
Ready window.

restorePreInfuseState(state)protected #

Restore the pre-infusion dynamic state for this widget.

This method is called after #$element has been inserted into DOM. The parameter is the return value of #gatherPreInfuseState.

Parameters:

Name Type Description
state Object
Inherited from:
Source:
Restore the pre-infusion dynamic state for this widget.

scrollElementIntoView([config]) → {jQuery.Promise} #

Scroll element into view.

Parameters:

Name Type Attributes Description
config Object optional

Configuration options
Inherited from:
Source:

Returns:

Promise which resolves when the scroll is complete

Type
jQuery.Promise
Scroll element into view.

setData(data) → {OO.ui.Element}chainable #

Set element data.

Parameters:

Name Type Description
data any

Element data
Inherited from:
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set element data.

setDimensions(dim) → {OO.ui.Window}chainable #

Set window dimensions. This method is called by the window manager when the window is opening. In general, setDimensions should not be called directly.

To set the size of the window, use the #setSize method.

Parameters:

Name Type Description
dim Object

CSS dimension properties

Properties:
Name Type Attributes Default Description
width string | number optional
 ''

Width
minWidth string | number optional
 ''

Minimum width
maxWidth string | number optional
 ''

Maximum width
height string | number optional

Height, omit to set based on height of contents
minHeight string | number optional
 ''

Minimum height
maxHeight string | number optional
 ''

Maximum height
Overrides:
Source:

Returns:

The window, for chaining

Type
OO.ui.Window
Set window dimensions.

setElementGroup(group) → {OO.ui.Element}chainable #

Set group element is in.

Parameters:

Name Type Description
group OO.ui.mixin.GroupElement | null

Group element, null if none
Inherited from:
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set group element is in.

setElementId(id) → {OO.ui.Element}chainable #

Set the element has an 'id' attribute.

Parameters:

Name Type Description
id string
Inherited from:
Source:

Returns:

The element, for chaining

Type
OO.ui.Element
Set the element has an 'id' attribute.

setManager(manager) → {OO.ui.Window}chainable #

Set the window manager.

This will cause the window to initialize. Calling it more than once will cause an error.

Parameters:

Name Type Description
manager OO.ui.WindowManager

Manager for this window
Inherited from:
Source:

Throws:

An error is thrown if the method is called more than once

Type
Error

Returns:

The window, for chaining

Type
OO.ui.Window
Set the window manager.

setSize(size) → {OO.ui.Window}chainable #

Set the window size by symbolic name (e.g., 'small' or 'medium')

Parameters:

Name Type Description
size string

Symbolic name of size: small, medium, large, larger or full
Inherited from:
Source:

Returns:

The window, for chaining

Type
OO.ui.Window
Set the window size by symbolic name (e.g., 'small' or 'medium')

setup([data]) → {jQuery.Promise} #

Setup window.

This is called by OO.ui.WindowManager during window opening (before the animation), and should not be called directly by other systems.

Parameters:

Name Type Attributes Description
data Object optional

Window opening data
Inherited from:
Source:

Returns:

Promise resolved when window is setup

Type
jQuery.Promise
Setup window.

supports(methods) → {boolean} #

Check if element supports one or more methods.

Parameters:

Name Type Description
methods string | Array.<string>

Method or list of methods to check
Inherited from:
Source:

Returns:

All methods are supported

Type
boolean
Check if element supports one or more methods.

teardown([data]) → {jQuery.Promise} #

Teardown window.

This is called by OO.ui.WindowManager during window closing (after the animation), and should not be called directly by other systems.

Parameters:

Name Type Attributes Description
data Object optional

Window closing data
Inherited from:
Source:

Returns:

Promise resolved when window is torn down

Type
jQuery.Promise
Teardown window.

toggle([show]) → {OO.ui.Element}chainable #

Toggle visibility of an element.

Parameters:

Name Type Attributes Description
show boolean optional

Make element visible, omit to toggle visibility
Inherited from:
Source:

Fires:

Returns:

The element, for chaining

Type
OO.ui.Element
Toggle visibility of an element.

updateSize() → {OO.ui.Window}chainable #

Update the window size.

Inherited from:
Source:

Throws:

An error is thrown if the window is not attached to a window manager

Type
Error

Returns:

The window, for chaining

Type
OO.ui.Window
Update the window size.

updateThemeClasses() #

Update the theme-provided classes.

This is called in element mixins and widget classes any time state changes. Updating is debounced, minimizing overhead of changing multiple attributes and guaranteeing that theme updates do not occur within an element's constructor

Inherited from:
Source:
Update the theme-provided classes.