The
htmldialog function allows for the customization of CSPro dialogs in two ways. First, HTML templates can receive dynamic input data from the CSPro application which can be used as text in the dialogs or to change the behavior of the dialog. Second, user-created HTML templates give the application developer complete control of the appearance and behavior of the dialogs.
s = htmldialog(html_filename,
ʃinputData := input_data,ʅ
ʃdisplayOptions := display_optionsʅ); The
htmldialog function must be passed a a string expression,
html_filename, that specifies the HTML template to be used for the dialog.
In the first version, the optional string expression input_data argument allows input data to be passed to the HTML template.
In the second version, the optional
named argument input_data allows input data to be passed to the HTML template. The optional named argument
display_options argument is a
JSON string that allows control of the display settings. All possible display options are shown below in a table.
The function returns a string. The contents of the string are determined by the HTML template and returned by a JavaScript call to CSPro.returnData().
CSPro includes
HTML templates in the installation folder for the dialogs it uses. User-created HTML templates allow for further customization of the dialogs. When the
htmldialog function is called, the
html_filename is first searched for in the current application directory. If not found and a
HtmlDialogs directory override is specified in the
PFF file, that directory is searched. If a match is still not found, then the directory
html/dialogs in the CSPro installation folder is also searched.
Writing a user-created HTML template can be simplified by first selecting an existing HTML template that is most similar to the planned dialog. Make a copy of this HTML template in the current application directory and extend it to fit the new dialogs requirements.
The input data argument is a mechanism to pass data from the CSPro application to the HTML template. The contents of the input data could be a simple text string that represents a single value or a
JSON string that represents multiple values. The string contents of the input data are retrieved by calling
CSPro.getInputData() from the script block of the HTML template.
// Simple string
var inputString = CSPro.getInputData();
// JSON string
var inputJSON = JSON.parse(CSPro.getInputData());
The display options can be set using the optional named argument display_options in CSPro logic, or can be specifed as part of the HTML dialog by executing a JavaScript call to CSPro.setDisplayOptions(displayOptions).
| Name | Platform | Values |
|---|
| width | Both | Width in display units |
| height | Both | Height in display units |
| resizable | Windows | True, False |
| borderColor | Windows | CSS name or hex code (e.g., "black" or "#000000") |
| titleBarColor | Windows | CSS name or hex code |
| titleBarHeight | Windows | Height in display units |
| keyboard | Android | True, False (whether to show an on-screen keyboard) |
The default values for resizeable and keyboard are false. If a width and height are not specified, CSPro will wait a few seconds before showing the dialog as it expectantly waits for a call to CSPro.setDisplayOptions(displayOptions). This behavior is undesirable so it is important to specify the dialog width and height.
string input_data = '{ "title": "Enter Some Data!",'
' "multiline": true,'
' "allowEmptyText": false }';
string result = htmldialog("text-input.html", input_data);