You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
125 lines
6.4 KiB
125 lines
6.4 KiB
= Configuring custom dialogs
|
|
:navtitle: Basic configuration
|
|
:description: How to create a basic dialog for TinyMCE.
|
|
:keywords: dialog, dialogapi, api
|
|
|
|
A dialog configuration has three main parts to match the three main parts of a dialog’s UI.
|
|
|
|
. *Title*
|
|
- the dialog’s title.
|
|
- It displays in the dialog’s header.
|
|
. *Body*
|
|
- the dialog’s body.
|
|
- The body component can be a xref:dialog-components.adoc#panel[panel] or a xref:dialog-components.adoc#tabpanel[tab panel], which can contain an array of xref:dialog-components.adoc#panel-components[panel components] such as buttons, inputs and text.
|
|
. *Buttons*
|
|
- An array of xref:dialog-footer-buttons.adoc[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:
|
|
|
|
[source,js]
|
|
----
|
|
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'
|
|
}
|
|
]
|
|
});
|
|
----
|
|
|
|
// Note: The configurationoptions anchor is needed for older external links
|
|
[[options]]
|
|
== [[configurationoptions]] Options
|
|
|
|
[cols="1,2,1,4",options="header"]
|
|
|===
|
|
|Name |Value |Requirement |Description
|
|
|title |string |required |The title of the dialog. This will display in the header of the dialog.
|
|
|body |`+panel+` or `+tabpanel+` component |required |The specification for the xref:dialog-components.adoc[body component].
|
|
|buttons |`+FooterButton[]+` |required |An array of xref:dialog-footer-buttons.adoc[footer buttons] to render in the footer of the dialog.
|
|
|size |`+'normal'+`, `+'medium'+` or `+'large'+` |optional |default: `+normal+`. `+normal+` sets the dialog to be responsive to the viewport size. `+medium+` sets the dialog to render with only the height required to fits its components. `+large+` sets the dialog to a large fixed height. `inline` dialogs do not support `size: 'large'`.
|
|
|initialData |object |optional |An object containing initial values for the dialog's panel components.
|
|
|onAction |`+(dialogApi, details) => void+` |optional |Function invoked when a user interacts with a `+button+` type panel component, clicks a *Custom* type footer button, or clicks an item in a *Menu* type footer button.
|
|
|onSubmit |`+(dialogApi) => void+` |optional |Function invoked when a *Submit* type footer button is clicked.
|
|
|onCancel |`+(dialogApi) => void+` |optional |Function invoked when the dialog is cancelled. The dialog header's close button and a *Cancel* type footer button invoke this function.
|
|
|onChange |`+(dialogApi, details) => void+` |optional |Function invoked when the value of an `+input+` type panel component changes.
|
|
|onClose |`+() => void+` |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 `+close()+` method invoke this function.
|
|
|onTabChange |`+(dialogApi, details) => void+` |optional |*This method only applies to xref:dialog-components.adoc#tabpanel[tab panel] dialogs.* Function invoked when the user changes tabs. `+details+` is an object that contains `+newTabName+` and `+oldTabName+`.
|
|
|===
|
|
|
|
For more information on the `+dialogApi+` object that is passed to some of the configuration options, see the xref:dialog-components.adoc#dialog-instance-api-methods[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 {productname} 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 {productname} does not differentiate between them.
|
|
|
|
[[configuration-parameters]]
|
|
== Configuration parameters
|
|
|
|
include::partial$configuration/dialog_align.adoc[]
|
|
|
|
include::partial$configuration/dialog_border.adoc[]
|
|
|
|
include::partial$configuration/dialog_buttons.adoc[]
|
|
|
|
include::partial$configuration/dialog_persistent.adoc[]
|
|
|
|
include::partial$configuration/dialog_streamContent.adoc[]
|
|
|
|
== Dialog position
|
|
|
|
By default a dialog is shown as a modal in the center of the editor viewport.
|
|
|
|
This presented position can be changed by providing a second argument, with an appropriate value, to xref:apis/tinymce.windowmanager.adoc#open[`editor.windowManager.open()`].
|
|
|
|
[[inline]]
|
|
=== `+inline+`
|
|
|
|
The `+inline+` option, passed to `editor.windowManager.open()`, sets the dialog’s presented position to one of two possiblities.
|
|
|
|
When added to a configuration with the value, `+toolbar+`, it sets the dialog to appear adjacent to the {productname} toolbar.
|
|
|
|
When added to a configuration with the value, `+bottom+`, it sets the dialog to appear at the bottom of the editor viewport.
|
|
|
|
*Type:* `+String+`
|
|
|
|
*Possible values:* `+toolbar+`, `+bottom+`
|
|
|
|
=== Basic example with the inline argument added and set to toolbar
|
|
|
|
[source,js]
|
|
----
|
|
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'
|
|
}
|
|
]
|
|
}, { inline: 'toolbar' });
|
|
----
|