Best Practices
Spreadsheet Event Handler¶
The event handler script for a push button in a spreadsheet always has two arguments. One is the EventHandler and the other is the spreadsheet control raising the executing script event.
The EventHandler is the ISpreadsheetScriptEventSender type. It contains the information of the spreadsheet as well as information of all controls in the spreadsheet. The user can utilise this information to implement special functionalities. The EventHandler also provides many methods similar to those in the spreadsheet module to the user whilst working with a spreadsheet. For example, the “Walk-through: Make a spreadsheet event handler function” section uses the Controls property of the EventHandler to get the dropdown list control in the spreadsheet so that the user can work with this control. It uses the GetCellValue and SetCellValue methods of the EventHandler to get values from the spreadsheet and change values in the spreadsheet. Table 1 lists some important properties and methods of the EventHandler.
| Property/Method | Description |
|---|---|
| EventAction | Gets current sender’s event action, like ButtonClicked. |
| Spreadsheet | Gets current spreadsheet entity. |
| Controls | Gets all controls’ info in the spreadsheet. |
| EnableControl(string name) | Enable a control by name. |
| DisableControl(string name) | Disable a control by name. |
| GetAllControlNames() | Gets all controls’ names |
| SaveSpreadsheet() | Save the spreadsheet entity. |
| GetCellValue(string sheetName, string reference) | Gets cell’s value from the spreadsheet. |
| SetCellValue(string sheetName, string reference, object value) | Sets a cell’s value in the spreadsheet. |
| SaveTimeseriesToDatabase(string sheetName, string reference, TimeSeriesProperty property) | Save range data as a time series to the database. |
| SaveFeatureAttributesToDatabase(string sheetName, string reference, string featureClassPath) | Save range data as a feature class to the database. |
| SaveTimeseriesFromRange(string sheetName, string dateRange, string valueRange, TimeSeriesProperty property) | Save the data of date range and data of value range as a time series to the database. |
| SaveEnsembleTimeseriesFromRange(string sheetName, string reference, TimeSeriesProperty property) | Save range data as an ensemble time series to the database. |
Table 1: Properties and methods of EventHandler
The spreadsheet control argument provides the information of the control which raises the event, to execute a specified script. The user can retrieve the control’s name, type or text etc. The MIKE CUSTOMISED platform will now support executing a script by merely clicking a button. Table 2 lists the important properties of the spreadsheet control.
| Property/Method | Description |
|---|---|
| Name | Gets or sets control’s name. |
| Text | Gets or sets control’s text. |
| Enabled | Gets or sets a value indicating whether the control is enabled. |
| ControlType | Gets the control’s type. |
Table 2: Properties of the Control
ClearData() Method¶
The ClearData() method is a method of IDataSeries entity in the time series manager. It is responsible for clearing the time series data cached in memory. It is useful after the user calls GetAll() method of IDataSeries entity to get all data of a time series, as the GetAll() method will cache the data in the memory. If these data are not cleared when they are no longer used, a memory leak may occur. It is therefore recommended that the user should call ClearData() after using GetAll() method in his script.
Inserting Script Snippets¶
The MIKE CUSTOMISED platform provides functionality to insert script snippets in the script functions. The user can do this by making use of the script editor context menu. The following figure shows the menu for inserting a snippet.
Snippets menu
A snippets form will pop up after clicking the “Snippets…” menu (as shown in the figure below). This form lists all of the available snippets in the platform.
Snippets form
The platform provides some useful snippets, like getting the manager module, fetching an entity, setting a cell value in a spreadsheet or creating a spread sheet event handler function etc. Besides these default snippets, the user can add own snippets by means of the snippet manager as shown in the following figure. This snippet manager can be accessed through the tool button in the script editor.
Snippets manager
The user is able to add/edit/remove a snippet by making use of this manager.
Using Tools from Script¶
The MIKE CUSTOMISED platform provides a number of tools to the user. Each tool can implement a specific function. If the user wants to implement a functionality which also has a tool available through script, he can use the tool in the script directly, to reduce the amount of script code.
For the convenient use of a tool in script, the platform provides the following two ways to auto-generate script functions for tool execution.
- The user can get the tool scripts by dragging a tool from the tool explorer
and dropping it in the script editor. The following listing shows the
scripts generated in this manner.
Auto-generated script by dragging and dropping a tool in the script editor
The auto-generated script contains necessary-import/from statements, definition of tool execution script function, argument descriptions corresponding to the tool’s property descriptions and a return value corresponding to the tool output.
- Another option is to use the tool wrapper functionality from the script editor context menu. The figure below demonstrates the context menu of the editor.
Tool wrapper menu of script editor
If the user clicks the “Tool wrapper…” menu, the following tool wrapper dialog which provides additional configuration options, will appear.
Tool wrapper dialog
The user can select one or more tools and opt to include the tool’s property descriptions as documentation in the tool wrapper script function or to have a sample function added to demonstrate how to call the tool execution function. The next listing depicts the result of including the caller method and argument descriptions.
Auto-generated script by clicking “Tool wrapper…” menu
The “DoExportDocument” function is the caller method that demonstrates how to call the tool wrapper function “ExportDocument”. At the same time, the “ExportDocument” method has descriptions of arguments.
The above listings illustrate that both ways lead to the same result, i.e. generation of a script function with input parameters corresponding to the properties of the tool and a return value corresponding to the output of the tool.
Using Script from Job¶
The job manager of the MIKE CUSTOMISED platform has a task named “RunScript”. The user can find it in the “DSS Script Manager” category of the Task Selection Dialog. The following figure illustrates this dialog.
RunScript task
This task can be added to a job. After setting the values of its input parameters like the script path, the user can execute a script by running a job. This task also has an output entry which is the return value of the executed script. If the script has print statements, the print results will be stored in the job log and shown under the “Log” node in the job data view.
Scripts: Scoping Rules in scripts has changed¶
With MIKE OPERATIONS 2019.2, Python libraries has been upgraded to the version released with IronPython 2.7.9.
The new libraries enforces scoping rules described in the Python reference manual. This means that using “from module import *“ is now only allowed at module level (outside functions). If the syntax is used within a function, the error below will be displayed.
It is allowed to use “import *” at module level or specifying what to import.
Note that existing scripts using “import *” inside a function, will execute without errors as new scoping rules are enforced when saving the script.
Read more about Python scoping rules here. https://docs.python.org/2/whatsnew/2.1.html#pep-227-nested-scopes