OOUI/Windows/Process Dialogs

Process dialog 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   class is always extended and customized with the methods and static properties 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 ActionWidgets:  a ‘safe’ action on the left (e.g., ‘Cancel’) and a ‘primary’ action on the right (e.g., ‘Done’). These actions are called ‘special’ actions. Any additional actions are called ‘other’ actions and are displayed in the dialog footer. Note that which actions are ‘special’ and which ‘other’ can be changed dynamically and/or accessed with the action set's  or   methods.

Simple example
The following example illustrates a process dialog window with two ActionWidgets (‘Cancel’ and ‘Done’) displayed in its header. The dialog body contains a layout and message. Note that the window is not populated with this content when it is instantiated. Instead, its contents are added just before the window is opened for the first time, when the window manager calls the window's  method. For an example of a window that is populated with contextual content passed at the time of opening, scroll down to the next example.

"WindowsProcessDialog1.png"

Both ‘safe’ and ‘primary’ actions are designated with flags that affect the action’s prominence in the dialog window: The ‘primary’ and ‘safe’ actions (as well as any other actions specified) comprise an ActionSet. An action set can consist of multiple action widgets configured with the same action and/or the same flags. If multiple ‘safe’ and ‘primary’ actions are specified, the process dialog renders the first 'safe' and 'primary' action in its header. If an action is changed--to use a new flag, for example--the user interface is updated accordingly. To defer updating the interface until after all actions have been changed, use the forEach method to iterate over the actions and update the user interface at the end of the iteration.
 * primary - The primary action (e.g., ‘save’ or ‘done’) moves the user forward in whatever process they are in. The primary action is the most important widget in the user interface, and its positioning--in the upper right corner of the dialog window-- reflects this.
 * safe - The safe action (e.g., ‘Cancel’) will make no changes. ‘Safe’ actions are usually configured without an action. Actions widgets that have no configured action will close the window without making changes.

Using window data to set value of a text input when opening the dialog
The next example illustrates how the getSetupProcess method is used to configure a window with contextual data that is passed at the time of opening.

"WindowsProcessDialog2.png"

For a full list of supported methods and configuration options for process dialogs, please see the code-level documentation.

Action sets
ActionSets manage the behavior of the actions that comprise them, allowing developers to control which actions are available for specific contexts (modes) and circumstances (abilities):
 * modes: When an action widget is configured with modes (e.g., ‘edit’ or ‘preview’), the action set can make the action available or not based on those modes (set with the  method). Each action will only be available if it is configured for the current mode. (See below example.)

The following example illustrates an action set that contains four action widgets: a primary action (‘continue’), two safe actions (‘cancel’ and ‘back’), and a ‘help’ action. Several of the actions have also been configured with modes: ‘edit’ or ‘help.’
 * abilities: When an action widget is configured with an action, the action set can make that action available or not based on abilities (set with the  method). If a ‘save’ action is used to save content, for example, abilities can be used to disable the action until the content is determined to be valid. If multiple action widgets execute the ‘save’ action, all will be disabled until the criteria are met.

The process dialog in the next example uses the above action set to customize available actions based on the modes.

"WindowsProcessDialogActionSet.png"

"WindowsProcessDialogActionSet2.png"

For a full list of supported methods and configuration options for action sets, please see the code-level documentation.

Processes and errors
Process dialogs execute a process, which is a list of ‘steps’ that are called in sequence. If the process fails, an error is generated. Depending on how the error is configured, users can dismiss the error and try the process again, or not.

Each ‘step’ of a process can be a number, a jQuery promise, or a function: A ‘step’ can be added to the beginning of a process with the  method, or to the end of it with the   method.
 * function: If the step is a function, the process will execute it. Optionally, a function context can be specified as well. The process will stop if the function returns a Boolean ‘false’.
 * promise: If the step is a  jQuery promise, the process will use the promise to either continue to the next step when the promise is resolved or to stop when the promise is rejected.
 * number: If the step is a number, the process will wait for the specified number of milliseconds before proceeding.

The process is started with the  method, which returns a promise that is either resolved when all steps have completed or rejected with an error message if any of the steps return a Boolean ‘false’ or a promise is rejected. If a process is stopped, its remaining steps will not be performed.

The error messages used by the process dialog are configured with a required string argument (or jQuery selection) that is used as the error message as well as optional settings ( or  ) that influence the appearance and functionality of the error interface.

The basic error message contains a formatted error message as well as two buttons: ‘Dismiss’ and ‘Try again’ (i.e., the error is recoverable by default). If recoverable is set to, the ‘Try again’ button will not be rendered and the widget that initiated the failed process will be disabled.

Errors can also be configured as warnings. If  is set to , the error interface will include a ‘Dismiss’ and a ‘Continue’ button, which will try the process again. A warning might be used before a destructive action, such as ‘Delete all files’ to confirm that this is the user’s intent. It is the responsibility of the developer to ensure that the warning is not triggered a second time if the user chooses to continue.

Note that the appearance of the error message can be customized by using a jQuery selection instead of a string for the value of the required message argument. A jQuery selection will allow you to add links and/or spans for styling select parts of the error message. The error title is not configurable.

The following is an example of a process dialog that has been configured to display a recoverable error message (for the ‘Save’ process) and a non-recoverable error message (for the ‘Delete’ process). The example also uses a time delay to demonstrate how the window visually represents a long-running process with a header animation.



For a full list of supported methods and configuration options, please see the code-generated documentation for processes and errors.