Plugin Form

SAInt-API is a powerful tool to automate the manual processes in the GUI. It gives access to multiple network and scenario data processing and execution functions. The API can be used with Python, C++, C#, and VisualBasic. In section "SAInt-API functions", we focus in describing the available functions in SAInt-API implemented for Python. In this section we provide a detailed overview of the structure and language syntax used in SAInt to create wizards and forms for plugins.

A plugin is an external self-contained executable program performing specialized tasks and interacting with SAInt. A plugin in SAInt has two components: the executable program called "main.exe", generally accepting a set of input parameters and producing certain outputs, and a dedicated graphical user interface like a "form" or a wizard called "form.yaml", which collects the input parameters from the user for the executable. These two components must be in the same folder for SAInt to recognized and, after validation, use the plugin. So a plugin has following structure:

example-plugin/
├── form.yaml
├── main.exe
└── <any_supporting_files_or_folders>

where

main.exe: The plugin executable. Arguments can be given by --field_name <field value> or a customized alternative.
form.yaml: A yaml file specifying the wizard behavior and looks. At a high level, it will take inputs from a user and send them to main.exe as arguments.
<any_supporting_files_or_folders>: Any files that may be required to execute main.exe. Commonly a folder called _internal for plugins built using pyinstaller.

The plugin executable is developed around one of the programming languages supported by the SAInt-API (e.g., Python), while the wizard is described in the remaining part of this section.

For examples of how to develop plugins in SAInt check the "Beginner Tutorial on Plugins Development".

1. Structure of "form.yaml"

The basic structure of the "form.yaml" is as follows:

wizard:
  title: ""
  pages:
    - name: ""
      title: ""
      description: ""
      page_sections:
        - name: ""
          mode: ""
          title: ""
          fields:
            - name: ""
              label: ""
              type: ""
              default_value: ""
              options:
                - display_name: ""
                  value: ""
                  dependent_fields:
                    - ""
              validation_rules:
                - type: ""
                  value: ""
                  message: ""
      page_navigation:
        conditional_navigations:
          - conditions:
              - field_name: ""
                operator: ""
                value: ""
            next_target: ""
        next_target: ""
        show_submit: ""
  navigation_elements:
    previous_button:
      label: ""
      color: ""
    next_button:
      label: ""
      color: ""
    submit_button:
      label: ""
      color: ""

We can breakdown the structure into parts, like:

# **************************************************************************************************************
# *************** If a field can have "[]" or "null", we don't have to specifically define them. ***************
# **************************************************************************************************************

wizard:
  title: "" #String
  pages: [] # Collection of pages
  navigation_elements: # This is fixed
    previous_button:
      label: ""
      color: ""
    next_button:
      label: ""
      color: ""
    submit_button:
      label: ""
      color: ""

page:
    name: "unique_page_name"
    title: "Page Title"
    description: "Page Description"
    page_sections: [] # Collection of sections in the page
    page_navigation: [] # Collection of navigation configuration in the page

page_section:
    name: "unique_page_section_name"
    mode: "Page Section Mode" # Fixed | Collapsed
    title: "Page Section Title"
    fields: [] # Collection of fields in the page_section

field:
  name: "unique_field_name"
  label: "Field Label" # Bold.
  type: "" # text | textbox | spineditor | dropdown | checkbox | toggleswitch | slider | fileexplorer | datetimepicker
  default_value: "" # Not Bold.
  value_format: null # Value Format is only available for the datetimepicker and the spineditor field types.
  options: [] # Collection of options in the field. Options are not available for the text, textbox and datetimepicker field types.
  validation_rules: []

options:
  display_name: "Display Name"
  value: ""
  dependent_fields: [] # Collection of the names of dependent fields. All fields that are referenced as dependent in an option, will be disabled by default when the form is loaded and only will be enabled if the option is selected.

validation_rule:
  type: "" # required | regex (currently regex is not supported) The required rule only applied if the field is enabled. There is no validation rule for the datetimepicker as it is always required by default.
  value: "" # value to validate against. "value" attribute is not used for the "required" validation type.
  message: "" # message to show if input is not valid

page_navigation:
  conditional_navigations: []
  next_target: "unique_page_name" # name of the next page
  show_submit: false # whether or not to show the submit on this page: false by default.

condition:
  field_name: "" # Name of the field
  operator: "" # Symbol of the operator: < | > | = | <>
  value: ""

The form accepts different input field types:

#------------------------
#------Input Fields------
#------------------------

# Text: (Not input) - Used for informative texts
field:
  name: "unique_field_name"
  label: "Text Label"
  type: "text"
  default_value: null
  options: [] # No options
  validation_rules: [] # No validation rule

# Text Box: (Input Field) - Allows users to enter text. Value Type: string
field:
  name: "unique_field_name"
  label: "Text Field"
  type: "textbox"
  default_value: null # Optional
  options: [] # No options
  validation_rules:
      - type: "required" # If it's required, it has to have a non-empty value.

# Spin Editor: (Input Field) - Allows users to enter a number. Value Type: decimal if "#.#"; integer if "#"
field:
  name: "unique_field_name"
  label: "Number Field"
  type: "spineditor"
  default_value: null # Default value attribute is not mandatory for spin editor control. If no value is defined in this form, the lower end of the accepted values/min value will be used as default
  value_format: "#.###" # If no value format is specified, "#" (int) will be used as the default.
  options:
    - display_name: null
      value: 0 # Lower end of the accepted values
      dependent_fields: []
    - display_name: null
      value: 10 # Upper end of the accepted values
      dependent_fields: []
  validation_rules:
    - type: "required" # Required for spin editor means it has to be set to a non-default option. It could make sense if the default value is 0.

# Dropdown (Select Box) - A collapsible list of options. Value Type: string
field:
  name: "unique_field_name"
  label: "Dropdown Field"
  type: "dropdown"
  default_value: "Opt2" # Default value attribute is not mandatory for the dropdown controls. If no default value is defined in this component, first option's value will be used as default
  options:
    # It is recommended to add the first option as "Please select..." and the value as null. If it is required, the user has to select another option.
    - display_name: "Please select..."
      value: null
      dependent_fields: []
    - display_name: "Option1"
      value: "Opt1"
      dependent_fields:
        - "unique_field_name_1"
        - "unique_field_name_2"
    - display_name: "Option2"
      value: "Opt2"
      dependent_fields:
        - "unique_field_name_1"
        - "unique_field_name_3"
    - display_name: "Option3"
      value: "Opt3"
      dependent_fields: []
    - display_name: "Option4"
      value: "Opt4"
      dependent_fields: []
  validation_rules:
    - type: "required" # Required for the dropdown means the selected option has to have a non-empty value.

# Checkboxes - Allow multiple selections. Value Type: list of string {"Opt1", "Opt3"}
field:
  name: "unique_field_name"
  label: "Checkbox Field"
  type: "checkbox"
  default_value: "Opt1,Opt2" # The comma separated values should have an exact match with the values. There shouldn't be a space after the comma. Valid --> "Opt1" | "Opt1,Opt2" ... Invalid --> "opt1, opt2" | "Opt1, Opt2"
  options:
    - display_name: "Option1"
      value: "Opt1"
      dependent_fields:
        - "unique_field_name_1"
        - "unique_field_name_2"
    - display_name: "Option2"
      value: "Opt2"
      dependent_fields:
        - "unique_field_name_1" # It is not recommended to add a dependent field in multiple options. If a field is referenced in multiple options, having 1 option as selected is enough to enable that field.
        - "unique_field_name_3"
    - display_name: "Option3"
      value: "Opt3"
      dependent_fields: []
  validation_rules:
    - type: "required" # Required for checkbox means at least one item has to be checked.

# Toggle Switch - Used for binary settings. If used in a form, it means this input is, somehow, required because there is no option to not select anything. Value Type: string
field:
  name: "unique_field_name"
  label: "Toggle Switch Field"
  type: "toggleswitch"
  default_value: "Opt2" # Default value attribute is not mandatory for the toggleswitch controls. If no value is defined in this form, first value will be used as default
  options: # Any option other than the first two options will be ignored for the toggleswitch controls
    - display_name: "Option1" # Left-hand side of the toggle
      value: "Opt1"
      dependent_fields:
        - "unique_field_name_1"
        - "unique_field_name_2"
    - display_name: "Option2" # Right-hand side of the toggle
      value: "Opt2"
      dependent_fields:
        - "unique_field_name_1"
        - "unique_field_name_2"
  validation_rules:
    - type: "required" # Required for toggleswitch means it has to be set to non-default option. e.g. This can be used to get the user consent.


# Sliders - Adjust values within a range. If used in a form, it means this input is somehow required because there is no option to not select anything. Value Type: int
field:
  name: "unique_field_name"
  label: "Slider Field"
  type: "slider"
  default_value: 0 # Default value attribute is not mandatory for the slider controls. If no value is defined in this form, first option's value will be used as default
  options: # Any option other than the first two options will be ignored for the slider controls
    - display_name: null
      value: 0 # Lower end of the slider
      dependent_fields: []
    - display_name: null
      value: 10 # Upper end of the slider
      dependent_fields: []
  validation_rules:
    - type: "required" # Required for slider means it has to be set to non-default option. It could make sense if the default value is 0.


# File Selection/Upload - Enables users to select files from file explorer. Value Type: string
field:
  name: "unique_field_name"
  label: "File Selection Field"
  type: "fileexplorer"
  default_value: "%userprofile%/Documents"  # Used to set the default search directory e.g. if set to null, the default search directory is set to "%userprofile%/Documents\encoord\SAInt-v3\DataImport"
  options: # List of supported file types, if set to [], we search for everything
    - display_name: "Excel Files"
      value: ".xlsx"
      dependent_fields: []
    - display_name: "Comma Separated Values Files"
      value: ".csv"
      dependent_fields: []
    - display_name: "Text Files"
      value: ".txt"
      dependent_fields: []
    - display_name: "All Files"
      value: ".*"
      dependent_fields: []
  validation_rules:
    - type: "required" # If it's required, it has to have a non-empty value.

# Folder selection - Enables users to select a folder Value Type: string
field
- name: "unique_field_name"
    label: "Folder Selection Field"
    type: "folderexplorer"
    default_value: "%userprofile%/Documents"
    validation_rules:
    - type: "required"

# Datetime selection - Enables users to select a datetime Value Type: datetime
field:
  name: "unique_field_name"
  label: "Datetime Selection Field"
  type: "datetimepicker"
  value_format: "dd/MM/yyyy HH:mm" # Value format is mandatory for the datetimepicker type. It can be selected as any valid date time format. If the HH:mm is not specified, DatePicker will be used instead of DateTimePicker.
  default_value: "01/01/2025 00:00" # Default Value has to match the format. If no default value is defined in this, DateTime.Now will be used.
  options: [] # No options
  validation_rules: [] # There is no validation rule for the datetimepicker because it is always required by default.
```

2. Environmental variables

The SAInt Wizard Form system supports environment variables that can be used within wizard form YAML configurations. This feature allows dynamic value injection into field default values, making the wizard forms more flexible and context-aware.

Environment variables are placeholders in your wizard form YAML configuration that get replaced with actual values at runtime. They allow you to:

Access SAInt system information (version, file paths, etc.);
Create context-aware default values;
Pass dynamic data between systems;
Store hidden values that don’t require user input.

Environment variables are specified using curly braces in the YAML configuration:

default_value: "{VariableName}"

You can also combine multiple variables or mix them with static text:

default_value: "SAInt Version {SAIntVersion}"
default_value: "{ENETDir}\\output.csv"
default_value: "{ENETPath}"

A list of available environmental variables is provided in Table 1.

A new field type hidden has been introduced to work seamlessly with environment variables. Hidden fields:

Do not appear in the wizard form UI;
Must have a default value;
Cannot have validation rules, options, or value formats;
Are useful for storing system-generated or environment-derived values.

Hidden Field Example

fields:
  - name: "system_version"
    label: "System Version"  # Label is still required but won't be displayed
    type: "hidden"
    default_value: "{SAIntVersion}"

Table 1. Supported environment variables in SAInt.
Variable Name	Description	Example Value
SAIntVersion	Current SAInt version	`3.8.0`
ENETPath	Electric network file path	`C:\Projects\MyProject\enet\electric.enet`
ENETDir	Electric network directory path	`C:\Projects\MyProject\enet`
ESCEPath	Electric scenario file path	`C:\Projects\MyProject\enet\electric.esce`
GNETPath	Gas network file path	`C:\Projects\MyProject\gent\gas.gnet`
GNETDir	Gas network directory path	`C:\Projects\MyProject\gnet`
GSCEPath	Gas scenario file path	`C:\Projects\MyProject\gnet\gas.gsce`
TNETPath	Thermal network file path	`C:\Projects\MyProject\tnet\thermal.tnet`
TNETDir	Thermal network directory path	`C:\Projects\MyProject\tnet`
TSCEPath	Thermal scenario file path	`C:\Projects\MyProject\tnet\thermal.tsce`
HUBSPath	Hubs network file path	`C:\Projects\MyProject\hubs\hubs.hubs`
HUBSTDir	Hubs network directory path	`C:\Projects\MyProject\hubs`
SAIntInstallPath	SAInt installation directory	`C:\Program Files\encoord\SAInt-v3-RC`
SAIntDocPath	SAInt user documents directory	`C:\Users\JacobKravits\Documents\encoord\SAInt-v3-RC`

Network and scenario path variables will return null if the corresponding network or scenario is not loaded.

The wizard form validation service automatically checks environment variables for:

Variable Existence: All referenced variables must be defined
Variable Names: Cannot be empty or whitespace
Value Resolution: Variables with null values are flagged

In case the validation fails, the error message provides details on the problem. For example, in case the variable does not exist, the message "Environment variable 'ProjectName' does not exist" is logged in the validation report. If the variable names is empty or with whitespaces, the error message is "Environment variable name cannot be empty".

Examples of the use of the environmental variables are:

Example 1

Display SAInt Version

wizard:
  pages:
    - name: "intro_page"
      sections:
        - name: "intro_section"
          mode: "Fixed"
          title: "Introduction"
          fields:
            - name: "version"
              label: "SAInt Version"
              type: "text"
              default_value: "SAInt {SAIntVersion}"

Example 2

Hidden System Information

fields:
  - name: "version"
    label: "SAInt version"
    type: "hidden"
    default_value: "{SAIntVersion}"

Example 3

Dynamic File Path

fields:
  - name: "output_file"
    label: "Output File Path"
    type: "fileexplorer"
    default_value: "{ENETDir}\\exports\\output.csv"
    validation_rules:
      - type: "required"

  - name: "user_comment"
    label: "Comment"
    type: "text"
    default_value: "Analysis for {SAIntVersion}"

Example 4

Multiple Variables

fields:
  - name: "export_info"
    label: "Export Information"
    type: "text"
    default_value: "Exporting from {ENETPath} using SAInt {SAIntVersion}"

3. Output Folder

When a specific folder is designated for generated files (e.g, generated SAInt networks/scenarios, results files, logs) it is an "output" folder. To designate a folder as an "output" folder it must have the type folderexplorer and have the field name output_folder.

For example:

name: "output_folder"
label: "Output Directory"
type: "folderexplorer"
default_value: "%userprofile%/Desktop"
validation_rules:
- type: "required"

generates an output folder of the name {plugin name}-{datetime of plugin run}. Importantly, if an HTML file is generated in this folder, SAInt will automatically open it in the HTML Viewer after the plugin is done running.

The specific operation logic is as follows:

If a folder browser is required;
- If the default value is provided in the YAML;
  - The text area of the Folder Browser Field should be populated with the default value
  - When the user clicks on browse;
    
    If there is a value in the text area, we should open that folder.
    
    If there is no value in the text area, we should open the last opened folder.
- If the default value is not provided in the YAML;
  - The text area of the Folder Browser Field should be populated with the last opened plugin address
  - When the user clicks on browse;
    
    If there is a value in the text area, we should open that folder.
    
    If there is no value in the text area, we should open the last opened folder.
If a folder browser is not required;
- If the default value is provided in the YAML;
  - The text area of the Folder Browser Field should not show anything
  - When the user clicks on browse;
    
    We should open the address of the default value
    
    If there is a value in the text area, we should open that address.
- If the default value is not provided in the YAML;
  - The text area of the Folder Browser Field should not show anything
  - When the user clicks on browse;
    
    We should open the last opened folder.
    
    If there is a value in the text area, we should open that address.