OOUI/Windows/Window managers

OOUI
Introduction
About the library OOjs primer
Getting started
Creating interfaces programmatically PHP examples Using OOUI in MediaWiki
Working with widgets
Elements GroupElements FlaggedElements LookupElements DraggableElements Widgets Icons, Indicators, and Labels Buttons and Switches Selects and Options Inputs Popups Progress bars Layouts Fields and Fieldsets Forms Stacks and Panels Menus Booklets and Pages Index and TabPanels Windows Simple messages Dialogs Process Dialogs Message Dialogs Window managers Toolbars Themes Other concepts
See also
Fixing scripts and gadgets

Each window is managed by a WindowManager, which is used to open and close the window and control its presentation. Windows are added to the window manager by reference, symbolic name, or explicitly defined symbolic name. If a dialog class is registered with a factory (OO.factory), the factory can be used to instantiate the windows as needed. See #Using factories and symbolic names for an example.

Because managed windows are mutually exclusive, stacked/overlapping dialogs can be created using multiple WindowManager instances, where the order in the stack corresponds to the order by which the WindowManager instances are appended to the body.

Window managers can be configured to prevent interaction outside the window (by setting the modal option to true). For a full list of supported methods and configuration options, please see the code-level documentation.

For more information about the lifecycle of a window and the methods and promises the window manager calls and emits while directing this cycle, please see OOUI/Windows.

Using factories and symbolic names

Most of the examples in this documentation consist of windows that are instantiated and then added to a window manager by reference. Though useful for illustrating how windows are composed and managed, in practice, you will often find it useful to refer to windows by symbolic name instead. A symbolic name is specified with the Dialog class’s static name property or when a window is added by reference to the window manager (in this case, both a static name and the reference are passed like this: { symbolicName: myDialog }, and the two patterns can be used interchangeably).

Window classes must have a static name property in order to be registered with OO.Factory, which creates new window objects referred to by symbolic name, a practice that provides more flexibility than simply instantiating objects directly and referring to them only by reference. For example, a factory is often used in the following scenarios:

1. To reference a concept rather than an instance of it. If an application uses several types of similar windows (a simple and advanced help window, for example), a factory can be used to create and make available the appropriate version of the window as needed. Because the windows are referenced by their symbolic name (‘help’, in this example) the factory will simply create whichever ‘help’ window is requested, replacing an existing ‘help’ window with the new ‘help’ window if a previous version has been made.
2. To create windows only as needed. Windows can be registered with a factory using a symbolic window name as well as the name of the constructor that will be used to create it. The window is not actually instantiated until it is needed (i.e., when the window manager opens the window, the factory creates the new window on the fly).

Example: Referencing windows by symbolic name and using a factory to instantiate the windows as needed.

// Example: Window added to the window manager by symbolic name. The class used to instantiate the window must be registered with a factory, which will create the window as needed. Note that the window manager is configured to use the factory via its 'factory' config setting.

// Create a factory.
myFactory = new OO.Factory();

function MyDialog( config ) {
	MyDialog.super.call( this, config );
}
OO.inheritClass( MyDialog, OO.ui.Dialog );

// Specify a symbolic name (e.g., 'simple', in this example) using the static 'name' property.
MyDialog.static.name = 'simple';
MyDialog.static.title = 'Simple dialog';

MyDialog.prototype.initialize = function () {
	MyDialog.super.prototype.initialize.call( this );
	this.content = new OO.ui.PanelLayout( { padded: true, expanded: false } );
	this.content.$element.append( '<p>The window manager references this window by its symbolic name (\'simple\'). The symbolic name is specified with the dialog class\'s static \'name\' property. A factory is used to instantiate the window and add it to the window manager when it is needed.</p>' );
	this.$body.append( this.content.$element );
};

// Register the window constructor with the factory.
myFactory.register( MyDialog );

// Create a window manager. Specify the name of the factory with the ‘factory’ config.
var windowManager = new OO.ui.WindowManager( {
	factory: myFactory
} );
$( document.body ).append( windowManager.$element );

// Open window by symbolic name.
windowManager.openWindow( 'simple', { size: 'small' } );

Example: Referencing windows by explicitly defined symbolic name

// Example: Windows added to the window manager using explicitly defined symbolic names. This approach is useful when working with MessageDialogs (or any class that is not typically extended, making the name for all instances the same). Here, the MessageDialog class is instantiated twice and a symbolic name is explicitly defined for each instance. (Otherwise, both instances would use the same name, 'message', which is defined by the class.)

var windowManager = new OO.ui.WindowManager();
$( document.body ).append( windowManager.$element );
windowManager.addWindows( {
	confirmDelete: new OO.ui.MessageDialog( {
		title: 'Really delete?' 
	} ),
	confirmCreate: new OO.ui.MessageDialog( {
		title: 'Really create?'
	} )
} );
windowManager.openWindow( 'confirmCreate', { 
	message: 'This window was added to the window manager using an explicitly defined symbolic name.' 
} );