s = CS.UI.showDialog(path := ...
ʃ, inputData := ... ʅ
ʃ, displayOptions := ...ʅ) | Argument | Description | Types / Required |
|---|
| path | The path of the HTML dialog to show. | string
required |
| inputData | The input data for the dialog. | string, number, boolean, array, object
not required |
| displayOptions | The display options to use when initially showing the dialog. | object
not required |
The
UI.showDialog action shows a
HTML dialog. HTML dialogs are shown as modal dialogs without an initial size, so the width and height of the dialog window must be specified. If you want to display HTML without worrying about sizing the window, you should use the
UI.view action.
The
path identifies an HTML dialog to show. CSPro includes
HTML templates in the installation folder for the dialogs that it uses for functions like
errmsg or
prompt. If
path does not identify a file provided by the user, it is evaluated based on the location of CSPro's HTML templates, or based on the overridden
HtmlDialogs property defined in the
PFF file. This allows you to show either custom or CSPro dialogs.
Specify
inputData if you want to pass input data to the dialog, which the dialog can retrieve using
UI.getInputData.
Optional
displayOptions allow you to pass initial display options to the dialog that can help with sizing the dialog. These options will be used by the window that hosts the dialog, and can also be queried using
UI.getDisplayOptions. These options include:
| Property | Platform | Value |
|---|
| "width" | All | The desired width, in display units or a percent, of the dialog. |
| "height" | All | The desired height, in display units or a percent, of the dialog, or the question text (on Windows only). |
| "resizable" | Windows | If true, the dialog can be resized. |
| "borderColor" | Windows | The color of the dialog border, which can be specified as a HTML color name (like "red") or a hex color code (like "#ff0000"). |
| "titleBarColor" | Windows | The color of the dialog's title bar. |
| "titleBarHeight" | Windows | The height, in display units, of the dialog's title bar. |
| "keyboard" | Android | If true, the soft keyboard is brought to the forefront when the dialog is shown. |
If a width and height are not specified to size the HTML dialog, CSPro will wait a few seconds before showing the dialog as it expectantly waits for a call to
UI.setDisplayOptions. This behavior is undesirable so it is important to specify the dialog's dimensions, either using
UI.setDisplayOptions or by specifying
displayOptions.
The action returns any result set by the HTML dialog using the
UI.closeDialog action. If no result was set, the action returns undefined.
The action throws an exception if any of its arguments are not specified in a valid form or if the dialog file does not exist or cannot be read.
<script>
const CS = new CSProActionInvoker();
// use the text-input.html dialog, used by the prompt logic function, to query for a password
CS.UI.showDialogAsync({
path: "text-input.html",
inputData: {
title: "Enter a Password",
password: true
}
})
.then(result => {
if( result !== undefined ) {
document.getElementById("password").value = result.textInput;
}
})
.catch(e => {
CS.UI.alertAsync({
text: e.message
});
});
</script>