Configuring custom dialogs
A dialog configuration has three main parts to match the three main parts of the dialog’s UI:
-
Title: The title of the dialog. This will display in the header of the dialog.
-
Body: The body of the dialog. The body component can be a panel or a tab panel, which can contain an array of panel components such as buttons, inputs and text.
-
Buttons: An array of footer buttons that are displayed in the dialog’s footer.
Basic example
The configuration for a basic dialog that displays HTML information might look like this:
tinymce.activeEditor.windowManager.open({
title: 'Dialog Title', // The dialog's title - displayed in the dialog header
body: {
type: 'panel', // The root body type - a Panel or TabPanel
items: [ // A list of panel components
{
type: 'htmlpanel', // an HTML panel component
html: 'Panel content goes here.'
}
]
},
buttons: [ // A list of footer buttons
{
type: 'submit',
text: 'OK'
}
]
});
Options
Name | Value | Requirement | Description |
---|---|---|---|
title |
string |
required |
The title of the dialog. This will display in the header of the dialog. |
body |
|
required |
The specification for the body component. |
buttons |
|
required |
An array of footer buttons to render in the footer of the dialog. |
size |
|
optional |
default: |
initialData |
object |
optional |
An object containing initial values for the dialog’s panel components. |
onAction |
|
optional |
Function invoked when a user interacts with a |
onSubmit |
|
optional |
Function invoked when a Submit type footer button is clicked. |
onCancel |
|
optional |
Function invoked when the dialog is cancelled. The dialog header’s close button and a Cancel type footer button invoke this function. |
onChange |
|
optional |
Function invoked when the value of an |
onClose |
|
optional |
Function invoked when the dialog is closed. The dialog header’s close button, a Cancel type footer button and the dialog instance API’s |
onTabChange |
|
optional |
This method only applies to tab panel dialogs. Function invoked when the user changes tabs. |
For more information on the dialogApi
object that is passed to some of the configuration options, see the dialog instance API documentation.
Event callback functions
Each of the event callback functions - onAction
, onSubmit
, onCancel
, onChange
, onClose
, and onTabChange
- are shared between all dialog components that may trigger them. For example, Custom type footer buttons and dialog panel buttons all trigger onAction
. Therefore, callback functions that may be triggered by multiple components are passed an object (called details
above) that contains the name
of the component that triggered the event.
Any callback function that is not passed a details
object assumes that the dialog will only contain one component which can trigger it or that it does not matter if the function is triggered by multiple components. For example, onSubmit
is only triggered when a user clicks on a Submit type footer button, and TinyMCE assumes that a dialog will only have one Submit type button. In comparison, onCancel
and onClose
are both triggered by clicking the X
button in the top right of a dialog or by clicking a Cancel type footer button. These two buttons have the same functionality, and therefore TinyMCE does not differentiate between them.