(abstract) new ProcessDialog(configopt)
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 [OOjs UI documentation on MediaWiki][1] for more information and examples.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
config |
Object |
<optional> |
Configuration options |
- Source:
Example
// Example: Creating and opening a process dialog window.
function MyProcessDialog( config ) {
MyProcessDialog.parent.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.parent.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 ) {
var dialog = this;
if ( action ) {
return new OO.ui.Process( function () {
dialog.close( { action: action } );
} );
}
return MyProcessDialog.parent.prototype.getActionProcess.call( this, action );
};
var windowManager = new OO.ui.WindowManager();
$( 'body' ).append( windowManager.$element );
var dialog = new MyProcessDialog();
windowManager.addWindows( [ dialog ] );
windowManager.openWindow( dialog );
[1]: https://www.mediawiki.org/wiki/OOjs_UI/Windows/Process_Dialogs
Extends
Members
$overlay
Overlay element to use for the $overlay
configuration option of widgets that support it.
Things put inside of it are overlaid on top of the window and are not bound to its dimensions.
See
MyDialog.prototype.initialize = function () {
...
var popupButton = new OO.ui.PopupButtonWidget( {
$overlay: this.$overlay,
label: 'Popup button',
popup: {
$content: $( '<p>Popup contents.</p><p>Popup contents.</p><p>Popup contents.</p>' ),
padded: true
}
} );
...
};
Properties:
Type | Description |
---|---|
jQuery |
- Inherited From:
- Source:
Methods
(protected) attachActions()
Attach action actions.
- Overrides:
- Source:
close(dataopt) → {jQuery.Promise}
Close the window.
This method is a wrapper around a call to the window manager’s closeWindow method, which returns a closing promise resolved when the window is done closing.
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:
Promise resolved when window is closed
- Type
- jQuery.Promise
(protected) detachActions()
Detach action actions.
- Inherited From:
- Source:
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
getActionProcess(actionopt) → {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
getActions() → {OO.ui.ActionSet}
Get the set of actions used by the dialog.
- Inherited From:
- Source:
Returns:
- Type
- OO.ui.ActionSet
getActionWidgets(actions) → {Array.<OO.ui.ActionWidget>}
Get action widgets from a list of configs
Parameters:
Name | Type | Description |
---|---|---|
actions |
Array.<Object> | Action widget configs |
- Overrides:
- Source:
Returns:
Action widgets
- Type
- Array.<OO.ui.ActionWidget>
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
getClosestScrollableElementContainer() → {HTMLElement}
Get closest scrollable container.
- Inherited From:
- Source:
Returns:
Closest scrollable container
- Type
- HTMLElement
getContentHeight() → {number}
Get the height of the full window contents (i.e., the window head, body and foot together).
What consistitutes 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
getData() → {Mixed}
Get element data.
- Inherited From:
- Source:
Returns:
Element data
- Type
- Mixed
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
getElementDocument() → {HTMLDocument}
Get the DOM document.
- Inherited From:
- Source:
Returns:
Document object
- Type
- HTMLDocument
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
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
getElementWindow() → {Window}
Get the DOM window.
- Inherited From:
- Source:
Returns:
Window object
- Type
- Window
getHoldProcess(dataopt) → {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.
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
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
getReadyProcess(dataopt) → {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.
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
getSetupProcess(dataopt) → {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.
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
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
getSizeProperties() → {Object}
Get the size properties associated with the current window size
- Inherited From:
- Source:
Returns:
Size properties
- Type
- Object
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
getTeardownProcess(dataopt) → {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.
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
hold(dataopt) → {jQuery.Promise}
Hold window.
This is called by OO.ui.WindowManager during window closing, 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
initialize()
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
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
isElementAttached() → {boolean}
Check if the element is attached to the DOM
- Inherited From:
- Source:
Returns:
The element is attached to the DOM
- Type
- boolean
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
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
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
isVisible() → {boolean}
Check if the window is visible.
- Inherited From:
- Source:
Returns:
Window is visible
- Type
- boolean
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:
open(dataopt) → {jQuery.Promise}
Open the window.
This method is a wrapper around a call to the window manager’s openWindow method, which returns a promise resolved when the window is done opening.
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:
Promise resolved with a value when the window is opened, or rejected if the window fails to open. When the promise is resolved successfully, the first argument of the value is a new promise, which is resolved when the window begins closing.
- Type
- jQuery.Promise
ready(dataopt) → {jQuery.Promise}
Ready window.
This is called by OO.ui.WindowManager during window opening, 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
(protected) restorePreInfuseState(state)
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:
scrollElementIntoView(configopt) → {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
setData(data)
Set element data.
Parameters:
Name | Type | Description |
---|---|---|
data |
Mixed | Element data |
- Inherited From:
- Source:
setDimensions(dim)
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
|
- Overrides:
- Source:
setElementGroup(group)
Set group element is in.
Parameters:
Name | Type | Description |
---|---|---|
group |
OO.ui.mixin.GroupElement | null | Group element, null if none |
- Inherited From:
- Source:
setElementId(id)
Set the element has an 'id' attribute.
Parameters:
Name | Type | Description |
---|---|---|
id |
string |
- Inherited From:
- Source:
setManager(manager)
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
setSize(size)
Set the window size by symbolic name (e.g., 'small' or 'medium')
Parameters:
Name | Type | Description |
---|---|---|
size |
string | Symbolic name of size: |
- Inherited From:
- Source:
setup(dataopt) → {jQuery.Promise}
Setup window.
This is called by OO.ui.WindowManager during window opening, 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
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
teardown(dataopt) → {jQuery.Promise}
Teardown window.
This is called by OO.ui.WindowManager during window closing, 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
toggle(showopt)
Toggle visibility of an element.
Parameters:
Name | Type | Attributes | Description |
---|---|---|---|
show |
boolean |
<optional> |
Make element visible, omit to toggle visibility |
- Inherited From:
- Source:
Fires:
- event:visible
updateSize()
Update the window size.
- Inherited From:
- Source:
Throws:
-
An error is thrown if the window is not attached to a window manager
- Type
- Error
updateThemeClasses()
Update the theme-provided classes.
- Inherited From:
- Source: