Table of Contents

Simian GUI Documentation

Table of Contents

• Introduction
  • Matlab
  • Python
  • Form.io
• Getting started
  • MATLAB setup
    • License
  • Python setup
    • License
  • Hello world!
• Overview
• Form definition
  • guiInit
  • Form structure
  • Components
    • Basic
      • Button
      • Checkbox
      • Number
      • Password
      • Radio
      • Select
      • Selectboxes
      • TextArea
      • TextField
    • Advanced
      • Currency
      • DateTime
      • Day
      • Email
      • PhoneNumber
      • Signature
      • Survey
      • Tags
      • Time
      • Url
    • Layout
      • Columns
      • Content
      • FieldSet
      • Html
      • HtmlElement
      • HtmlTable
      • Panel
      • Table
      • Tabs
      • Well
    • Data
      • Container
      • DataGrid
      • DataMap
      • DataTables
      • EditGrid
      • Hidden
    • Miscellaneous
      • File
      • Form
      • Plotly
      • ResultFile
  • Component nesting
  • Component properties
    • Validate
    • Conditional
    • Logic
    • Json
    • Error
  • Composed components
    • StatusIndicator
  • Navbar
  • Simian Form Builder (beta)
• Handling events
  • guiEvent
  • Submission data
  • Caching state
  • Error handling
  • guiUpload
  • guiDownload
• Nested forms
• Advanced features
  • Custom CSS classes
  • Custom JavaScript
  • Focus lost event
  • Value changed event
• Tables
• Deployment
  • MATLAB
  • Python
• Example
• How to
  • How to add a piece of uneditable text?
  • How to place a button next to a textfield?
  • How to hide a component unless a condition is met?
  • How to disable a component unless a condition is met?
  • How to send an update to the form and immediately continue calculations?
  • How to change the options of my Select component?
  • How to change the options of my Selectboxes component?
  • How to use numbers with scientific notation?
• Testing
• Frequently asked questions (FAQ)
  • Form definition
  • Runtime
• Release notes
• Known issues & limitations

Upgrading from version 1.5.0

Introduction

Simian GUI provides an accessible way to define graphical user interfaces for your MATLAB or Python applications, that can be deployed on a server where they can be used by authorized users. The user interface can be developed using relatively basic code, focusing on GUI content specification and (mutual) positioning of interface components. In other words: the developer focuses on the final product, while more technical GUI aspects are handled by Simian GUI.

The key capabilities of Simian GUI are:

• Development of your models and the graphical user interface can be performed in the same environment (MATLAB or Python).
• Write the user interface definition in basic MATLAB or Python code. Utilize over 35 different customizable components to create the interface you want.
• The same codebase is used for local and deployed mode.
• Exploit the computational power of your deployment server instead of having to use that of your user’s machines.
• MATLAB: No MATLAB license required for each user when running deployed applications.
• No HTML/JavaScript/JSON knowledge required to create full-fledged user interfaces.

Simian GUI has a MATLAB and a Python implementation, both of which are described in this document. The pieces of code in this document are MATLAB or Python code, indicated by the and icons in the top-right of the code blocks. In these code snippets, the following imports are assumed to be made (and thus are not shown) in order to keep them readable:

• MATLAB:
  • simian.gui_v2_0_0.* where the release number 2_0_0 may vary.
• Python:
  • import simian.gui
  • from simian.gui import component
  • from simian.gui import composed_component
  • from simian.gui import component_properties
  • from simian.gui import utils

Parts of the documentation on name-value pairs show them in PascalCase: starting with an upper case character and starting every word with a capital letter. These name-value pairs are used in MATLAB. In Python, the name-value pairs are snake_cased: lower case with underscores separating the words. This means that if a name-value pair is documented as NestedForm, the input argument in Python becomes nested_form.

For an example of a form hosting the inputs and results of a model please refer to the Ball Thrower example.

MATLAB

Graphical user interfaces defined with the MATLAB version of Simian GUI can be tested and used in a native MATLAB figure. They can also be deployed on the MATLAB Production Server, which allows users with sufficient access (Active Directory) to access the tools through their internet browser in real-time. They do not require a MATLAB license or more computational power than is needed for the browser. The appearance of the GUI in local MATLAB mode is the same as that in deployed mode.

Simian GUI is supported in MATLAB releases R2020a to R2022b.

Workflow

The basic workflow of Simian GUI in combination with the MATLAB Production Server is illustrated in the image below.

Local use

While the tool is under development, using the MATLAB Production Server is not a necessity yet. The general workflow is as follows:

1. Start off by defining the form (GUI) initial states and underlying behavior in MATLAB. Tie the front-end to the back-end by specifying what event should trigger what computations.
2. The form is initialized in a MATLAB figure. In this figure, you can change values in the form using checkboxes, text fields etc.
3. When you are done making changes to the form, click a button that triggers a submission of the form data to the back-end (MATLAB). The computations you specified for that button are performed and updates are sent back to the form for the user to interact with.

Deployed use

Your tool can be used with the MATLAB Production Server using the following steps:

1. Generate an archive from your MATLAB code and deploy your tool on the MATLAB Production Server. This is described in Deployment.
2. Configure your Simian Portal to add a link to the deployed web app for the users.
3. A user can now access the tool from their favorite web browser without requiring an active MATLAB session. Since the application is the same as in local mode, the same edits can be made as in step 2 of the list above.
4. After a button is clicked, the data is submitted to the back-end (MATLAB Production Server) where computations are performed. Updates are sent back to the front-end (the user's web browser).

Python

Graphical user interfaces defined with Simian GUI can be tested and used locally with pywebview. The GUI can also be deployed on a server and can be accessed with an internet browser by users that have sufficient access rights. When deployed, the calculations behind the GUI are performed by the server and not the user's machine. The appearance and functionality of the GUI in local Python mode is the same as that in deployed mode.

Currently, Python versions 3.8 - 3.10 64 bit are supported. Windows, Linux and Mac operating systems are supported. To be able to use Simian GUI, a license file must be available.

Local use

During development of the GUI, it can be used and tested locally with pywebview. Refer to the Setup section for the steps required to do this.

Deployed use

When the GUI is ready it can be deployed on a server to reach a wider audience. There is not a standard deployment target for Python as there is with MATLAB. GUIs created with Simian GUI have successfully been deployed on the following environments (sorted alphabetically):

• Azure functions
• FastAPI
• Flask (Not suited for production)
• ownR

Other environments may also work as deployment target, but these have not been tried.

For more information on deployment, refer to the Deployment section.

When the web app code is deployed, the Simian Portal must be configured to connect with it, so that users can use it.

Form.io

Form.io is a form and data management platform for progressive web applications. It provides a structural approach to build and communicate with a front-end client interface that runs in the browser, and a back-end running on a server.

Simian GUI uses the front-end part of Form.io to build a user interface and interact with a back-end running on the Matlab Production Server or WSGI applications.

Forms

HTML forms are the common way to collect user input on a webpage. The Form.io framework builds upon this technology with its own JSON format for defining forms and to communicate data with the server. In turn, Simian GUI uses this format to bring the user input into a MATLAB or Python application.

To gain insight into the capabilities of Simian GUI, you can use the online form builder. It illustrates how Form.io forms can be constructed and what components and properties are available. This builder will not be used for the actual implementation of your application or tool and its behavior may differ. When you drag components from the left onto the form and change some of their properties, you can see the resulting interactive form at the bottom of the page. The definition of the form in JSON format is shown on the right. Below the form, you can see the submission data that will be sent to the back-end when an event is triggered (for example the push of a button), also in JSON format.

In MATLAB/Python, you write code to define the form (See Form definition). The resulting form definition is an object tree that will be converted to JSON for you. The submission data received from the front-end is converted from JSON into a struct/dict that is more easy to navigate and change. What the form builder does not show is that the submission data of the form can be updated by the back-end as well to perform certain actions such as filling a component with data or hiding/showing a component.

Getting started

This chapter describes the required setup for creating a form with Simian GUI, both in MATLAB and in Python.

The first step is to setup your project in MATLAB or Python. Then, it is time to create your first application as described in Hello world!.

A more elaborate example that illustrates the use of Simian GUI is shown in the Ball Thrower example application.

MATLAB setup

Requires the following resource:

• MATLAB Simian GUI release zip file.

Setup steps:

1. Unzip the archive with the MATLAB version of Simian GUI to the location where you want to use it. Refer to section Simian GUI contents for more information about its contents.

2. Run the install.p script.

3. Install your license as described in the License section.

Note In all code presented in the documentation, v2_0_0 must be substituted with the version number for the actual release that is used. It is recommended to use dynamic version numbers as explained here

Testing your setup

You can test your environment setup by running the following commands in MATLAB:

form = simian.gui_v2_0_0.Form();

If you get a Form object, your environment is setup correctly. You should also be able to start the BallThrower example locally by running the following command:

simian.local_v2_0_0.Uiformio("simian.examples_v2_0_0.ballthrower");

If you get an error, you can check this against these error messages and solutions:

• Unable to resolve the name simian.gui_v2_0_0.Form. Ensure that the the simian-gui folder is on the MATLAB path and that the version in the namespace corresponds with your Simian GUI version.
• Unable to resolve the name simian.local_v2_0_0.Form. Ensure that the the simian-local folder is on the MATLAB path and that the version in the namespace corresponds with your Simian GUI version.
• Unable to resolve the name 'simian.examples_v2_0_0.ballthrower' Ensure that the the simian-examples folder is on the MATLAB path and that the version in the namespace corresponds with your Simian GUI version.

Simian GUI contents

An overview of archive contents is shown in the figure below.

• Documentation The documentation of Simian GUI.
  • index.html The main page of the documentation.
• simian-examples Folder containing the included examples.
  • +simian
    • +examples_v2_0_0
      • @BallThrower Class implementing the ball throwing model.
      • +ballthrower The BallThrower application package. It contains the guiInit.m and guiEvent.m function files that define the user interface of the application.
• simian-gui Folder containing the Simian GUI code.
  • +simian
    • +gui_v2_0_0 Simian GUI package where the name contains the version number. When you use Simian GUI you must ensure that the correct name is used. Refer to the deployment section for tips on making this easier.
  • java Utilities required for running Simian GUI.
  • utils Utilities required for running Simian GUI.
  • config.json File containing the version number of the front-end.
• simian-local Folder containing the code to run Simian GUI locally.
  • +simian
    • +local_v2_0_0 Simian Local package where the name contains the version number. When you use Simian GUI you must ensure that the correct name is used. Refer to the deployment section for tips on making this easier.
  • html Folder containing the front-end build for uihtml.
• Contents.m Simian GUI version number.
• install.p Script that sets up Simian GUI for running applications locally.

Working with multiple releases

It is possible to work with, and deploy, multiple Simian GUI applications simultaneously, even if they use different Simian GUI releases. To facilitate this, the version numbers are included in the package namespace.

Therefore, the recommended approach is to dynamically select the Simian GUI package in your code.

1. Create a function that returns the required version number, e.g.:

   function simianGui = getSimianGui()
       simianGui = "gui_v2_0_0";
   end
   

2. Use the function to import or call the correct version of Simian GUI:

   % Direct calls:
   nr = simian.(getSimianGui()).component.Number("myKey");
   
   % Importing:
   import("simian." + getSimianGui() + ".*");
   nr = component.Number("myKey");
   

In order to update to a new release of Simian GUI, you only have to update the string returned by this function. All other files remain unchanged.

Alternatively, when not referencing the package dynamically, all calls to Simian GUI need to be updated to the new version. This may lead to a large number of changes. Extra care is required when using version control and multiple braches are under development simultaneously.

In order to update your code to a newer Simian GUI release, use the updateVersion function included in the Simian GUI package. This function edits the version number in all m-files in a given folder and its sub-folders. For example: simian.gui_v2_0_0.updateVersion("C:\Applications\MyApp"). Save all m-files and make a back-up before you run this function!

License

To be able to use the MATLAB version of Simian GUI a license file for Simian GUI must be available in a location where it can be found.

The location of the license file is either:

• On a floating license server, which can be specified by setting the MONKEYPROOF_FLOATING_LICENSE_SERVER environment variable to the address and port (separated by a colon) of the license server.
• In a custom folder, specified by setting the MONKEYPROOF_LICENSE_FILE_FOLDER environment variable.
• The default folder, which can be found by running fullfile(settings().matlab.addons.InstallationFolder.ActiveValue, 'Licenses') on the MATLAB command line.

Depending on your license type, it may be necessary to retrieve and/or activate the license the first time the application is started. In that case the license dialog appears, which allows you to specify a product key or activate the license.

License dialog

License information

• License ID The license ID is a unique reference to the license, created when the license was purchased.
• Activation ID The activation is a unique reference to an activation, created when the license was activated.
• License status Shows the current status of the license (validity and activation). If the text in this field is red, either action is required or an error occurred.
  • No license The license file has not been found: use the “Change product key” and specify the requested details.
  • Validation: LICENSE_VALID  Activation: ACTIVATION_REQUIRED The license needs to be activated: use the “Activate” button.
  • Other Go to the support forum for assistance.
• Expiration date This is the expiration date of the license. Maintenance can be purchased in the webshop.

User Information

• Name Name of the user to which the product is licensed.
• Email Email address used to purchase the license.
• Company Company of the licensee.

Change product key

Specify the product key sent to you by email and the user's name and company as were specified during purchase.

Activate

When the Activate button is clicked, the Activation Dialog appears. It shows the end user license agreement, which needs to be accepted to activate the license.

Deactivate

Deactivates the license to make it available for activation on another machine. The number of allowed deactivations is limited.

Show Hardware IDs

The Hardware IDs dialogs shows the IDs of a number of properties that can be used for offline activation. The right-click menu offers the option to copy all IDs to the clipboard.

Enter Modification Key

If you receive a license modification key, you can enter it here.

Show EULA

Shows the end user license agreement.

Python setup

Requires the following resources:

• An internet connection to download and install Simian GUI from our PyPi server (or an offline alternative).
• A Python Simian license file valid for your machine.

Setup steps:

1. Create and activate a Python environment.

   Note: Use Python 3.8 - 3.10. Python 3.11 and later are not supported at the moment.

2. Install the packages using pip:

   pip install --extra-index-url https://pypiserver.monkeyproofsolutions.nl/simple/ simian-gui simian-local simian-examples
   

   Note that for installation on a deployment server the simian-local and simian-examples packages are not required.

   1. The simian-local package installs pywebview as a dependency. To verify it is installed correctly on your system, run the following python commands. A window, displaying the PyWebview web page, should open.

      import webview
      webview.create_window('Hello world', 'https://pywebview.flowrl.com/')
      webview.start()
      

   2. If you want to use Redis cache (for deployed mode) it can be specified as optional dependency of the simian-gui:

      pip install simian-gui[redis]
      

   3. If you need to troubleshoot license failures, you may also want to install the pyarmor dependency.

      pip install simian-gui[pyarmor]
      

3. Make your license file available by specifying its location in the PYARMOR_LICENSE environment variable, as documented in the license section

Testing your setup

You can test your environment setup by running the following commands in your Python environment:

from simian.entrypoint import assert_simian_gui_imports

assert_simian_gui_imports()

This will throw an error when your license is not valid or cannot be found. License errors and potential solutions are described in the Invalid license message section.

import simian.gui
form = simian.gui.Form()

If you get a Form object, your environment is setup correctly. If pywebview is installed correctly in your Python environment, you should be able to start the BallThrower example locally by running the following commands:

import simian.local
simian.local.Uiformio("simian.examples.ballthrower", window_title="Ball Thrower")

If you get an error, you can check this against these error messages and solutions:

• ModuleNotFoundError: No module named 'simian' Simian GUI was not found on the Python path. Ensure that the simian-gui and simian-local packages are installed.

• ModuleNotFoundError: No module named 'simian.examples.ballthrower' The simian-examples package was not found on the Python path. Ensure that the simian-examples package is installed.

• ModuleNotFoundError: No module named xxx Ensure that all dependencies are installed in your Python environment.

Simian GUI contents

A full Simian GUI installation in your Python environment installs the following folders and files in the site-packages folder:

From simian-examples:

• simian
  • examples
    • all_components.py Web app with all components that can be used in Simian.
    • ballthrower.py Web app with the BallThrower application. It contains the gui_init and gui_event functions that define the user interface of the application.
    • ballthrower_engine.py Module with a class that implements the ball throwing model.
    • plot_types.py Web app showing some of the Plotly figures that can be used in Simian.
    • workshop_example.py Web app showing a DataTable and Plotly figure in use.
    • wrapped_thrower.py Web app with the BallThrower and a engine that is wrapped with Simian Wrapper.
  • version.txt version information.

From simian-gui:

• pytransform: Utility for license validation.
• simian
  • gui Folder containing Simian GUI code.
  • config.json File containing the version number of the front-end.
  • entrypoint.py Utility for handling callbacks.
  • version.txt version information.

From simian-local:

• simian
  • html Folder containing the front-end build for PyWebview.
  • eventh_handler.py Utility for communication with tht PyWebview window.
  • local.py The Simian Local module.
  • local.pyi Python stub file containing type hints for the local.py module.

License

To be able to use the Python version of Simian GUI a license file for Simian GUI must be available in a location where it can be found by the PyArmor license mechanism that is in Simian GUI.

To ensure the license file can be found, it must be made available in one of the following ways:

• Set the PYARMOR_LICENSE environment variable to the absolute file path of the license file, for instance by putting it in Python's sys.PYARMOR_LICENSE variable.
• Put the license file in the pytransform package that is installed with simian-gui.

If no valid license file is available, an error is thrown and the form is not shown.

When contacting us about a license issue, please provide the contents of your license.lic.txt file and the information described in the next section for a quicker resolution.

Getting license information

Information about a license file can be read from the text file that came with it. This license information can be compared with information about your environment. This information can be obtained with two utility functions in the simian.entrypoint module:

• The get_info_for_license function writes relevant information of the machine that runs Simian GUI to the console. This information can be used to get a license file that is valid for that machine.

  As an alternative you can install PyArmor and use the hdinfo function directly.

• The get_license_info function prints some information about Simian GUI to the console.

Note that for these utilities to work you either need Simian GUI with a valid license or have PyArmor installed in your Python environment. The simian.entrypoint tries to run these functions when a license problem was encountered, but then requires PyArmor to be installed.

Invalid license message

When no valid license can be found, the simian.entrypoint raises a RuntimeError with a message on the violation:

1. Read file license.lic failed, No such file or directory No license file was found. If you have one, make sure it can be found as described earlier in this section.

2. License is expired the license expiry date was exceeded. You need a new license.

3. 'sys.PYARMOR_LICENSE': '<value>' is not an existing file. Python could not find the file specified in the PYARMOR_LICENSE environment variable. Review the full file name and ensure that it points to your license file.

4. License is not for this machine The license is bound to environment properties that do not match with the environment that Simian GUI is currently being used on. For disambiguation of the message refer to the logs (described below) that may contain more information on the issue.

   1. License is bound to another domain.
   2. License is bound to another Python interpreter.
   3. Mac address in license does not match a mac address of the deployment environment.
   4. License contains a disk name that cannot be matched to the deployment environment.
   5. License is bound to another ipv4 address.

5. License checker: Marshal loads failed Your environment is not supported by this Simian GUI version. Use a Python version and operating system that are supported.

6. Invalid product license file

   1. License file could not be read by PyArmor. Ensure that it exists and that it is a Simian GUI license.lic file.
   2. License is bound to a domain, whereas you are not on a domain.

7. Check license failed, Invalid input packet The license that was found by PyArmor is not for Simian GUI.

8. NameError("name '__pyarmor__' is not defined") Simian GUI code was not unpacked correctly. Put the following code snippet in your wrapper function, which should ensure that the unpacking is triggered.

   # Call the PyArmor runtime to ensure it is started.
   import pytransform
   pytransform.pyarmor_runtime()
   

9. Get mac address failed The license contains an invalid mac address. Contact us.

10. License file contains an unexpected data type <type>. The license file was not read in correctly or contains incorrect information. Please contact us.

11. License file contains an unsupported environment <environment>. Simian GUI version that you are using cannot determine the validity of license files for the shown environment and thus throws an error. The environment may be supported in a newer version of Simian GUI.

12. Azure specific messages:

13. Could not get Azure Subscription Information. Check that this is an Azure environment. Simian GUI was unable to determine the Azure Subscription of the environment it is used on. Ensure that you are deploying on Azure.

14. License is not for this Azure Subscription <id>. License is only valid for another Azure Subscription. Use Simian GUI on the Azure Subscription that this license is for.

15. License file does not contain an Azure subscription id. This is not supported. The license file does not contain an Azure Subscription ID. This is not supported by Simian GUI version that you are using. The environment may be supported in a newer version of Simian GUI.

16. ownR specific messages:

    1. Could not get ownR license Information. Check that this is an ownR environment. Simian GUI was unable to determine the ownR license ID of the environment it is used on. Ensure that you are deploying on ownR.
    2. License is not for this ownR environment <License id> License is only valid for another ownR environment. Use Simian GUI on the ownR environment that this license is for.
    3. License file does not contain an ownR license id. This is not supported. The license file does not contain an ownR license ID. This is not supported by Simian GUI version that you are using. The environment may be supported in a newer version of Simian GUI.

If the error message you are getting is not in this list, check whether it is listed on the PyArmor website. If it is also not listed there, contact us.

The simian.entrypoint also tries to write information on the license and environment to the log. However, this only works when pyarmor is installed in your Python environment. If it is not installed and the utilities in Simian GUI do not work due to an invalid licence, a RuntimeError with the following message is raised:

No working PyArmor utilities available for getting the license and environment information. No valid license found. Ensure that PyArmor can find it, or (temporarily) install PyArmor in the Python environment for extra license and environment information.

Hello world!

Prerequisites

Ensure that Simian GUI for your programming language is available (unzipped) on your machine and that it is on the path. You need to be able to run the functionality in Simian GUI to be able to use it.

The editor you are using should offer tab completion, code analysis, linting and other hints during programming when Simian GUI is available to the editor.

The steps to setup a working environment be found in:

• MATLAB Setup
• Python Setup

First application

We will start with creating an empty application, that only has a title and logo.

MATLAB

In MATLAB, an application is a package folder containing two functions: guiInit to define the form and guiEvent to handle events.

Create a folder +hello and add the m-files guiInit.m and guiEvent.m. Make sure the containing folder is on the MATLAB path.

+hello/
    guiInit.m
    guiEvent.m

guiInit.m

function payload = guiInit(metaData)
    import simian.gui_v2_0_0.*;

    % Create a form and add it to the payload.
    form            = Form();
    payload.form    = form;
    
    % Set a logo and title.
    payload.navbar.logo = "favicon.ico";
    payload.navbar.title = "Hello, World!";
end

guiEvent.m

function payload = guiEvent(metaData, payload)
    import simian.gui_v2_0_0.*;

    % Process the events.
end

Start the application from the command line:

simian.local_v2_0_0.Uiformio("hello")

A MATLAB figure will open, showing the empty application as in the figure below the Python example.

Note: Substitute v2_0_0 with the actual version that you are using.

Python

In Python, an application is a module containing two functions: gui_init to define the form and gui_event to handle events.

Create a file hello.py. Make sure the containing folder is on the Python path.

hello.py

from simian.gui import component
from simian.gui import Form
from simian.gui import utils

def gui_init(meta_data: dict) -> dict:
    # Create a form and set a logo and title.
    form = Form()

    payload = {
        "form": form,
        "navbar": {
            "logo": "favicon.ico",
            "title": "Hello, World!",
        },
    }

    return payload

def gui_event(meta_data: dict, payload: dict) -> dict:
    # Process the events.
    return payload

Start the application from the Python console:

import simian.local
simian.local.Uiformio("hello")

A PyWebview window will open, showing the empty application as in the figure below.

Add components to the form

A component is created with a call to its constructor. Each contstructor takes one or two input arguments:

• a (unique) key
• and optionally a parent component or form.

Properties, such as label and defaultValue can be set on the created object. In this example we will add a TextField and a Button to the form. For more information, see the section about Form structure.

MATLAB

Append the guiInit function with code to add a text field and a button.

guiInit.m

function payload = guiInit(metaData)
    ...

    % Create a textfield.
    helloText               = component.TextField("helloKey", form);
    helloText.label         = "Enter first word";
    helloText.defaultValue  = "Hello";

    % Create a button.
    worldButton         = component.Button("buttonKey", form);
    worldButton.label   = "World!";
end

Start the application from the command line:

simian.local_v2_0_0.Uiformio("hello")

The form now looks as shown in the figure below.

Python

Append the gui_init function by with code to add a text field and a button.

hello.py

def gui_init(meta_data: dict) -> dict:
    ...

    # Create a textfield.
    hello_text = component.TextField("helloKey", form)
    hello_text.label = "Enter first word"
    hello_text.defaultValue = "Hello"

    # Create a button.
    world_button = component.Button("buttonKey", form)
    world_button.label = "World!"

    return payload

Start the application from the Python console:

import simian.local
simian.local.Uiformio("hello")

The form now looks as shown in the figure below.

Add an event

Buttons can emit events when clicked. These events are handled in the guiEvent function. In this example we will add an event to the previously created button, to print a message to the command line. For more information, see the chapter about Handling events.

MATLAB

Add the event to the button in guiInit with the setEvent method and the name of the event as input argument.

guiInit.m

function payload = guiInit(metadata)
    ...

    % Create a button that emits the "WorldButtonPushed" event.
    worldButton         = component.Button("buttonKey", form);
    worldButton.label   = "World!";
    worldButton.setEvent("WorldButtonPushed");
end

Add code to handle the event in guiEvent.

guiEvent.m

function payload = guiEvent(metaData, payload)
    import simian.gui_v2_0_0.*;

    % Process the events.
    Form.eventHandler("WorldButtonPushed", @sayHello);
    payload = utils.dispatchEvent(metaData, payload);
end

function payload = sayHello(metaData, payload)
    import simian.gui_v2_0_0.*;

    % Print the "<helloKey> world!" string to the console.
    fprintf(1, "%s world!\n", utils.getSubmissionData(payload, "helloKey"));
end

Start the application from the command line:

simian.local_v2_0_0.Uiformio("hello")

Click the button.

The message Hello world! is printed to the command window.

Python

Add the event to the button in gui_init with the setEvent method and the name of the event as input argument.

Add code to handle the event in gui_event.

def gui_init(meta_data: dict) -> dict:
    ...

    # Create a button that emits the "world_button_pushed" event.
    world_button = component.Button("buttonKey", form)
    world_button.label = "World!"
    world_button.setEvent("WorldButtonPushed")

    return payload


def gui_event(meta_data: dict, payload: dict) -> dict:
    # Process the events.
    Form.eventHandler(WorldButtonPushed=say_hello)
    callback = utils.getEventFunction(meta_data, payload)
    return callback(meta_data, payload)


def say_hello(meta_data: dict, payload: dict) -> dict:
    # Print the "<helloKey> world!" string to the console.
    print(utils.getSubmissionData(payload, "helloKey")[0] + " world!")
    return payload

Start the application from the Python console:

import simian.local
simian.local.Uiformio("hello")

Click the button.

The message Hello world! is printed to the console.

Overview

Basics of a form

An application is defined as a namespace containing several main functions with predefined names (starting with gui) and syntax. These are described in the table below. For MATLAB the namespace must be a package. For Python it must be a module. Simian GUI must be able to find the namespace on the path.

Simian GUI will try to execute the gui functions during initialization and when handling events. The form code can be in other files and functions, as long as the gui functions call these other functions in turn. When the functions are not found or cannot be executed for any other reason, the form will not function correctly.

gui functions

Running locally

The functions must be in a package (or module) to prevent shadowing these functions implemented for other potential applications created with Simian GUI. Once these functions have been created and the code and Simian are on the path, the form can be initialized locally by using:

simian.local_v2_0_0.Uiformio("my.namespace")

import simian.local
simian.local.Uiformio("my.namespace")

where "my.namespace" is the unique namespace of your form.

The following extra options can be specified:

• MATLAB:
  • Uiformio(_, "FigureHandle", figHandle) Specifies a custom parent figure.
  • Uiformio(_, "FigureProps", props) Specifies additional options (cell array) to use for the uihtml component.
  • Uiformio(_, "Fullscreen", fullscreen) Sets the figure full screen on start when true.
  • Uiformio(_, "Maximized", maximized) Maximizes the figure on start when true.
  • Uiformio(_, "Size", size) Sets the initial size [width, height] of the figure.
  • Uiformio(_, "WindowTitle", title) Specifies a title for the figure.
• Python:
  • Uiformio(_, debug=debug) Sets the application debug flag.
  • Uiformio(_, fullscreen=fullscreen) Sets the window full screen on start when true.
  • Uiformio(_, size=size) Sets the initial window size [width, height].
  • Uiformio(_, window_title=window_title) Specifies a title for the application window.

For deploying the form on a server please refer to the deployment chapter.

Form definition

The form definition is specified in the guiInit function that is called upon initialization of the form. It contains application-specific code for building the form and filling it with components. Simian GUI offers over 35 different components such as buttons, checkboxes, tables etc.

The documentation on name-value pairs shows them in UpperCamelCase: starting with an upper case character and starting every word with a capital letter. These name-value pairs are used in MATLAB. In Python, the name-value pairs are snake_cased: lower case with underscores separating the words. This means that if a name-value pair is documented as NestedForm, the input argument in Python becomes nested_form. Similarly, in the Python version of Simian GUI the guiXxx function names may be replaced by their snake case equivalents: gui_xxx.

Implementing guiInit

The guiInit function is called during initialization of the application and provides the form definition. In this section the calling syntax, arguments and return values will be discussed, followed by a small example.

Syntax

function payload = guiInit(metaData)
    ...
end

def gui_init(meta_data: dict) -> dict:
    ...
    return payload

Arguments

metaData:

Meta data describing the client session.

Struct/dict with fields:

• session_id: unique ID for the session, can be used to differentiate between multiple instances of the application
• namespace: package name of the application

In the guiInit function, form is defined by filling the form field of the payload. The payload is then sent to the front-end in order to present the form to the user.

payload:

Return value with the form definition.

Struct/dict with fields:

• form: a simian.gui.Form
• navbar (optional): struct/dict with fields:
  • logo (optional): image source reference (anything that can be put in HTML <img src="..." />
  • title (optional): HTML string
  • subtitle (optional): HTML string

See also

• For an example see Hello world!.

Form structure

The Hello world! example of the previous chapter follows the general structure of the form initialization code:

• Create an empty form: form = simian.gui.Form()
• Add components to it from top to bottom:
  • Create the component with default property values.
  • Change property values of the component where necessary.
• Return a struct/dict with a form field that contains the form.
  • Optionally specify a navbar field to set the logo and title of the application.

Components are created by using:

comp = component.<name>(<key>, <parent>)

In this call:

• name is the name of any class in component that is not the Component class. The Component is an abstract superclass of all implemented components, so it cannot be used directly. For a full list of available components, see Components and subsections.
• key is a unique string by which the component can be recognized. In MATLAB it must be a valid structure field name, which can be checked using isvarname(<key>) (Python does not have this restriction). In order to prevent unexpected behavior, it is advised to use globally unique component keys within the form.
• parent is an optional parent to which the new component must be added. You can add the new component directly to the form just like in the Hello world! example. Alternatively, you could add the component to a parent component such as a panel or table. More information on nesting of components can be found in Component nesting.

You can choose to import the component package to prevent having to use it for the creation of every single component. The syntax then becomes:

import simian.gui_v2_0_0.component.*
comp = <name>(<key>, <parent>);

from simian.gui.component import *
comp = <name>(<key>, <parent>)

There are over 35 different components that follow the same pattern. Each of these is described in the Components section and subsections.

Adding components from table

When each component is constructed individually, the code can quickly become very lengthy. In order to keep the overview, components can be specified in a MATLAB table or Pandas DataFrame (in Python) by using the utils.addComponentsFromTable function. It takes two input arguments:

• parent: a Form or Component that can have subcomponents (i.e. it has a components property),
• table: a MATLAB table or Pandas DataFrame.

It returns the created components in a struct/dict.

The table or DataFrame may have the following columns:

• key: Component key (mandatory). Must be a valid variable name and unique per level.
• type/class: Component type or class for creating the component (mandatory).
• level: Nesting level. Top level components (relative to parent) have level 1. Nested components, e.g. in a Panel, increment with 1. If the column is not present, all levels will be set to 1.
• options: Struct/dictionary with options, may contain any property that can be set to the component. Use missing/None to leave unspecified. If the column is not present, all options will be set to missing/None. Keys/fields 'defaultValue', 'label', 'tooltip', 'type', and 'key' are ignored, as these are columns of the table.
• defaultValue: The default value for the component, must be of a valid data type for the component type. Use missing/None to leave unspecified. If the column is not present, all default values will be set to missing/None.
• label: Label for the component. Use missing/None to leave unspecified. If the column is not present, all labels will be set to missing/None.
• tooltip: Tooltip for the component. Use missing/None to leave unspecified. If the column is not present, all tooltips will be set to missing/None.

Although in general only components can be added to the table, there are some other type/class values that can be added:

• column for adding the actual columns to a Columns component. In the options, a width field with an integer value must be specified. The total of the column widths must add up to 12.
• tab for adding the actual tabs to a Tabs component. The label will be shown on the tab.
• tablerow for adding rows to a Table component. Can only be added to a Table.
• tablecell for adding a TableCell to a tablerow. The TableCell can contain other components.

Validation, conditionals and logic can be added to the returned components as usual (see here), or they can be added via the options struct/dict that is put in the table.

The struct/dict that is returned uses the keys specified in the table definition as fields/keys. If keys in the table are not unique, then only the last component with the non-unique key will be in the output.

Example

This example shows a simple form built using a table/DataFrame. It consists of a panel that is added to the form and four components that are added to the panel, using the level column. The options struct/dict is used for multiple components, further reducing the amount of code required for building the form.

function payload = guiInit(metaData)
    form = Form();

    componentStruct = createLayout(form);

    fillColumn(componentStruct.left, "From");
    fillColumn(componentStruct.right, "To");

    payload.form = form;
end

function componentStruct = createLayout(form)
    columnOptions.width = 6;

    componentSpecs = {
        % key           class       level   options
        "locations",    "Columns",  1,      missing
        "left",         "Column",   2,      columnOptions
        "right",        "Column",   2,      columnOptions
        };

    componentTable = cell2table(componentSpecs, 'VariableNames', ["key", "class", "level", "options"]);

    componentStruct = utils.addComponentsFromTable(form, componentTable);
end

function fillColumn(column, label)
    key = lower(label);

    sharedOptions.labelPosition = "left-left";

    componentSpecs = {
        % key           class           level   options             defaultValue    label
        key + "Panel",  "Panel",        1,      missing,            missing,        label
        key,            "Container",    2,      missing,            missing,        missing
        "name",         "TextField",    3,      sharedOptions,      "Breda",        "Name"
        "latitude",     "Number",       3,      sharedOptions,      51.5883621,     "Latitude"
        "longitude",    "Number",       3,      sharedOptions,      4.7760251,      "Longitude"
        };

    componentTable = cell2table(componentSpecs, 'VariableNames', ["key", "class", "level", "options", "defaultValue", "label"]);

    utils.addComponentsFromTable(column, componentTable);
end

def gui_init(_meta_data: dict) -> dict:
    form = Form()

    component_dict = _create_layout(form)

    _fill_column(component_dict["left"], "From")
    _fill_column(component_dict["right"], "To")

    return {"form": form}


def _create_layout(form: Form) -> dict:
    column_options = {"width": 6}

    component_specs = [
        #   key             class       level   options
        [   "locations",    "Columns",  1,      None            ],
        [   "left",         "Column",   2,      column_options  ],
        [   "right",        "Column",   2,      column_options  ],
    ]

    component_table = DataFrame(
        data=component_specs,
        columns=["key", "class", "level", "options"],
        dtype=object,
    )

    return utils.addComponentsFromTable(form, component_table)


def _fill_column(column: component.Columns, label: str) -> None:
    key = label.lower()

    shared_options = {"labelPosition": "left-left"}

    component_specs = [
        #   key             class           level   options             defaultValue    label
        [   key + "Panel",  "Panel",        1,      None,               None,           label       ],
        [   key,            "Container",    2,      None,               None,           None        ],
        [   "name",         "TextField",    3,      shared_options,     "Breda",        "Name"      ],
        [   "latitude",     "Number",       3,      shared_options,     51.5883621,     "Latitude"  ],
        [   "longitude",    "Number",       3,      shared_options,     4.7760251,      "Longitude" ],
    ]

    component_table = DataFrame(
        data=component_specs,
        columns=["key", "class", "level", "options", "defaultValue", "label"],
        dtype=object,
    )

    utils.addComponentsFromTable(column, component_table)

Adding components from JSON

With the introduction of the Simian Form Builder, it is possible to generate components from a JSON form definition file by providing a named argument to the Form constructor.

form = Form(FromFile="/path/to/my/form.json");
form = Form(FromFile=mfilename("fullpath")); % The ".json" extension is added for convenience.

form = Form(from_file="/path/to/my/form.json")
form = Form(from_file=__file__)  # The extension is replaced with ".json" for convenience.

Additionally components that are able to hold other components, can be populated using the addFromJson method.

comp = component.Container("myContainer");
comp.addFromJson("/path/to/my/form.json");

comp = component.Container("myContainer")
comp.addFromJson("/path/to/my/form.json")

Initialization code

When components are generated using a JSON form, the component objects are added to the form tree. To modify a component programmatically without searching for it in the form, register a component initializer function.

In MATLAB and Python this can be done by calling the static method Form.componentInitializer before building the form. Note that the input arguments can be repeated to register multiple initializers.

function payload = guiInit(metaData)
    Form.componentInitializer('name', @initializeName);
    form = Form(FromFile='form.json');
    payload = struct("form", form);
end

function initializeName(comp)
    arguments
        comp component.TextField
    end

    comp.defaultValue = getenv('USERNAME');
end

def gui_init(meta_data: dict) -> dict:
    Form.componentInitializer(name=initialize_name)
    form = Form(from_file=__file__)
    return {"form": form}

def initialize_name(comp: component.TextField):
    comp.defaultValue = os.getlogin()

The Component class

The numerous different components all inherit properties and methods from the Component superclass. The following alphabetically ordered list of properties may be relevant for every component, regardless of their type:

The following methods are available for all components:

Available components

The components that can be added to your application have been divided into five categories. Each category contains an alphabetical list of all components including descriptions and examples.

• Basic: These can be used to collect basic user inputs such as text fields and checkboxes.
• Advanced: These components are for more advanced user inputs such as e-mail addresses or dates.
• Layout: Use these to define the layout of your application.
• Data: These can hold and/or present data, generally in tabular form.
• Miscellaneous: These components can be used to perform uploads, downloads or to nest forms.

Basic

The components in this section can be used to collect basic user inputs. Click the name of a component to move to a more detailed description.

The Button component

The Button component is a clickable button.

A button can be used to submit the form to the back-end or trigger other actions. To make a button trigger custom events in your form's guiEvent function, call the button's setEvent() method with a unique name for the new event. Note that the name of the event may not be a reserved Form.io event name, or you could get unintended behaviour or errors.

If the label is empty, the button becomes very thin. It is therefore advised to always have a non-empty label.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Button component has a label and tooltip property even though these are not explicitly listed here.

Properties

Methods

The Checkbox component

A checkbox is a box with a checked and unchecked state.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any Checkbox component has a label and defaultValue property even though these are not explicitly listed here.

Properties

See also

• Use the triggerHappy functionality to trigger an event whenever the value of the Checkbox component is changed by the user.
• Use a DataGrid component to create a table with a column of checkboxes.
• For a component with mutually exclusive options, use the Radio button.
• The Selectboxes component lets you create a group of checkboxes.

The Number component

Number components let the user enter a number. Several customizations are available.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any Number component has a label and defaultValue property even though these are not explicitly listed here.

Properties

The Number component does not support exponential notation. In order to specify numbers in scientific notation, use a TextField component with custom validation.

See also

• Use Validate to set things like min/max values for the Number component.

The Password component

Lets the user enter text that is obfuscated. As its name suggests, this is especially useful for entering passwords.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any Password component has a label and defaultValue property even though these are not explicitly listed here.

Properties

See also

• This components works the same as a TextField, but the entered characters are obfuscated.

The Radio component

Defines the specifics of a set of options of which exactly one must be selected.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Radio component has a label and defaultValue property even though these are not explicitly listed here.

Properties

Methods

By using the setValues method, the example Radio component above can be created using:

gender          = component.Radio("gender_radio", form);
gender.label    = "Gender";
gender.setValues(["Male", "Female", "Other", "Will not say"], ...
    ["m", "f", "o", "wns"])

gender = component.Radio("gender_radio", form)
gender.label = "Gender"
gender.setValues(["Male", "Female", "Other", "Will not say"],
    ["m", "f", "o", "wns"])

See also

• Use the triggerHappy functionality to trigger an event whenever the value of the Radio component is changed by the user.
• The Checkbox component allows for multiple selections at once.
• The Selectboxes lets you define a group of checkboxes in a similar fashion as the Radio component.
• The Survey component uses Radio buttons to ask several questions, each of them with the same set of possible answers.

The Select component

Use the Select component to let the user select an option from a dropdown list.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Select component has a label and defaultValue property even though these are not explicitly listed here.

Properties

Methods

The data property

The data property contains the values that are available in the Select component.

• When dataSrc is set to 'values', the data property must contain a struct/dict with key 'values', which must contain an array/list of structs/dicts with fields:

  • label: Text to display for the option.
  • value: Value of the option.

  The setValues method provides a simpler way to define the labels and values.

• When dataSrc is set to 'custom', the data property must contain a struct/dict with key 'custom', which may contain JavaScript code that fills a values variable with:

  • a list of objects. For instance:

    values = [
        {"label": "A", "value": "a"},
        {"label": "B", "value": "b"},
        {"label": "C", "value": "c"}
    ];
    

    The labels of the objects are shown in the Select component. The selected value depends on the Select component's valueProperty setting.

  • a list of labels. For instance:

    values = ["A", "B", "C"];
    

    This puts the letters A to C in the Select component and also uses the labels as values.

  • a reference to data of other components in the form. For instance:

    values = data.other_component_key;
    

    This allows for changing the selectable options "after initialization", as described in How to.

The widget property

The widget property can be used to switch between a Choices.js widget and a regular HTML 5 select widget. The visual difference between the two can be seen below, with on the left the Choices.js widget and on the right, the HTML 5 select widget. The Choices.js widget allows the user to search for an option, whereas the HTML 5 widget does not.

See also

• Use the triggerHappy functionality to trigger an event whenever the value of the Select component is changed by the user.
• Change the options of a Select component after initialization as described in How to.

The Selectboxes component

Define a group of checkboxes in the form. This is similar to the Radio component, but allows for multiple selections at the same time.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Selectboxes component has a label and defaultValue property even though these are not explicitly listed here.

Properties

Methods

The selectable options can be changed "after initialization" as well, as described in How to.

See also

• Use the triggerHappy functionality to trigger an event whenever the value of the Selectboxes component is changed by the user.
• Use the Radio to only allow for one selection.
• Change the options of a Selectboxes component after initialization as described in How to.

The TextArea component

Textareas are multi-line input fields allowing for long input text.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any TextArea component has a label and defaultValue property even though these are not explicitly listed here.

Properties

See also

• Use a TextField component to allow the user to enter text on a single line.

The TextField component

TextField components let the user enter text on a single line.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any TextField component has a label and defaultValue property even though these are not explicitly listed here.

Properties

See also

• Use a TextArea to allow for multiple lines of input text.

Advanced

The components in this section are for more advanced user inputs such as e-mail addresses or dates. Click the name of a component to move to a more detailed description.

The Currency component

This component lets the user enter a value in a specific currency.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any Currency component has a label and tooltip property even though these are not explicitly listed here.

Properties

The DateTime component

A DateTime component lets users specify a date and/or a time interactively.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any DataTime component has a label and tooltip property even though these are not explicitly listed here.

Properties

If you set the defaultValue property to specify the date selected by default, make sure to pass it in the right format (as specified in the format property). If you set both the defaultValue and defaultDate property, the defaultValue will be used as the default value. It is therefore advised to use the defaultValue instead of the defaultDate when not using Moment.js.

Testing

The defaultDate property does not work well with the Testing functionality because calling getSubmissionData on a DateTime component in a test-environment will return the defaultValue and not the defaultDate. Also, editing the value of a DateTime component with the testing functionality (using choose or type gestures) is not supported.

Methods

DatePickerConfiguration

The value of the datePicker property of a DateTime component shall be of type DatePickerConfiguration. It has the following properties:

For example, set the mininum date that can be selected by using:

dt                      = component.DateTime("dt", form);
dt.datePicker.minDate   = "2020-01-01";

dt = component.DateTime("dt", form)
dt.datePicker.minDate = "2020-01-01"

TimePickerConfiguration

The value of the timePicker property of a DateTime component shall be of type TimePickerConfiguration. It has the following properties:

For example, you can make the time show up in AM/PM instead of 24hr notation by using:

dt                          = component.DateTime("dt", form);
dt.timePicker.showMeridian  = true;

dt = component.DateTime("dt", form)
dt.timePicker.showMeridian = True

If the component does not expand when it is clicked, it probably means that a property of your DatePickerConfiguration or TimePickerConfiguration is incorrectly structured.

See also

• The Day component can be used to select a single day by individually choosing the day, month and year.

The Day component

The Day component can be used to select a single day by individually choosing the day, month and year.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any Day component has a label and tooltip property even though these are not explicitly listed here.

Properties

Methods

See also

• Interactive date and/or time selection can be done with a DateTime component.

The Email component

This component lets the user enter an e-mail address.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any Email component has a label and tooltip property even though these are not explicitly listed here.

Properties

The PhoneNumber component

This component lets the user enter a phone number.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any PhoneNumber component has a label and defaultValue property even though these are not explicitly listed here.

Properties

The Signature component

Users can draw a signature with this component.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any Radio component has a label and hidden property even though these are not explicitly listed here.

Properties

The Survey component

Asks multiple questions, all with the same options. Radio buttons are used to answer the questions.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Survey component has a label and defaultValue property even though these are not explicitly listed here.

Properties

Methods

The example survey displayed above (but without the answers entered) can be created using:

s       = component.Survey("my_survey", form);
s.label = "What is your opinion on:";
s.setQuestions(["Readability", "Support", "Performance", "Design"], ...
    ["read", "sup", "perf", "des"])
s.setAnswers(["Very poor", "Poor", "Neutral", "Good", "Excellent"], ...
    ["vp", "p", "n", "g", "e"])

s = component.Survey("my_survey", form)
s.label = "What is your opinion on:"
s.setQuestions(["Readability", "Support", "Performance", "Design"],
    ["read", "sup", "perf", "des"])
s.setAnswers(["Very poor", "Poor", "Neutral", "Good", "Excellent"],
    ["vp", "p", "n", "g", "e"])

The resulting value of the component after filling out the survey as in the image becomes:

{
   "read": "n",
   "sup": "e",
   "perf": "g",
   "des": "p"
}

See also

• Radio buttons are used to answer the questions.

The Tags component

The Tags component allows you to add a set of separate tags.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any Tags component has a label and defaultValue property even though these are not explicitly listed here.

Properties

The Time component

This component lets the user enter a time.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any Time component has a label and defaultValue property even though these are not explicitly listed here.

Properties

See also

• Use a DateTime component to enter a date and time.

The Url component

Url components let the user enter an url. Several customizations are available.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any Url component has a label and defaultValue property even though these are not explicitly listed here.

Properties

See also

• Use Validate to set things like min/max length for the Url component.

Layout

The components in this section can be used to define the layout of your application, for example to add headers or to split the application into multiple columns. Click the name of a component to move to a more detailed description.

The Columns component

Split the form into multiple columns with this component. The component has a number of columns, each of which can contain any number of components.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Columns component has a hidden property even though this is not explicitly listed here.

Properties

Methods

The example component with the two buttons and the textfield can be recreated as follows:

% Create three components without a parent.
btn1        = component.Button("button_1");
btn2        = component.Button("button_2");
btn1.label  = "First column";
btn1.block  = true; % Make the button fill the entire horizontal space of the parent.
btn2.label  = "Second column";
btn2.block  = true; % Make the button fill the entire horizontal space of the parent.
txt         = component.TextField("text");
txt.label   = "Enter text";

% Create two columns and add the components to them.
cols = component.Columns("two_columns", form);
cols.setContent({btn1, {btn2, txt}}, [2, 3]);

# Create three components without a parent.
btn1 = component.Button("button_1")
btn2 = component.Button("button_2")
btn1.label = 'First column'
btn1.block = True # Make the button fill the entire horizontal space of the parent.
btn2.label = 'Second column'
btn2.block = True # Make the button fill the entire horizontal space of the parent.
txt = component.TextField("text")
txt.label = 'Enter text'

# Create two columns and add the components to them.
cols = component.Columns("two_columns", form)
cols.setContent([[btn1], [btn2, txt]], [2, 3])

The Content component

This component can contain any HTML content. However, if you want to display an HTML table, it is strongly advised to use the HtmlTable functionality.

The Content component does not have a value and therefore it is not part of the submission data.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any Content component has a hidden property even though this is not explicitly listed here.

Properties

See also

• Custom HTML tables can be created and updated efficiently with the HtmlTable functionality.
• The HtmlElement is similar to the Content component in the sense that both display custom HTML.
• The Hidden component for an example on how to change the displayed content after initialization.

The FieldSet component

FieldSet components can be used to create a group of an area of the form and add a title to it. In this example, the fieldset has title Test settings and two components: a Checkbox and a DateTime.

In addition to the properties listed below, this component inherits properties and methods from the superclass Component. For example, any FieldSet component has a label and tooltip property even though these are not explicitly listed here.

Properties

The Html component

This component can display an HTML element in the form, for example a header, a table or an image.

Contrary to the HtmlElement component, the Html component has a value and therefore it is part of the submission data. The HTML to display can be set by assigning the defaultValue property during initialization and by using the setSubmissionData function after initialization (while processing events).

This component inherits properties and methods from the superclass Component. For example, any Html component has a hidden and defaultValue property even though these are not explicitly listed here.

Properties

See also

• The HtmlElement and Content components allow for setting the HTML content through a property instead of the submission data. However, these are more difficult to use than the Html component.
• The HtmlTable component subclasses this component.

The HtmlElement component

This component can display a single HTML element in the form, for example a header or an image.

The HtmlElement does not have a value and therefore it is not part of the submission data.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any HtmlElement component has a label and hidden property even though these are not explicitly listed here.

Properties

Methods

See also

• The 'Html' component allows for setting the HTML content through submission data.
• The Content component allows for more elaborate HTML content to be added to the form.
• The StatusIndicator uses an HtmlElement to display and update a status.
• The How to for a piece of example code.

The HtmlTable component

Create an HtmlTable component to efficiently display and update tables in your application. During events, you can set the highlighting of the elements of your tables in multiple ways. An example of a table as created by this component is shown below. The values of this component are not editable by the user.

This component inherits properties and methods from the superclasses Html and Component. For example, any HtmlTable component has a hidden property even though this is not explicitly listed here.

Properties

Initialization

Initializing an HtmlTable is done by calling the constructor with at least the key as the input:

Additional options can be given as name-value pairs:

You can set a default value for the table using:

obj.setDefaultValue(data, customization)

with data the data to display in the table and customization a struct/dict for specifying suffixes, custom styling etc.. Both are described in more detail below.

Updating

Update the data of your table in guiEvent using:

payload = setSubmissionData(payload, key, data);

setSubmissionData(payload, key, data)

where data can be a numeric, cell or string array in MATLAB. The table content can be customized by adding the Customization name-value pair, like so:

payload = setSubmissionData(payload, key, data, "Customization", customization);

setSubmissionData(payload, key, data, customization=customization)

customization must be a struct/dict that can have the following fields:

The HtmlTable component uses custom CSS (described in Advanced features) to customize the look of the tables to be displayed. As described above, the tableClass field can be used to specify a list of classes to be added to the <table> element. For example, by setting tableClass to "my-table" and specifying the following style in your custom CSS file, you can make all text in the table bold and blue:

.my-table {
    font-weight: bold;
    color: blue;
}

Using the same customization struct/dict, you can specify a default value for the table during initialization as follows:

obj = component.HtmlTable(key, ...);
obj.setDefaultValue(data, customization);

obj = component.HtmlTable(key, ...)
obj.setDefaultValue(data, customization)

Styling per cell

In addition to the fields described above, you can specify how each of the cells of the table can be styled. This can be done by using a combination of the Customization name-value pair and (custom) CSS styles. There are three styling modes that can be set using the stylingMode field of the Customization name-value pair. They add classes to the corresponding cells that can be used to apply styles to them that are readily available or that are defined in your custom CSS file(s).

The styling modes are described below.

redgreen

By choosing this mode, all cells with negative numbers get the text-danger class and all cells with positive numbers get the text-success class. These bootstrap classes color the text red and green, respectively. Only zeros get no class. For example:

customization.stylingMode = "redgreen";

This mode can only be used with numeric data.

thresholds

Define thresholds for varying the styling per cell. This can only be used in combination with numeric data. Specify a set of thresholds in the thresholds.values field and specify the classes to be added with these thresholds in the thresholds.classes field. The first class will be applied to values below and including the first threshold. Class n will be applied to values above threshold n-1 and below or equal to threshold n. The last class will be applied to all values above the last threshold. For this to work, the number of classes must equal the number of thresholds plus one. For example, the specification for adding the my-table-red class to all values below -1 and the my-table-green class to all values above 10 green, keeping everything in between black is as follows:

customization.stylingMode           = "thresholds";
customization.thresholds.values     = [-1, 10];
customization.thresholds.classes    = ["my-table-red", "", "my-table-green"];

customization["stylingMode"] = "thresholds"
customization["thresholds"]["values"] = [-1, 10]
customization["thresholds"]["classes"] = ["my-table-red", "", "my-table-green"]

Please note that in your custom CSS file, you have to define what happens to elements that have these classes (my-table-red and my-table-green).

custom

Choose the styling to apply to each of the elements of the table. Assign a string array the same size as the data that contains the classes to the cellClasses field of the customization struct/dict. For example if the data is two by two:

customization.stylingMode = "custom";
customization.cellClasses = ["text-danger", ""; "", "text-warning"];

customization["stylingMode"] = "custom"
customization["cellClasses"] = [["text-danger", ""], ["", "text-warning"]]

This adds classes to all non-empty strings. In this case, the classes added are:

[text-danger,   <none>
<none>,         text-warning]

Useful table CSS classes

Simian GUI comes with a Bootstrap CSS theme, that includes the following classes:

• table applies bootstrap table styling (this is the default value)
• table-dark creates a dark table with light text
• table-striped alternates between lighter and darker rows
• table-bordered draws a border around the table
• table-sm reduces the amount of padding in the table
• text-right aligns all text in the table to the right

For more information see Bootstrap Tables.

Some convenient additions to existing CSS classes can be made. For example

.table-sm {
    font-size: 0.75rem; /* smaller font size */
    width: auto; /* do not extend the table to full width */
}

can be used to further reduce the size of the table font and width. In order to make highlighted text stand out a bit more, the text can be made bold.

.table .text-danger {
    font-weight: bold; /* make red text in tables bold */
}

Text and background colors can be specified with:

• text-<theme> sets the text color
• bg-<theme> sets the background color

where <theme> can be primary, secondary, success, danger, warning, info, etc. See Bootstrap Colors for more information.

See also

• The HtmlElement component allows for setting the HTML content through a property instead of the submission data.
• The Content component allows for more elaborate HTML content to be added to the form.
• This component is a subclass of the Html component.

The Panel component

Panels can be used to wrap groups of components with a label and styling.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Panel component has a label and hidden property even though these are not explicitly listed here.

Properties

Methods

See also

• Component nesting
• Container and Well components can be used in a similar fashion.

The Table component

Position components in a table.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Table component has a label and hidden property even though these are not explicitly listed here.

Properties

Methods

See also

• For tables with more than a few rows, or with a variable number of editable rows, see the DataGrid or the EditGrid components.
• For more info on tables in general, see the Tables section.

The Tabs component

Tabs allow you to add different components to one of multiple tabs/pages in the form.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Tabs component has a hidden property even though this is not explicitly listed here.

Properties

Methods

Fill tabs using separate functions

You can call individual functions to fill a Tabs component using the fillTabs method. Its syntax is: obj.fillTabs(labels, fillFcns, inputs) This will add tabs to the Tabs component with the given labels and call each of the tab filling functions.

The input arguments are:

• labels: The label of each of the tabs. These must be unique.
• fillFcns: Handles of the functions that fill the tabs. They have syntax myFillFcn(tab, <additionalInputs>).
• inputs: Optional, additional inputs to each of the tab filling functions. Can be left out if none of the functions take any additional inputs.

The following example illustrates how this can be used in practice:

function payload = guiInit(metaData)
    form            = Form();
    payload.form    = form;
    labels          = ["Setup", "Analysis"];
    fillFcns        = {@fillSetupTab, @fillAnalysisTab};
    inputs          = {{"A", true}, {}};
    comp            = component.Tabs("myTabs", form);

    % This will add two tabs with the given labels. The tabs will be filled by calling the
    % local functions provided. These can be defined elsewhere as well.
    comp.fillTabs(labels, fillFcns, inputs)
end

function fillSetupTab(tab, key1, default)
    cb              = component.Checkbox(key1, tab);
    cb.defaultValue = default;
    cb.label        = "Ignore resistance";
end

function fillAnalysisTab(tab)
    txt         = component.TextField("txt", tab);
    txt.label   = "Name";
end

def gui_init(meta_data) -> dict:
    form = Form()
    labels = ["Setup", "Analysis"]
    fillFcns = [_fill_setup_tab, _fill_analysis_tab]
    inputs = [["A", True], []]
    comp = component.Tabs("myTabs", form)

    # This will add two tabs with the given labels. The tabs will be filled by calling
    # the local functions provided. These can be defined elsewhere as well.
    comp.fillTabs(labels, fillFcns, inputs)

    return {"form": form}


def _fill_setup_tab(tab, key, default):
    cb = component.Checkbox(key, tab)
    cb.defaultValue = default
    cb.label = "Ignore resistance"


def _fill_analysis_tab(tab):
    txt = component.TextField("txt", tab)
    txt.label = "Name"

The result is a Tabs component with two tabs, each filled with their own components:

The Well component

An area for containing components with a border and a gray background. No title or label is shown for this component.

In addition to the methods listed below, this component inherits properties and methods from the superclass Component. For example, any Well component has a label and hidden property even though these are not explicitly listed here.

Properties

Methods

See also

• Container and Panel components hold components in a similar fashion.

Data

These components can hold and/or present data, generally in tabular form. Click the name of a component to move to a more detailed description.

The Container component

A Container can hold multiple other components.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Container component has a label and tooltip property even though these are not explicitly listed here.

Properties

Methods

See also

• Component nesting
• Panel and Well components can be used in a similar fashion.

The DataGrid component

The DataGrid component is a table with a component in every column. Users can add, remove and edit rows. The DataGrid can also be filled by the back-end. Use the setContent method to automatically create the components for the DataGrid without filling them with data.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any DataGrid component has a label and tooltip property even though these are not explicitly listed here.

Properties

Methods

An example of how the setRowGroups method can be used is shown below:

colNames        = ["Person", "Hours", "Done"];
loggingTable    = component.DataGrid("logging", form);
loggingTable.setContent(colNames, lower(colNames), ["TextField", "Number", "Checkbox"]);

groupLabels     = ["Design phase", "Development phase", "Release phase"];
nRowsPerGroup   = [2, 3, 2];
rowNames        = ["Sketching", "Proposal", "Data retrieval", "Calculations", ...
    "Tests", "Documentation", "Deployment"];
loggingTable.setRowGroups(groupLabels, nRowsPerGroup, rowNames);

colNames = ["Person", "Hours", "Done"]
keys = [col.lower() for col in colNames]
loggingTable = component.DataGrid("logging", form)
loggingTable.setContent(colNames, keys, ["TextField", "Number", "Checkbox"])

groupLabels = ["Design phase", "Development phase", "Release phase"]
nRowsPerGroup = [2, 3, 2]
rowNames = ["Sketching", "Proposal", "Data retrieval", "Calculations", 
    "Tests", "Documentation", "Deployment"]
loggingTable.setRowGroups(groupLabels, nRowsPerGroup, rowNames)

The resulting DataGrid after initialization is as follows:

When using this method, the number of group labels must match the number of elements in nRowsPerGroup. If the rowNames input is used, the first component of the DataGrid must be a TextField and the number of row names must be equal to the sum of nRowsPerGroup.

Default value

You can set the initial value of the DataGrid (and EditGrid) by setting the defaultValue property of the component. In MATLAB, this can be a table with columns named after the keys of the components that you provided when calling setContent. Alternatively, it can be a struct array (MATLAB) or a list of dicts (Python), with fields equal to the keys of the DataGrid's components.

columnNames = ["Name", "Age", "Available"];
keys        = lower(columnNames);
users       = component.DataGrid("users", form);
users.setContent(columnNames, keys, ["TextField", "Number", "Checkbox"]);

% Two ways of setting the default value of the DataGrid.
users.defaultValue = struct(keys(1), {"Marie", "Hank"}, keys(2), {39, 43}, ...
    keys(3), {false, true});
users.defaultValue = table(["Marie"; "Hank"], [39; 43], [false; true], ...
    'VariableNames', keys);

columnNames = ["Name", "Age", "Available"]
keys        = [x.lower() for x in columnNames]
users       = component.DataGrid("users", form)
users.setContent(columnNames, keys, ["TextField", "Number", "Checkbox"])

users.defaultValue = [{
    keys[0]: "Marie",
    keys[1]: 39, 
    keys[2]: False}, {
    keys[0]: "Hank",
    keys[1]: 43, 
    keys[2]: True}
]

The default values of rows added by the user (if enabled) can be set by setting the defaultValue property of the relevant component:

users.disableAddingRemovingRows = false;
users.components{2}.defaultValue = 18;
users.components{3}.defaultValue = true;

users.disableAddingRemovingRows = False
users.components[1].defaultValue = 18
users.components[2].defaultValue = True

Initializing the DataGrid using the default values above and then adding one row yields:

See also

• The EditGrid component is very similar to the DataGrid, but has an expandable row in which elements can be edited.
• If your DataGrid has many rows, performance may be improved by using a DataTables component instead of a DataGrid. This also provides many additional features for displaying and editing table data.

The DataMap component

This component is similar to the DataGrid component. It creates a map by using two columns: key and value. Rows can be added, removed or edited by the user.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any DataMap component has a label and tooltip property even though these are not explicitly listed here.

Properties

See also

• DataGrid component.

The DataTables component

The DataTables component uses datatables.net to efficiently render an HTML table. It is a highly customizable component featuring support for pagination, searching, sorting and editing of its contents. Unlike the other tables in Simian GUI, the DataTables component does not contain any subcomponents. This implies that validation, conditionals, etc. for columns or cells works differently than with the native Form.io tables and grids.

This component inherits properties and methods from the superclass Component. For example, any DataTables component has a label and hidden property even though these are not explicitly listed here.

Properties

Methods

Basic use

The basic creation of a datatables component with all default settings is as follows:

% Create the component and set the label.
dt          = component.DataTables('dt', form);
dt.label    = 'Personnel';

% Specify the column titles and names.
dt.setColumns({'#', 'Name', 'Age', 'Present'}, {'id', 'name', 'age', 'present'});

% The value is an array of objects. The fields must match the column names.
% The first column with name 'id' is mandatory and must contain unique values.
dt.defaultValue = struct(...
    'id', {0, 1}, ...
    'name', {'Bob', 'Sarah'}, ...
    'age', {49, 47}, ...
    'present', {true, false});

# Create the component and set the label.
dt = component.DataTables('dt', form)
dt.label = 'Personnel'

# Specify the column titles and names.
dt.setColumns(['#', 'Name', 'Age', 'Present'], ['id', 'name', 'age', 'present'])

# The value is an array of objects. The fields must match the column names.
# The first column with name 'id' is mandatory and must contain unique values.
dt.defaultValue = [
    {'id': 0, 'name': 'Bob', 'age': 49, 'present': True},
    {'id': 1, 'name': 'Sarah', 'age': 47, 'present': False}
]

In order for DataTables to identify the individual rows, it is mandatory that the first column is named id and contains unique values. The column may be hidden if that is preferrable. Furthermore, the fields/keys entered in your default values must match the columns you have specified when calling the setColumns method. It is therefore highly recommended to call setColumns before setting the default value of the DataTables component.

Note: the value and options for the datatable must adhere to the DataTables API. Failing to do so may lead to incorrect rendering of the table or warning dialogs popping up.

Reading the data

After initialization, the current data of a DataTables component can be obtained by using the getSubmissionData utility function. In MATLAB, this returns a table. Python returns a pandas DataFrame. The syntax for both languages is the same:

data = utils.getSubmissionData(payload, "my_key");

New rows can be obtained using the static method getNewRows:

[payload, newRows] = component.DataTables.getNewRows(payload, key, ...
    "Parent", parentKey, "NestedForm", nestedFormKey);

payload, new_rows = component.DataTables.getNewRows(payload, key, 
    parent=parent_key, nested_form=nested_form_key)

For this method, new rows is defined as all rows added by the user since the last time this method was called (or since initialization if it is the first call). This means that if you call this method twice during a single guiEvent, the second call will not return any new rows.

The inputs to this method are the same as those for getSubmissionData. It outputs the payload and the new rows. In MATLAB, this returns a table. Python returns a pandas DataFrame. New rows obtained with this method will have a UUID in their id column. New rows that are not obtained using this method, but through using getSubmissionData, will have that UUID prefixed with new-.

Setting the data

After initialization, the data of a DataTables component can be set from the back-end by using the setSubmissionData utility function. In MATLAB, the data can have the following shapes:

• Cell/string/numeric/logical array with one element per cell in the DataTables component.
• Table with variable names equal to the keys of the columns.
• Struct with fields named after the keys of the columns.

In Python the data may be:

• A list of lists with the inner lists being the values per row.
• A list of dicts with a dict per row and the dict's keys named after the keys of the columns.
• A dict of lists with the dict's keys named after the keys of the columns. The lists are the columns' contents.
• A pandas DataFrame with columns named after the keys of the DataTable's columns.

The syntax is:

payload = utils.setSubmissionData(payload, "my_key", data);

utils.setSubmissionData(payload, "my_key", data)

Pagination

Without configuration, pagination is enabled. It allows the user to choose between 10 (default), 25, 50 or 100 entries per page.

Pagination can be disabled with dt.setFeatures(paging=False).

The dropdown menu to choose the page length can be disabled with dt.setFeatures(lengthChange=False).

The options in the dropdown menu can be customized with the lengthMenu option, for example:

dt.setOptions('lengthMenu', {{10, 25, 50, -1}, {10, 25, 50, "All"}});

dt.setOptions(lengthMenu=[[10, 25, 50, -1], [10, 25, 50, "All"]])

The default number of entries on a page can be specified with dt.setOptions(pageLength=25).

Searching

Without configuration, searching is enabled for all columns.

Searching can be disabled with dt.setFeatures(searching=False).

To only search in selected columns, use the searchable option of the colums:

dt.setColumns(...
    {'#', 'Name', 'Age', 'Present'}, ...
    {'id', 'name', 'age', 'present'}, ...
    'searchable', [false, true, true, false]);

dt.setColumns(
    ['#', 'Name', 'Age', 'Present'],
    ['id', 'name', 'age', 'present'],
    searchable=[False, True, True, False]
)

Other searching options can be specified with dt.setOptions(search=<string>, caseInsensitive=<boolean>, ...) and dt.setOptions(searchCols=[...]). The input given must follow the datatables.net reference.

Ordering

Without configuration, ordering is enabled for all columns.

Ordering can be disabled with dt.setFeatures(ordering=False).

To only enable ordering for selected columns, use the orderable option of the colums:

dt.setColumns(...
    {'#', 'Name', 'Age', 'Present'}, ...
    {'id', 'name', 'age', 'present'}, ...
    'orderable', [false, true, true, false]);

dt.setColumns(
    ['#', 'Name', 'Age', 'Present'],
    ['id', 'name', 'age', 'present'],
    orderable=[False, True, True, False]
)

A default sorting order can be specified with dt.setOptions(order=[[0, 'asc'], [1, 'desc']])

For other ordering options for the datatables or its columns please see the datatables.net reference.

Hidden columns

Columns can be hidden using the visible option of the columns. Note that hidden columns are still searchable but can be disabled as described here

dt.setColumns(...
    {'#', 'Name', 'Age', 'Present'}, ...
    {'id', 'name', 'age', 'present'}, ...
    'visible', [false, true, true, true]);

dt.setColumns(
    ['#', 'Name', 'Age', 'Present'],
    ['id', 'name', 'age', 'present'], 
    visible=[False, True, True, True]
)

Editing

DataTables has several methods of editing, that can be enabled or disabled with dt.setEditorMode(<bool>). As additional arguments can be specified:

• enableAddButton shows the New button, which opens a dialog to create a new row.
• enableEditButton shows the Edit button, which opens a dialog to edit the selected row(s). When the edit button is not enabled, inline editing is enabled.
• enableDelButton shows the Delete button, which deletes row(s) after confirmation.
• enableKeyNavigation, in combination with inline editing, allows the user to navigate the table using the arrow keys.
• cssSelectorForInlineMode allows the user to specify a CSS selector to determine which columns can be edited.

The default for boolean arguments is false. The cssSelectorForInlineMode allows editing all columns except id.

Inline editing

The default mode is inline editing. This mode is activated when the enableEditButton option is false or undefined. Without further configuration, all but the first column are editable. To confirm the new value, the user must press enter. All other actions, such as tabbing or stepping out of the field, cancel the change.

dt.setEditorMode(true, 'enableAddButton', true, 'enableDelButton', true);

dt.setEditorMode(True, enableAddButton=True, enableDelButton=True)

Modal editing

The alternative to inline editing is modal editing. This mode is activated when the enableEditButton option is true. Without further configuration, all but the first column are editable. To edit, select a row and click the edit button.

dt.setEditorMode(...
    true, ...
    'enableAddButton', true, ...
    'enableEditButton', true, ...
    'enableDelButton', true);

dt.setEditorMode(
    True,
    enableAddButton=True,
    enableEditButton=True,
    enableDelButton=True
)

Disable columns

Let's say that only the Age field may be edited by the user. To indicate the inaccessible columns, they get the muted-text CSS class.

dt.setColumns(...
    {'#', 'Name', 'Age', 'Present'}, ...
    {'id', 'name', 'age', 'present'}, ...
    'className', {'text-muted', 'text-muted', missing, 'text-muted'});

dt.setColumns(
    ['#', 'Name', 'Age', 'Present'],
    ['id', 'name', 'age', 'present'],
    className=['text-muted', 'text-muted', None, 'text-muted']
)

To disable inline editing this class is used to exclude the columns using a CSS selector. Note that this has no effect on the modal editing or creating new rows.

dt.setEditorMode(true, 'cssSelectorForInlineMode', ':not(.text-muted)');

dt.setEditorMode(True, cssSelectorForInlineMode=':not(.text-muted)')

To disable modal editing the editor fields need to be specified. This can be done using the setEditorFields method. The types of the noneditable fields are set to readonly or hidden.

dt.setEditorFields("type", ["hidden", "readonly", missing(), "hidden"])

dt.setEditorFields(type=["hidden", "readonly", "", "hidden"])

Custom rendering and editing

Sometimes, columns have a datatype that only takes a limited number of values, such as an enumeration or boolean. In these cases a text field is not the most user friendly way to let the user specify a value. DataTables supports various kinds of input fields, in this example the select box is shown.

The Present field in the example is a boolean. Without customization it would be a text field containing "true" or "false" as text value.

To show the value as "Yes" or "No" instead, a custom renderer can be used. This requires adding a custom Javascript function as described in Use custom Javascript. The getBooleanRenderer function returns an inner function that can be used by DataTables' columns.render. The inner function can access variables in the parent scope, in this case used for t and f.

function getBooleanRenderer(t, f) {
    return function (data, type, row) {
        if (type === 'display') {
            return data ? t : f;
        }
    
        return data;
    };
}

To tell the table to use the custom renderer for the Present column, the render option is set on the last column.

dt.setColumns(...
    {'#', 'Name', 'Age', 'Present'}, {'id', 'name', 'age', 'present'}, ...
    'render', struct(...
    'function', {missing, missing, missing, 'getBooleanRenderer'}, ...
    'arguments', {missing, missing, missing, {'Yes', 'No'}}));

dt.setColumns(
    ['#', 'Name', 'Age', 'Present'], ['id', 'name', 'age', 'present'], 
    render=[
        None,
        None,
        None, {
            'function': 'getBooleanRenderer',
            'arguments': ['Yes', 'No']
        }
    ]
)

In order to edit the value using a select box, the editor fields need to be manually specified. This works for both editor modes. The boolean field is set to 'type': 'select' and options are specified to configure it (see DataTables' select)

dt.setEditorFields("type", ["hidden", "text", "text", "select"], ...
    "options", {[], [], [], struct("Yes", true, "No", false)});

dt.setEditorFields(type=["hidden", "text", "text", "select"], 
    options=[{}, {}, {}, {"Yes": True, "No": False}])

Large tables

For tables that contain a large amount of data, it is recommended to only render one page at a time, using the deferRender feature.

dt.setFeatures('deferRender', true);

dt.setFeatures(deferRender=True)

Other options

DataTables have many options and we cannot support all of them. However, we allow a large subset to be specified. Note: error checking and validation for the various options ranges from non-existent to incomplete. Incorrect settings may cause rendering issues, Javascript errors or popup alerts. Use on your own responsibility.

The tables in the following sections show a mapping of the options that can be set using the provided functions. The section name refers to the function that can be used to specify the options. This function name in turn refers to a section in the datatables reference or datatables editor reference.

The left column is the name of the name-value argument to specify in the function. The right column is the name of the corresponding option(s) in the datatables options.

setFeatures

setCallbacks

setOptions

setColumns

setEditorFields

setInternationalisation

setSelect

setEditorInternationalisation

The EditGrid component

The EditGrid component is a table like component with an adjustable number of rows. Each row contains the same set of components that are children of the EditGrid component. The components can be layout components containing other components, making the EditGrid more flexible than a DataGrid.

The tableView property of components specifies whether their (simplified) values are to be shown in the 'saved'/collapsed state of the EditGrid rows. The labels of these components are used as column headers of the EditGrid.

The values of the components cannot be edited immediately. Each row contains an 'Edit' button, which brings the row in an 'edit'/expanded mode, showing all components in the row and allowing the values to be changed. The changed values are not part of the submission data until the row is 'saved'. If there is communication with the back-end before the row was saved, the changes to the values in the EditGrid may be lost.

Rows can be added or removed by the user or from the back-end. A new row created by the user is not available in the submission data until it is 'saved'.

The submission data of an EditGrid is a struct array / list of dicts where each item in the array/list contains the values of a row in the EditGrid. The structs / dicts contain the values of the components in the rows. The getSubmissionData and setSubmissionData utilities work for an entire EditGrid and expect/return an array/list with the values of the rows. In the back-end the values per row can be processed in a for loop that runs over the array/list that was returned by getSubmissionData. When sending values back into the front-end, the complete array/list of EditGrid values must be put in the setSubmissionData utility function.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any EditGrid component has a label and tooltip property even though these are not explicitly listed here.

Properties

Methods

Example

The example EditGrid shown above can be recreated with the following MATLAB and Python code.

% Create the Locations list.
locationGrid = component.EditGrid("location_grid", form);
locationGrid.label = "Location availability";

inputLocation = component.Number("input_location", locationGrid);
inputLocation.label = "Location";

inputAvailable = component.Checkbox("input_available", locationGrid);
inputAvailable.label = "Available";

# Create the Locations list.
location_grid = component.EditGrid("location_grid", form)
location_grid.label = "Location availability"

input_location = component.Number("input_location", location_grid)
input_location.label = "Location"

input_available = component.Checkbox("input_available", location_grid)
input_available.label = "Available"

See also

• The DataGrid component is similar to the EditGrid, but the component values are edited directly in the row, without expanding it first. Setting the default value of an EditGrid works the same as setting it for a DataGrid.
• If your EditGrid has many rows, performance may be improved by using a DataTables component instead of an EditGrid. This also provides many additional features for displaying and editing table data.

The Hidden component

Hidden components can contain data that is included in the submission data, but is not visible to the user. Hidden values can be used as data that has no meaning to the user and should not be changed, but may be required for the computational code, for instance unique identifiers of a set of data.

A special use case of hidden values is to set component properties that would otherwise not be part of the submission data.

This component inherits properties and methods from the superclass Component. For example, any Hidden component has a defaultValue property even though this is not explicitly listed here.

Properties

Example

A good example of a value that is not part of the submission data, is the html field of the Content component. Since it is not a value, it cannot be updated after initiliazation of the form. However, it is possible to reference the value of another component. In this example we will use a Hidden component to adjust the displayed text after initialization. A very similar approach can be used for the HtmlElement component. Please note that the Html component can have its HTML content changed directly, without the need for a Hidden component.

function payload = guiInit(~)   
    form = Form();

    header = component.Content("header", form);
    header.html = "<h1 class=""display-1"">{{data.headerContent}}</h1>";
    header.refreshOnChange = true;

    headerContent = component.Hidden("headerContent", form);
    headerContent.defaultValue = "Hello, world!";

    headerButton = component.Button("headerButton", form);
    headerButton.label = "Say Hi!";
    headerButton.setEvent("SetHeader");

    payload.form = form;
end

function payload = guiEvent(~, payload)    
    if payload.action == "event"
        if payload.event == "SetHeader"
            payload = utils.setSubmissionData(payload, "headerContent", "Hi, world!");
        end
    end
end

def gui_init(_meta_data: dict) -> dict:
    form = Form()

    header = component.Content("header", form)
    header.html = '<h1 class="display-1">{{data.headerContent}}</h1>'
    header.refreshOnChange = True

    header_content = component.Hidden("headerContent", form)
    header_content.defaultValue = "Hello, world!"

    header_button = component.Button("headerButton", form)
    header_button.label = "Say Hi!"
    header_button.setEvent("SetHeader")

    payload = {"form": form}

    return payload


def gui_event(_meta_data: dict, payload: dict) -> dict:
    if payload["action"] == "event":
        if payload["event"] == "SetHeader":
            utils.setSubmissionData(payload, "headerContent", "Hi, world!")

    return payload

Miscellaneous

The miscellaneous components can be used to perform uploads, downloads or to nest forms. Click the name of a component to move to a more detailed description.

The File component

The File component can be used to upload files. In comparison to the guiUpload functionality, there are several differences.

• The File component does not block the user interface during upload. It also does not trigger an event in the back-end.
• For deployed applications, the file is uploaded to the webserver instead of being part of the submission data. This makes the File component suitable for uploading larger files.

There are two modes of operation:

• base64: In base64 mode, the selected files are base64 encoded and put in the submission data. This is the default mode for local applications.
• portal: In portal mode, the selected files are uploaded to the portal webserver. Download URLs are provided in the submission data. This is the default mode for deployed applications.

Note: the File component also offers upload capabilities for a number of cloud storage services. These are not facilitated yet.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any File component has a label and tooltip property even though these are not explicitly listed here.

Properties

Methods

See also

• ResultFile for downloading files.

The Form component

Use the Form component to create a form within your form (nested forms). Nested forms are more elaborately described in Nested forms. Forms can be included by reference.

The Plotly component

Visualize data with the Plotly component. The Plotly implementations for the MATLAB and Python versions of Simian GUI differ significantly, so they are documented in separate subsections below. It is possible to combine multiple types of plots in the same figure, which is demonstrated with an example.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any Plotly component has a label and hidden property even though these are not explicitly listed here.

MATLAB

The Plotly component creates a Plotly figure in which data can be visualized.

Properties

utils.Plotly

The utils.Plotly class provides methods that resemble MATLAB plotting functions with which data can be presented in several chart types. When the Plotly utils class object is put in the payload and returned to the form, the created plot is shown in the form. Since the data to plot is often calculated based on certain inputs, the Plotly utils class object is often added in the guiEvent function, as illustrated by the example below the properties and methods described next.

utils.Plotly properties

utils.Plotly methods

Usage

Below is an example illustrating the MATLAB plotly functionality. You can call multiple plotting functions on the same Plotly object to plot multiple things in the same figure. The resulting plot is shown below the code.

function payload = guiInit(metaData)
    form            = Form();
    payload.form    = form;
    component.Plotly("my_plot", form);

    % When this button is clicked, the data is plotted.
    btn         = component.Button("plot_data", form);
    btn.label   = "Plot data";
    btn.setEvent("PlotData");
end

function payload = guiEvent(metaData, payload)
    plotObj = utils.getSubmissionData(payload, "my_plot");
    plotObj.clf();

    % Add a line plot and a bar chart in the same figure.
    nPoints = 4;
    plotObj.bar(1:nPoints, rand(nPoints, 2));
    plotObj.plot(1:nPoints, rand(nPoints, 1), "LineWidth", 3);

    % Add peripherals such as labels etc.
    plotObj.title("Recent efficiency compared to average efficiency");
    plotObj.xlabel("N");
    plotObj.ylabel("Efficiency [-]");
    plotObj.legend("This year", "Last year", "Average last ten years");

    payload = utils.setSubmissionData(payload, "my_plot", plotObj);
end

The same plot can also be achieved during initialization by calling the methods above on the object in the defaultValue property of the Plotly component object:

function payload = guiInit(metaData)
    form            = Form();
    payload.form    = form;

    % Add a Plotly component and add a line plot and a bar chart in the same figure.
    comp    = component.Plotly("plot", form);
    nPoints = 4;
    comp.defaultValue.bar(1:nPoints, rand(nPoints, 2));
    comp.defaultValue.plot(1:nPoints, rand(nPoints, 1), "LineWidth", 3);

    % Add peripherals such as labels etc.
    comp.defaultValue.title("Recent efficiency compared to average efficiency");
    comp.defaultValue.xlabel("N");
    comp.defaultValue.ylabel("Efficiency [-]");
    comp.defaultValue.legend("This year", "Last year", "Average last ten years");

    % When this button is clicked, the data is plotted.
    btn         = component.Button("plot_data", form);
    btn.label   = "Plot data";
    btn.setEvent("PlotData");
end

In addition to the chart types available through the methods of the Plotly class, you can use all functionality from the Python Plotly library if you set the submission data such that it can be interpreted as a Plotly component correctly. For example, you can change the font-size of the ticks on the x-axis using plotObj.layout.xaxis.tickfont.size = 10;.

Python

The Plotly functionality in the Python version of Simian GUI differs significantly from the MATLAB implementation as the Plotly library is directly available from Python, which can be used to visualize data in the form. Most functionality from the Python Plotly API can be used (animations and controls are not supported) when a Plotly Figure object is put in the Plotly object's figure property.

The Plotly component creates a Plotly figure in which data can be visualized.

Properties

utils.Plotly

This utility class should be used in guiEvent, not in guiInit. The utils.getSubmissionData function returns a utils.Plotly object containing the payload data for the Plotly component. When the Plotly utils class object is put in the payload and returned to the form, the created plot is shown in the form.

utils.Plotly properties

utils.Plotly methods

Usage

Below is an example illustrating the Python plotly functionality with an initial bar plot that is extended with an extra line when the guiEvent function is executed. Note that in Python the Plotly Express functions are available to allow for easier creation and modification of plotly figures.

import plotly.express as px
import plotly.graph_objects as go


def gui_init(meta_data):
    app_form = Form()
    plot_obj = component.Plotly("plot", app_form)
    plot_obj.figure = go.Figure(
        go.Bar(
            x=[1, 2, 3, 4, 5],
            y=[0.81, 0.58, 0.25, 0.45, 0.41],
            name="This year",
        )
    )
    plot_obj.figure.update_layout(
        title="This year's efficiency compared to the average efficiency",
        xaxis_title="N",
        yaxis_title="Efficiency [-]",
        autosize=False,
        width=600,
        height=400,
    )

    # When this button is clicked, the data is plotted.
    btn = component.Button("plot_data", app_form)
    btn.label = "Plot data"
    btn.setEvent("PlotData")

    return {"form": app_form}


def gui_event(meta_data, payload):
    plot_obj, _ = utils.getSubmissionData(payload, "plot")
    plot_obj.figure.add_scatter(
        x=[1, 2, 3, 4, 5],
        y=[0.35, 0.95, 0.32, 0.54, 0.23],
        name="Average last<br>ten years",
    )

    # Update the payload with the new values in the Plotly object.
    payload, _ = utils.setSubmissionData(payload, "plot", plot_obj)

    return payload

The form generated with the above code will look like this:

Resizing

Please note that the Plotly component spans the entire width of its parent component, even if the plot itself is smaller. This means that if you set layout.width and layout.height, the plot itself becomes smaller but the containing component does not, resulting in subsequent components ending up way below the plot. In order to mitigate this, you can reduce the width of the component by placing it in a Columns component, like so:

function payload = guiInit(metaData)
    form            = Form();
    payload.form    = form;
    
    % Add the Plotly component to the first column of a Columns component.
    plotObj = component.Plotly("my_plot");
    cols    = component.Columns("plot_cols", form);
    cols.setContent({plotObj, {}}, [4, 8])    

    % When this button is clicked, the data is plotted.
    btn         = component.Button("plot_data", form);
    btn.label   = "Plot data";
    btn.setEvent("PlotData");
end

The ResultFile component

The ResultFile component is the counterpart of the File component, that allows the user to download result files created by the back-end. In comparison to the guiDownload functionality, there are several differences.

• The ResultFile component is able to show multiple download links in a list, instead of being just a download button.
• The ResultFile component does not block the user interface during the download. It also does not trigger an event in the back-end.
• For deployed applications, the file is downloaded via the portal webserver instead of being part of the submission data. This makes the ResultFile component suitable for downloading larger files.

There are two modes of operation:

• base64: In base64 mode, the selected files are base64 encoded and put in the submission data. This is the default mode for local applications.
• portal: In portal mode, the selected files are uploaded to the portal webserver. Download URLs are provided in the submission data. This is the default mode for deployed applications.

In addition to the properties and methods listed below, this component inherits properties and methods from the superclass Component. For example, any ResultFile component has a label and tooltip property even though these are not explicitly listed here.

Properties

Methods

Upload method

The input of the static upload method are:

• filePaths: Array/list of paths to files to upload
• mimeTypes: Array/list of MIME-types corresponding to the files to upload
• metaData: Metadata struct/dict
• payload: The payload struct/dict
• key: Key of the ResultFile component
• Parent/NestedForm: Optional inputs for further specifying what ResultFile component is used to upload the files
• FileNames: Optional input for specifying an array/list of file names to display in the component³
• Append: Optional input to control whether previously uploaded files remain listed. Per default the list is cleared before the new file is uploaded.

Example

In the guiEvent code snippets below a simple struct/dict is written to a .json file in the session folder of the back-end and made available in the front-end.

% Write a struct to a .json file in the back-end's session folder.
sessionFolder   = utils.getSessionFolder(metaData, "Create", true);
niceName        = "example_table.json";

fileName = fullfile( ...
    sessionFolder, ...
    sprintf("example_table-%s.json", matlab.lang.internal.uuid()));

fid = fopen(fileName, 'w');
fprintf(fid, '%s', jsonencode(struct("hello", "world")));
fclose(fid);

% Upload the created .json file to make it available in the front-end.
payload = component.ResultFile.upload( ...
    fileName, ...
    "application/json", ...
    metaData, ...
    payload, ...
    "result_file_key", ...
    'FileNames', niceName);

# Write a dict to a .json file in the back-end's session folder.
session_folder = utils.getSessionFolder(meta_data, create=True)
nice_name = "example_table.json"
file_name = os.path.join(session_folder, f"example_table-{uuid.uuid4()}.json")

with open(file_name, 'wt') as f:
    json.dump({"hello": "world"}, f)

# Upload the created .json file to make it available in the front-end.
component.ResultFile.upload(
    file_paths=[file_name],
    mime_types=["application/json"],
    meta_data=meta_data,
    payload=payload,
    key="result_file_key"
    fileNames=[nice_name]
)

See also

• File for uploading files.

Component nesting

As described in Form structure, when creating a component, you can pass an optional parent as an input after the component's key. This can be used to add the component directly to the form or to another component as long as the parent component is suitable. In Components and subsections, you can find which components can contain other components. These components have a components property as a means to refer to their children and an addComponent method. Some components can have child components that are not added to the component directly. These components do not have a components property. For example, the Columns component has a columns property. Child components are added to a single column instead of to the Columns component.

There is no parent property because components and forms only know about potential child components, not about their own parent.

When the parent of the component to create is left out, the component will not be part of the form until it is added to another component or the form itself. This can be done using the addComponent method of the parent component. The following example illustrates how two textfields are created and after that, added to a Panel component.

% Create two textfields without adding them to the form or another component yet.
name        = component.TextField("nameField");
color       = component.TextField("colorField");
name.label  = "Name";
color.label = "Favourite color";

% Create a panel in the form and add the textfields to it.
panel       = component.Panel("myPanel", form);
panel.label = "Personal info";
panel.addComponent(name, color);

# Create two textfields without adding them to the form or another component yet.
name = component.TextField('name_field')
color = component.TextField('color_field')
name.label = 'Name'
color.label = 'Favourite color'

# Create a panel in the form and add the textfields to it.
panel = component.Panel('my_panel', form)
panel.label = 'Personal info'
panel.addComponent(name, color)

The resulting form is as follows:

In this example, it would also have been possible to create the panel first, then create the textfields and provide the parent panel as an input directly:

% Create a panel in the form.
panel       = component.Panel("myPanel", form);
panel.label = "Personal info";

% Create two textfields and add them to the panel.
name        = component.TextField("nameField", panel);
color       = component.TextField("colorField", panel);
name.label  = "Name";
color.label = "Favourite color";

# Create a panel in the form.
panel = component.Panel('my_panel', form)
panel.label = 'Personal info'

# Create two textfields and add them to the panel.
name = component.TextField('name_field', panel)
color = component.TextField('color_field', panel)
name.label = 'Name'
color.label = 'Favourite color'

Component properties

There are several properties of the Component class that may contain objects of specific classes. Each of these classes are described in the sub-sections of this section.

On this page some functionality that is shared between these classes is described.

Custom JavaScript

For more complex applications it is possible to add custom JavaScript code that is executed in the front-end. This can reduce the need for communicating with the back-end. Custom JavaScript code can be used in the following places:

1. Component properties:

   • calculateValue

     The JavaScript code must assign a value to variable value.

   • customConditional

     The JavaScript code must assign a boolean to variable show. Example

   component_object.calculateValue    = "value = data.other_component + 1;"
   component_object.customConditional = "show = data.other_component > 0;"
   

2. Logic.action

   When the type field of the action struct/dict is set to 'value' or 'customAction', the JavaScript code in the action's 'value' or 'customAction' field must assign a value to variable value. Example

3. Logic.trigger

   When the type field of the trigger struct/dict is set to 'javascript', the JavaScript code in the trigger's 'javascript' field must assign a boolean to variable result. Example

4. Validate custom property

   The JavaScript code must assign a boolean to variable valid.

In the JavaScript code the variables listed in the table below are available for use. The usage numbers denote which variables are available for the places specified in the above list. current component refers to the component to which the custom JavaScript applies.

Execution of custom JavaScript depends on the JavaScript support provided by the browser the application is opened in. When the browser does not support JavaScript features that are used, errors and warnings may be printed in the browser's console. The application should continue to function, but functionality may differ from the expected functionality.

Validate

Add a Validate object to a component to define custom validation for it. When the validation fails, the form cannot be submitted and an indication is given on why validation failed and where.

Properties

Example

The following example shows a form with a TextField that has a validation on the maximum number of words in the input.

The initialization code is as follows:

tf          = component.TextField("LastName", form);
tf.label    = "Last name";

tfVal               = componentProperties.Validate(tf);
tfVal.maxWords      = 1;
tfVal.customMessage = "Last name shall be one word.";

btn         = component.Button("SubmitButton", form);
btn.action  = "submit";
btn.label   = "Submit";

tf = component.TextField('tf', form)
tf.label = 'Last name'

validate = component_properties.Validate(tf)
validate.maxWords = 1
validate.customMessage = 'Last name shall be one word.'

btn = component.Button('btn', form)
btn.action = 'submit'
btn.label = 'Submit'

Conditional

Add a Conditional to a component to define when the component should be shown or hidden based on data or properties of the form. With the properties of this class, an equation like show when "NameTextField" equals "Bart" can determine whether or not the component is shown.

Properties

It is also possible to specify a customConditional which evaluates a Javascript expression to determine whether the component should be shown. When conditional and customConditional are both specified, the latter has precedence.

Example

The following example shows a form whose Number component is only shown when a checkbox is checked.

The initialization code is as follows:

% Create a Checkbox.
cb          = component.Checkbox("CalibrateCb", form);
cb.label    = "Calibrate";

% Create a Number and add a Conditional for toggling its visibility.
nr          = component.Number("CalibrationNr", form);
nr.label    = "Calibration value";
nrCond      = componentProperties.Conditional(nr);
nrCond.show = true;
nrCond.when = "CalibrateCb";
nrCond.eq   = true;

# Create a Checkbox.
cb = component.Checkbox('calibration_cb', form)
cb.label = 'Calibrate'

# Create a Number and add a Conditional for toggling its visibility.
nr = component.Number('calibration_number', form)
nr.label = 'Calibration value'
nr_cond = component_properties.Conditional(nr)
nr_cond.show = True
nr_cond.when = 'calibration_cb'
nr_cond.eq = True

Logic

Adding Logic to a component allows for changing the component definition in reaction to data entered in a form. For two examples, see this page. The createLogic and createDisableLogic functions in the componentProperties package/module makes it easier to create Logic objects.

Properties

Trigger property

The trigger's 'type' field may have the values 'simple', 'javascript' or 'event'. The createTrigger function in the componentProperties package/module simplifies creating a trigger.

simple

When the trigger type is 'simple', the trigger struct/dict must contain a field 'simple'. It must contain a struct/dict with fields:

• 'show': must contain a boolean,
• 'when': must contain the full key of another component and
• 'eq': must contain a value that is compared against the value of the component specified in 'when'

The component that contains the Logic object is shown true/false when the other component's value equals the specified value.

javascript

When the trigger type is 'javascript', the trigger struct/dict must contain a field 'javascript'. It must contain JavaScript code that assigns a boolean to a variable 'result'. This is described in more detail in section Custom JavaScript.

event

When the trigger type is 'event', the trigger struct/dict must contain a field 'event'. It must contain the name of an event that is triggered in the form.

Actions property

The actions property must contain a cell array / list containing one or more action structs/dicts. The action's 'type' field may have the values 'property', 'value' or 'customAction'. To create a disable action the createDisableAction function in the componentProperties package/module can be used.

property

When the action type is 'property', the action struct/dict must contain a field 'property'. It must contain a struct/dict with fields:

• 'value': the property to change
• 'type': the data type of the property

The action struct must also contain a field 'state' containing the value the specified property must get when the trigger of the Logic object is triggered.

value

When the action type is 'value', the action struct/dict must contain a field 'value'. It must contain JavaScript code that assigns a value to a variable 'value'. This is described in more detail in section Custom JavaScript.

customAction

When the action type is 'customAction', the action struct/dict must contain a field 'customAction'. It must contain JavaScript code that assigns a value to a variable 'value'. This is described in more detail in section Custom JavaScript.

Utility functions

The componentProperties package/module contains some utility functions to make it easier to add Logic to your components.

Create Trigger

The createTrigger function can be used to define when Logic must be applied. It accepts a triggerType and triggerValue input. The trigger type and value must be one of the following combinations:

The following trigger types and values trigger Logic when the component with key "key" has the given value. Note that data.key does not work in case of intermediate data components.

Create disable action

The createDisableAction function creates a component disable action definition that can be used in a Logic object. When you use the function with disableTarget input set to false, the created action is an enable action.

Create Logic

The createLogic function creates a Logic object with the specified trigger type and value, and optional actions and component to add it to. The trigger is created by the createTrigger function, so the input options documented there also apply here.

Create disable Logic

The createDisableLogic function creates a Logic object with disable action with the given trigger type and value. The trigger is created by the createTrigger function, so the input options documented there also apply here. When a target component is specified, the Logic object is added to that component. When the function is used with the disableTarget input set to false, the created action is an enable action.

Note that adding disable Logic to a disabled component (and the other way around) does nothing. This function will show a warning on this.

Json

This class is used to specify JSON strings that when transformed into JSON, remain JSON strings. Consider the following MATLAB example where a string is transformed both directly, and as part of a Json object:

str = '{"test":100, "space":"station"}';
obj = componentProperties.Json(str);

>> disp(jsonencode(str))
    "{\"test\":100, \"space\":\"station\"}"
>> disp(jsonencode(obj))
    {"test":100, "space":"station"}

This class is (among others) useful for the Hidden component and for defining custom component Validation.

Error

This class allows customizable errors to be displayed for each component when an error occurs. It has the following properties:

• required
• min
• max
• minLength
• maxLength
• invalid_email
• invalid_date
• pattern
• custom

The values of these properties are the messages you wish to display once an error of that type occurs. Within the message, you can use {{ field }} to include the component's label. The following example shows a custom error message shown when a required component was left empty:

The initialization code is as follows:

txt         = component.TextField("name_field", form);
txt.label   = "Name";
txt.setRequired();

customError             = componentProperties.Error(txt);
customError.required    = "Field {{ field }} is required. Please try again.";

btn         = component.Button("submit", form);
btn.label   = "Submit";
btn.setEvent("TestEvent")

txt = component.TextField("name_field", form)
txt.label = "Name"
txt.setRequired()

customError = componentProperties.Error(txt)
customError.required = "Field {{ field }} is required. Please try again."

btn = component.Button("submit", form)
btn.label = "Submit"
btn.setEvent("TestEvent")

Composed components

Simian GUI includes components that are composed of multiple other components.

If you want to use a set of components in a similar fashion throughout your application, consider creating your own composed component in order to prevent code duplication.

StatusIndicator

Create a StatusIndicator component to create an HtmlElement component that indicates a status that can be updated on the back-end. The status indicator can look as follows:

Initialization

The initialization is done by calling the constructor with at least two inputs:

Additional options can be given as name-value pairs:

The StatusIndicator component creates an HtmlElement for displaying the status. The object of the HtmlElement can be found in the displayComponent property. Further customization such as adding a customConditional to it, can be performed using that property: obj.displayComponent.customConditional = "show = data.nr > 5".

Updating

Update the status in your guiEvent code using:

payload = composedComponent.StatusIndicator.update(...
    payload, key, status, nestedFormKey, "Parent", parentKey);

where key is the key provided when creating the StatusIndicator, status is one of the items of statuses.value and nestedFormKey is an optional nested parent form. Use the Parent name-value pair to further specify which status indicator must be selected.

Example

% Initialize using defaults:
testStatus = composedComponent.StatusIndicator("testStatus", form);

% Initialize using options:
testStatus = composedComponent.StatusIndicator(...
    "testStatus", form, ...
    "Content", "Tests", ...
    "DefaultValue", "notRun", ...
    "Statuses", struct(...
    "value", {'notRun', 'running', 'success', 'failed'}, ...
    "theme", {'secondary', 'warning', 'success', 'danger'}));
    
% Update the status:
payload = composedComponent.StatusIndicator.update(payload, "testStatus", "failed");

# Initialize using defaults:
testStatus = composed_component.StatusIndicator("testStatus", form)
        
# Initialize using options:
testStatus = composed_component.StatusIndicator(
    "testStatus", form,
    content="Tests",
    defaultValue="notRun",
    statuses=[{
        "value": "notRun",
        "theme": "secondary"
    }, {
        "value": "running",
        "theme": "warning"
    }, {
        "value": "success",
        "theme": "success"
    }, {
        "value": "failed",
        "theme": "danger"
    }]
)

# Update the status:
composed_component.StatusIndicator.update(payload, "testStatus", "failed")

Navbar

The navigation bar is shown at the top of the screen. It contains the close button on the right and can be configured to show a configurable logo and title text on the left. The navbar can be specified as follows:

payload.navbar.logo     = utils.encodeImage("myCustomLogo.jpg");
payload.navbar.title    = "Example title";
payload.navbar.subtitle = "<small>v1.0</small>";

payload["navbar"] = {
    "logo": utils.encodeImage("myCustomLogo.jpg"),
    "title": "Example title",
    "subtitle": "<small>v1.0</small>"
}

Show changes

A warning message can be displayed in the navbar, whenever the form has changes. To enable this feature, specify the showChanged field in the payload. This feature can be turned on and off during initialisation or events.

The change indication is triggered by the form's pristine flag, which is lowered each time the user changes a value. Reverting a changed value to the previous value does not raise the pristine flag again. It is possible to change the pristine flag value during initialisation or events.

payload.showChanged = true;
payload.pristine    = true;

payload["showChanged"] = True
payload["pristine"] = True

Simian Form Builder (beta)

The Simian Form Builder can be used to build Simian web apps in a graphical environment, reducing the need to write code.

Simian web apps created with the builder can be used without having the builder installed. They do need Simian GUI to be installed to work.

Currently the Simian Form Builder is only available for Python.

Installation

To install the builder, make sure you have simian-gui and simian-local installed and running with a valid license. Then, in the same environment, run:

pip install --extra-index-url https://pypiserver.monkeyproofsolutions.nl/simple/ simian-builder

Getting started

Open the Simian Form Builder window

python -m simian.builder

The Builder opens and shows the default form.

Specify the Workspace folder and Module name.

Click the Create module button.

This generates:

1. A form definition file (.json).
2. A Python module that loads the form definition file. The module can be run as a script to open the app locally.
3. A css folder containing the modules style sheet.

Drag and drop components to build a form.

Edit component settings to change behavior and appearance.

Click the Save JSON button to save the updated form.

Noteworthy settings

• On the API tab the field Property Name contains the component key. It is automatically generated based on the label, but can be changed here.

• The settings of the Component classes are equivalent to the settings that can be set in the builder.

Nested application

Add a container to the form.

Open a new Builder window and create a new module.

Add some component(s).

Run the preview of the main module.

Handling events

When the user interacts with the user interface (e.g.: clicks on a button, or changes a value), the back-end application is notified via an event that carries data about the origin of the event and the status of the user interface. Whenever an event occurs, the guiEvent function is called on the server. By implementing this function, user-defined functionality can be provided to the application.

Implementing guiEvent

The guiEvent function serves as a gateway for all events. Therefore, a typical implementation will consist of switching logic that dispatches the events to other functions that actually provide functionality to handle the events. In this section the calling syntax, arguments and return values will be discussed, followed by a small example.

Syntax

function payload = guiEvent(metaData, payload)
    ...
end

def gui_event(meta_data: dict, payload: dict) -> dict:
    ...
    return payload

Arguments

metaData:

Meta data describing the client session. It is a struct/dict with fields:

• session_id: unique ID for the session, can be used to differentiate between multiple instances of the application
• namespace: package name of the application

payload:

When entering the function, this contains the event data containing all values as provided by the client. It is a struct/dict with fields:

• action: 'event'
• download: information regarding the download of a file. Empty when no file is being downloaded.
• event: name of the event that was triggered.
• followUp (optional): name of a follow-up event that will be triggered after the current one has completed.
• formMap: Map representing the form definition.
• key: identifier of the component that triggered the event
• submission: struct/dict with fields:
  • data: struct/dict with fields:
    • eventCounter: incrementing counter; do not change.
    • <key>: multiple fields containing the values of the components identified by the keys.
    • <nested form key>: See Nested forms for more information. Struct/dict with fields:
      • data: struct/dict with fields:
        • <key>: multiple fields containing the values of the components identified by the keys.
• updateForm: when true, the form definition is sent to the front end. The default value is false. Use this only when the form definition changes. Updating the form definition will be slower than only updating the submission data.
• alerts (optional): array of struct/dict with fields:
  • type: message type, see Alerts
  • message: string

In the guiEvent function, the submission field may be altered before sending payload back to the front-end in order to present results to the user. Additionally, the followUp field can be changed, which is described below.

Key & Event

The key is unique for each component within the context of its parent and/or nested form, but event can be shared between components. This can be useful when multiple components (partially) share functionality. See Example.

Dispatching events

As the number of possible events in your application grows, your guiEvent function may contain an enormous switch/case or if/elif construction. In order to mitigate this, it is possible to automatically call functions based on event names without having to specify every single event. This can be achieved by using the dispatchEvent or getEventFunction utility functions:

payload = utils.dispatchEvent(metaData, payload);

caller = utils.getEventFunction(meta_data, payload)
payload = caller(meta_data, payload)

The dispatchEvent function calls a function equal to the name of the event that was triggered, whereas getEventFunction only returns the function object.

Note: In Python, breakpoints cannot be detected in functions executed via the dispatchEvent function. It is therefore recommended to use getEventFunction instead.

The functionality of the dispatching mechanism is illustrated with the example below. Consider the initialization code of a form with several buttons, each with their own event:

btn1 = component.Button("btn1", parent);
btn1.setEvent("ModelS.getResults");

btn2 = component.Button("btn2", parent);
btn2.setEvent("writeToDatabase");

btn3 = component.Button("btn3", parent);
btn3.setEvent("ModelX.getValue");

The following guiEvent functions handle these events, the first one using conditional logic and the second one using the dispatchEvent or getEventFunction functions:

function payload = guiEvent(metaData, payload)
    switch payload.event
        case "ModelS.getResults"
            payload = ModelS.getResults(metaData, payload);

        case "writeToDatabase"
            payload = writeToDatabase(metaData, payload);

        case "ModelX.getValue"
            payload = ModelX.getValue(metaData, payload);
    end
end

function payload = guiEvent(metaData, payload)
    % Use the automatic dispatch.
    payload = utils.dispatchEvent(metaData, payload);
end

def gui_event(meta_data, payload):
    if payload["event"] == "ModelS.getResults":
        ModelS.getResults(meta_data, payload)
    elif payload["event"] == "writeToDatabase":
        writeToDatabase(meta_data, payload)
    elif payload["event"] == "ModelX.getValue":
        ModelX.getValue(meta_data, payload)

def gui_event(meta_data, payload):
    # Use the automatic dispatch.
    caller = utils.getEventFunction(meta_data, payload)
    payload = caller(meta_data, payload)

Registering events explicitly

Sometimes it is undesirable to name an event after a function or vice versa. For this purpose, event handler functions can be registered explicitly.

In MATLAB and Python this can be achieved by calling the static method Form.eventHandler in the guiEvent function before event dispatching. Note that the eventHandler input arguments can be repeated to register multiple events.

function payload = guiEvent(metaData, payload)
    Form.eventHandler("SayHello", @sayHello);
    payload = utils.dispatchEvent(metaData, payload);
end

function payload = sayHello(metaData, payload)
    payload = utils.setSubmissionData(payload, "display", "Hello, world!");
end

def gui_event(meta_data: dict, payload: dict) -> dict:
    Form.eventHandler(SayHello=say_hello)
    callback = utils.getEventFunction(meta_data, payload)
    return callback(meta_data, payload)

def say_hello(meta_data: dict, payload: dict) -> dict:
    utils.setSubmissionData(payload, "display", "Hello, world!")
    return payload

Follow-up Event

When the followUp field is added to payload, and its value is the name of another event, the follow-up event will be triggered after completion of the current one. The component key will be identical for both events. The most common use case of this feature is to present the user with intermediate results of a calculation that consists of multiple stages. Consider combining this with the StatusIndicator component.

An example of the follow-up event is given below:

function payload = guiInit(metaData)
    form            = Form();
    payload.form    = form;

    btnLoadData         = component.Button("run", form);
    btnLoadData.label   = "Run";
    btnLoadData.setEvent("Run");

    txtId       = component.TextField("id", form);
    txtId.label = "ID";
end

function payload = guiEvent(metaData, payload)
    switch payload.event
        case "Run"
            pause(1);
            payload = utils.setSubmissionData(payload, "id", "Running phase 1");
            payload.followUp = "RunNext";

        case "RunNext"
            pause(1);
            payload = utils.setSubmissionData(payload, "id", "Finalizing...");
            payload.followUp = "RunFinal";

        case "RunFinal"
            pause(2);
            payload = utils.setSubmissionData(payload, "id", "Done!");
    end
end

import time


def gui_init(meta_data: dict) -> dict:
    form = Form()
    payload = {"form": form}

    btnLoadData = component.Button("run", form)
    btnLoadData.label = "Run"
    btnLoadData.setEvent("Run")

    txtId = component.TextField("id", form)
    txtId.label = "ID"

    return payload


def gui_event(meta_data: dict, payload: dict) -> dict:
    if payload["event"] == "Run":
        time.sleep(1)
        utils.setSubmissionData(payload, "id", "Running phase 1")
        payload["followUp"] = "RunNext"
    elif payload["event"] == "RunNext":
        time.sleep(1)
        utils.setSubmissionData(payload, "id", "Finalizing...")
        payload["followUp"] = "RunFinal"
    elif payload["event"] == "RunFinal":
        time.sleep(2)
        utils.setSubmissionData(payload, "id", "Done!")

    return payload

Example

The following example shows an implementation of guiEvent that uses the event names and component keys to dispatch the event to the correct function.

function payload = guiEvent(metaData, payload)
    % Switch on event name.
    switch payload.event
        case "calculate"
            % The calculate event has an application-specific preprocessing step.
            % Preprocess the data entered in the form before performing calculations.
            preprocessed_data = preprocess(payload);
            
            % Switch on the component key.
            % Each component starts a different calculation.
            switch payload.key
                case "stage1StartButton"
                    payload = runStage1(payload, preprocessed_data);
                    
                case "stage2StartButton"
                    payload = runStage2(payload, preprocessed_data);
            end
            
        case "estimate"
            payload = estimate(payload);
    end
end

def gui_event(meta_data, payload):
    # Switch on event name.
    if payload['event'] == 'calculate':
        # The calculate event has an application-specific preprocessing step.
        # Preprocess the data entered in the form before performing calculations.
        preprocessed_data = preprocess(payload)

        # Switch on the component key. Each component starts a different calculation.
        if payload['key'] == 'stage1StartButton':
            runStage1(payload, preprocessed_data)

        elif payload['key'] == 'stage2StartButton':
            runStage2(payload, preprocessed_data)

    elif payload['event'] == 'estimate':
        estimate(payload)
        
    return payload

Submission data

Typically, the handling of an event will consist of three steps:

1. Get input data provided by the user.
2. Perform calculations.
3. Send a result back to the user.

In Simian GUI, data is communicated via submission data. In particular when working with nested forms, the submission data can have a deeply nested structure, which makes it cumbersome to work with directly. Therefore, Simian GUI provides some utility functions to address this issue. It is therefore advised to refrain from getting and setting the submission data in your payload directly, and to stick to using these functions:

getSubmissionData: Obtains submission data from the payload using the component key. You can use this to, for example, get the text entered in a specific textfield. Note that for some components the submission data values are (or can be) automatically converted to a more user-friendly format.

setSubmissionData: Sets submission data using the component key. If there is already submission data present for the component, it will be replaced. Use this, for example, to set the text of a specific textfield or to fill a datagrid. This function may apply changes to the input data to make sure it is understood by the front-end. The changed input data is the second output of the function. For example, setting the submission data of a DataGrid component allows for entering the data as a numeric array/list. However, this is transformed into a struct array/list of dicts before being placed in the submission data.

These functions should not be used during initialization (guiInit), but are there for event handling.

The components for which the data type is (or can be) automatically converted in the getSubmissionData and setSubmissionData functions and the corresponding data types are:

with:

• 'x / y': MATLAB / Python data types. When there is a difference.
• '-': no conversion.
• '(opt.)": optional conversion output type.
• 'table-like': table, struct array, 2D-matrix / DataFrame, list of dicts, dict with lists, list of lists

Syntax

[data, isFound] = utils.getSubmissionData(...
    payload, key, "NestedForm", nestedForm, "Parent", parent);
[payload, newData] = utils.setSubmissionData(...
    payload, key, data, "NestedForm", nestedForm, "Parent", parent);

data, is_found = utils.getSubmissionData(payload, key, nested_form, parent)
payload, new_data = utils.setSubmissionData(payload, key, data, nested_form, parent)

Arguments

• payload: the payload contains the submission data
• key: the component key for which the value will be retrieved
• data: the value of the specified component. When using setSubmissionData in Python ensure that the values are JSON serializable with the json module. This may require converting values to another data type before using it in setSubmissionData.
• isFound: boolean value indicating whether the submission data has been found
• optional NestedForm: when working with nested forms, the key of the form can be specified. This input can be omitted if the component is not in a nested form or if the combination of key and Parent is unique within the application.
• optional Parent: key of the parent component. Use this for components in Containers, DataGrids, Panels, etc. Some additional notes about this input argument:
  • This must be the key of an actual component. For example, if you want to get or set the submission data for a component that is in a tab of a Tabs component, this input shall be the key of the Tabs component and there is no need to specify which tab the component is in. Similarly, for a component in a Columns component, you can provide the key of the Columns component and do not have to specify which column the component is in. This is different from the form initialization code, where a single tab or column can be provided as the parent when adding a component to it.
  • If a component is directly in a nested form, do not input the nested form's key as the parent. Instead, use the NestedForm input for this.
  • This input can be omitted if the component does not have a parent component or if the combination of key and NestedForm is unique within the application.

As described above, if there are multiple components with the same key, you can use the NestedForm and Parent inputs to refine the selection. When the component is directly in the form, do not specify a Parent or NestedForm input.

When zero or more than one components match the key(s) in the inputs, the getSubmissionData function will return a [] / None as data, and false for isFound. When exactly one component matches the key(s) in the inputs, the value of the component is returned and isFound contains true. setSubmissionData errors when not exactly one component is matched.

Please note that in Python, the payload dict returned by the setSubmissionData function is the same object as the input payload.

Example

The three steps described at the top of this page are illustrated with an example below.

function payload = estimate(payload)   
    % Collect input data provided by the user.
    inputValue = utils.getSubmissionData(payload, "my_input_field");
    
    % Do the calculations.
    outputValue = doSomething(inputValue);
    
    % Send the result back to the user.
    payload = utils.setSubmissionData(payload, "my_output_field", outputValue);
end

def estimate(payload: dict) -> dict:
    # Collect input data provided by the user.
    input_value, _ = utils.getSubmissionData(payload, 'my_input_field')

    # Do the calculations.
    output_value = doSomething(input_value)

    # Send the result back to the user.
    return utils.setSubmissionData(payload, 'my_output_field', output_value)[0]

Caching State

Commonly, a webserver is stateless: after a request has been completed, no data is retained on the server. This is also the case for the Matlab Production Server and calls to Python via WSGI. Therefore, the calls to guiEvent are also stateless.

If it is necessary or desirable to retain the state of the application server-side, Simian GUI provides a caching mechanism that can be used to store and retrieve data for a session.

• setCache: Cache data under a given name to be retrieved later.
• getCache: Get cached data for a given name.

Syntax

utils.setCache(metaData, name, data)
[data, isFound] = utils.getCache(metaData, name);

utils.setCache(meta_data, name, data)
data, is_found = utils.getCache(meta_data, name)

Arguments

• metaData: the session_id from the meta data is used to support multiple sessions
• name: the name of the cache entry
• data: data to store in the cache
• isFound: boolean value indicating whether the cache entry was found

Local session

When running an application in Matlab locally, the cache persistently stores the data in the workspace of the Matlab session. When running an application in Python locally, the cached information is stored in a dictionary object in the Python session.

Matlab Production Server

When deploying an application to the Matlab Production Server the cache data is stored in Redis, an open source (BSD licensed), in-memory data structure store, used as a database, cache and message broker.

The default Matlab Production Server Redis cache is configured to not evict any data from memory and the maximum amount of memory is not limited. After a restart of the Redis cache, all cached data is lost.

The maximum size of a value stored in Redis is limited to 512 MiB. Depending on the data type, the required amount of memory for storing the value in cache may be larger or smaller compared to the variable in the Matlab workspace.

Please refer to the Redis documentation and MPS documentation for more information about the Redis cache on the Matlab Production Server.

Python - Redis

For applications run from a server (or even locally) it is possible to store the cached data on a Redis server. To enable Redis caching add a cache key to the meta_data dict containing a dict with key enabled set to True, a key type set to "redis", and an options dict with key-value pairs being the named inputs of the redis.Redis class constructor of redis-py.

Error Handling

When an uncaught error occurs during the execution of guiEvent, Simian GUI automatically shows an alert message to the user. The user gets the option to reload or close the app. In local MATLAB mode, the error message including stack trace can be found in the command window.

It is recommended to prevent errors from happening as much as possible. When there are situations where errors may occur, it is recommended to catch the error and handle it appropriately.

Alerts

To indicate success or failure of a calculation, dismissable alerts can be displayed above the form.

The alerts can be defined by specifying payload.alerts. The value must be a cell array of structs (MATLAB) or a list of dictionaries (Python) with fields type and message, where type can be danger, warning, success, info, primary, secondary, dark or light. The utils.addAlert function can be used to add alerts to the payload.

Example

payload = utils.addAlert(...
    payload, ...
    "An error occurred in the application back-end.", ...
    "danger");

payload = utils.addAlert(
    payload,
    "An error occurred in the application back-end.",
    "danger",
)

guiUpload

The guiUpload function can be used to upload content to the form. It is triggered instead of guiEvent when a button is clicked that had the setUpload method called on it during form initialization. Before the function is called, the user will have had the opportunity to select the file to upload. Upon arrival in the function, the payload will have a field upload that has the following fields:

• contentType: The content type specified with the setUpload method.
• fileContents: Base64 encoded version of the file's contents.
• fileName: The name of the file including extension.
• filePath: The full path of the file including extension.

Similar to the guiEvent function, you can choose what happens depending on the event that is triggered.

Alternatively, the File component can be used to upload files.

Syntax

The syntax of the guiUpload function is similar to that of guiEvent as shown in the example below. It shows the initialization code of a button setup for uploading an Excel file. The guiUpload function reads the contents of the file and calls a plotting function to plot the data in the form. The definition of the plotting component is not shown in the initialization code.

function payload = guiInit(metaData)
    form        = Form();
    btn         = component.Button("stage_1_upload", form);
    btn.label   = "Upload analysis - stage 1";
    btn.setEvent("UploadAnalysis")
    btn.setUpload(".json")
    payload.form = form;
end    

function payload = guiUpload(metaData, payload)
    switch payload.event
        case "UploadAnalysis"
            data    = jsondecode(fileread(payload.upload.filePath));
            payload = plotStage1(payload, data);
        otherwise
            % Handle other upload actions.
    end
end

def gui_init(meta_data: dict) -> dict:
    form = Form()
    btn = component.Button("stage_1_upload", form)
    btn.label = "Upload analysis - stage 1"
    btn.setEvent("UploadAnalysis")
    btn.setUpload(".json")
    return {"form": form}

def gui_upload(meta_data: dict, payload: dict) -> dict:
    if payload["event"] == "UploadAnalysis":
        with open(payload["upload"]["filePath"], "r") as file:
            data = json.load(file)

        plot_stage_1(payload, data)
    else:
        # Handle other upload actions.
        pass

    return payload

guiDownload

The guiDownload function is used to download data from the application to the location selected by the user. Downloading data is quite straightforward in local mode, but because the same code should also work in deployed mode, some extra steps need to be taken. The workflow is as follows:

1. The user clicks a button that triggers event downloadStart. In guiInit, you can call myButton.setEvent("downloadStart") to set this event for a specific button.
2. Application-specific function guiDownload is triggered. This function should define the file name and the data to return in the payload. This is described below.
3. Simian GUI creates a file from the data specified by guiDownload.
4. The user selects the location to save the file.

The guiDownload function should assign the download field of the payload. The download field is a struct/dict with the following fields:

• fileContents: Base64 encoded version of the data to download. In Matlab, you can use the matlab.net.base64encode function to Base64-encode a bytestream representing the data you want to encode.
• fileName: The name of the file to download. This includes an extension but excludes a path.
• fileContentType: The content type. For example '*.zip'.

Multiple files can be downloaded at once using a zip-file. The following example illustrates how this could be achieved with guiDownload:

function payload = guiDownload(metaData, payload)
    % Save the data to multiple files.
    sessionFolder   = utils.getSessionFolder(metaData, "Create", true);
    csvFile         = fullfile(sessionFolder, "Measurements.csv");
    coeffFile       = fullfile(sessionFolder, "Coefficients.txt");
    writetable(myTable, csvFile)
    writematrix(myCoefficients, coeffFile)

    % Create a zip file.
    zipFileName     = "Results.zip";
    zipFileNameFull = fullfile(sessionFolder, zipFileName);
    zip(zipFileNameFull, [csvFile, coeffFile]);

    % Base64-encode the zip file.
    fid             = fopen(zipFileNameFull, "r");
    fileContents    = fread(fid, "uint8=>uint8");
    fclose(fid);

    payload.download.fileContents       = matlab.net.base64encode(fileContents);
    payload.download.fileContentType    = "*.zip";
    payload.download.fileName           = zipFileName;
end

import base64
import os.path
from pandas import DataFrame
import shutil
import tempfile

def gui_download(meta_data: dict, payload: dict) -> dict:
    """Download Example."""
    # Create a dummy table for the example.
    ones_table = DataFrame(
        [[1] * 4] * 3, columns=['A', 'B', 'C', 'D'], index=["Row 1", "Row 2", "Row 3"])

    # Create a temporary folder and create a csv and json file with the DataFrame in it.
    session_folder = utils.getSessionFolder(meta_data, create=True)
    temp_folder = tempfile.TemporaryDirectory(dir=session_folder)
    ones_table.to_csv(os.path.join(temp_folder.name, 'ones_table.csv'))
    ones_table.to_json(os.path.join(temp_folder.name, 'ones_table.json'))

    # Create a new temp folder to create the zip file in. (If you reuse the previous temp
    # folder, the zip file would contain a stub version of itself.)
    temp_zip_file = os.path.join(tempfile.TemporaryDirectory(dir=session_folder).name, 'Results')

    with open(shutil.make_archive(temp_zip_file, "zip", temp_folder.name), 'rb') as file:
        # Open the zip file as a binary file, read its contents and base64 encode it.
        encoded = base64.b64encode(file.read())
        payload = {
            'download': {
                'fileContents': encoded.decode("utf-8"),
                'fileContentType': 'application/zip',
                'fileName': "Results.zip"
            }
        }

    return payload

The code above uses utility function getSessionFolder. Its syntax is:

sessionFolder = utils.getSessionFolder(metaData, "Create", true);

session_folder = utils.getSessionFolder(meta_data, create=True)

The first input is the metadata. Optionally, specify whether to create the session folder if it does not exist yet.

When there are multiple different download options, each with their own button, they all have to trigger a downloadStart event. You can differentiate between them by looking at payload.key, which is the key of the button that was pushed.

Note: The session folder will be removed when the session is ended using the Close button. For files in other locations, it is the responsiblity of the developer to ensure they are cleaned up appropriately, for instance using guiClose.

Nested forms

Nested forms are forms within forms. Simian GUI supports nesting forms and provides utilities to manage forms that are nested one level deep. By toggling the visibility of the nested forms, the user interface can be separated into multiple pages. When using nested forms to group components, the submission data follows the same nesting structure (see Submission data).

Form and Form

Simian GUI has two Form classes:

1. Form: This is the application form, the top level of the user interface.
2. component.Form: This is a nested form, which is used as a component in the application form.

Although they both refer to the same type of form eventually, the properties and data associated with both classes are different.

Initialization

A nested form can be added to the application form in guiInit in a similar fashion as any other component.

nestedForm = component.Form(nestedFormKey, formObj)

However, the recommended method to add nested forms is addNestedForms:

formObj.addNestedForms(formKeys, createFcns, inputs, targetComponent)

where

• formObj is the application Form object.
• formKeys is an array/list of strings that are used as keys for the nested forms.
• createFcns is an array of function handles (MATLAB) or a list of Callables (Python). Each of the functions is called to fill the corresponding nested form. The functions must accept their nested form object as first input argument, and the corresponding (optional) inputs. In the function components can be added to the nested form object.
• inputs is a cell array (MATLAB) or a list of inputs (Python) to be used in the createFcns. This allows you to use the same createFcn more than once, but with different parameters.
• targetComponent is the component to add the nested forms to. This input is optional and when no component is specified, the nested forms are added to the application Form.

The first nested form will be visible on initialization, while the others are hidden. The benefits of using this method are:

• Manages switching behaviour (showing one nested form and hiding the others).
• Less boilerplate code.

Note that you can only use the addNestedForms method once per application.

An example of how it can be used is given below.

formDefs = {
    % Key                       Create function                     Inputs
    "mainForm"                  @guiLibrary.createMain              {}
    "inputForm"                 @guiLibrary.createInputPhase        {}
    "swapExemptionForm"         @guiLibrary.createSwapExclusion     {}
    "createPhaseAsset"          @guiLibrary.createCreatePhase       {"Asset"}
    "createPhaseLiability"      @guiLibrary.createCreatePhase       {"Liability"}
    "testPhaseAsset"            @guiLibrary.createTestPhase         {"Asset"}
    "testPhaseLiability"        @guiLibrary.createTestPhase         {"Liability"}
    };

appForm.addNestedForms([formDefs{:, 1}], formDefs(:, 2), formDefs(:, 3));

form_defs = [ 
    # Key                       Create function                     Inputs
    ["mainForm",                guiLibrary.createMain,              []],
    ["inputForm",               guiLibrary.createInputPhase,        []],
    ["swapExemptionForm",       guiLibrary.createSwapExclusion,     []],
    ["createPhaseAsset",        guiLibrary.createCreatePhase,       ["Asset"]],
    ["createPhaseLiability",    guiLibrary.createCreatePhase,       ["Liability"]],
    ["testPhaseAsset",          guiLibrary.createTestPhase,         ["Asset"]],
    ["testPhaseLiability",      guiLibrary.createTestPhase,         ["Liability"]],
    ]
    
appForm.addNestedForms(*zip(*form_defs))

This creates seven nested forms, the first of which will be visible after initializing the application.

Switching Forms

For forms that have been added to the application using addNestedForms it is possible to switch between the forms using switchForms in guiEvent. After event handling has completed, the selected form (identified by its key) will be displayed. Other nested forms will be hidden.

payload = utils.switchForms(payload, "inputForm");

utils.switchForms(payload, "inputForm")

The key of the currently visible form can be found as follows (with "currentFormKey" always the same):

currentFormKey = utils.getSubmissionData(payload, "currentFormKey");

current_form_key = utils.getSubmissionData(payload, "currentFormKey")

You can check if a given form is the nested form currently shown by using:

isShown = utils.isCurrentForm(payload, formKey)

Advanced features

This chapter describes a number of advanced features such as how to use your own css classes for your forms or how to trigger events when specific components lose focus.

Use custom CSS classes

Each of the component objects has a customClass property that can be leveraged to alter the appearance of the components by using CSS classes. Use spaces to separate classes. For example, by using the following code, you can make the font of the label of a TextField component smaller and italic:

occupationTextField.addCustomClass("small", "font-italic")

% Alternatively:
occupationTextField.customClass = "small font-italic";

The textfields with and without custom classes are shown below.

You can use custom styles as well, using your own *.css files. This can be done by adding your stylesheet files to a css folder in the same (package) folder your guiInit and guiEvent functions are in.

Consider the following .css file in the css folder:

.bigButton {
    color: black;
    font-size: 28pt;
    height: 80px;
    width: 200px;
    text-align: left;
}

Add the class to your button:

finishButton.customClass = "bigButton";

A comparison between buttons with and without custom classes:

A special css class that can be used is the "form-check-inline" class. When this class is added to all components in a grouping component (like a Container or Panel), the components are laid out horizontally instead of vertically. You can also add it to the individual components you wish to lay out horizontally. In the Example, two CheckBoxes in a Container have this css class:

Use custom Javascript

You can use custom Javascript using your own *.js files. This can be done by adding your files to a js folder in the same (package) folder your guiInit and guiEvent functions are in. The functions and variables defined in the Javascript file will be available for global use in custom validators, callbacks, etc.

Trigger an event when a component loses focus

For components that contain a value, it is possible to trigger an event when the component loses focus. By simply adding the EventOnBlur class to the components of your choice, you enable this feature for those components. For instance: myTextField.customClass = "EventOnBlur". By adding the class to a parent component, for example a DataGrid, all child components on any level will trigger the event when they lose focus.

The event that is triggered will end up in the guiEvent function of the form. The payload will contain the following information on the event:

• action: "event"
• event: "blur"
• key: <path_to_component>, where <path_to_component> is the path to the component. A focus lost event from a cell in a table may for instance get: key: [mydatagrid][3][age]. In this case, mydatagrid is the key of the parent DataGrid, 3 represents the row number (zero-based!) and age is the key of the column that was edited. A focus lost event from a simple textfield directly in the form may for instance get: key: [surname], where surname is the key of the textfield.

Note that adding this custom class to a component only results in triggering an event when the component loses focus, so not every time its value changes. For triggering an event every time a component's value changes (for example for Checkbox components), see the next section. A combination of both these features can be imagined as well.

Trigger an event when a component's value changes

Components that contain a value can trigger an event whenever that value changes by using the following command on them:

obj.addCustomProperty("triggerHappy", true);
obj.addCustomProperty("triggerHappy", "my.package.change");

obj.properties = {"triggerHappy": True}
obj.properties = {"triggerHappy": "my.module.change"}

The event that is triggered will end up in the guiEvent function of the form. The payload will contain the following information on the event:

• action: "event"
• event: "change" when triggerHappy is true, or the triggerHappy value when it is a string
• key: key of the component whose value has changed

Note that using this option causes the component to trigger an event for every value change. This is convenient for checkboxes and similar components. However, for example for TextField components, an event will be triggered after every keystroke. In order to only trigger an event when the user is done editing a field, it is advised to use the EventOnBlur option for components with entered text. Unlike that feature, this option does not apply to child components.

Tables

Simian GUI supports initializing and updating tables of various forms. The most prevalent use cases are described in this chapter.

Regular-sized, editable tables

If you want to include a table in your form whose values must be editable by a user (possibly including adding and removing rows), you can use a DataGrid or EditGrid. The DataGrid supports in-line editing whereas the EditGrid lets the user expand a row and edit it that way. Both these components support child components of any kind: textfields, checkboxes, select components etc. Performance of the form may deteriorate when the table contains a lot of rows or columns (100+). If you encounter this, please refer to one of the other options described in this chapter.

Layout components in a grid

The Table component allows for adding components in a table/grid directly. However, this is mostly useful for defining the layout of the form, not for creating tables with a variable number of elements or for tables with more than a few rows. In order to display data entered from the back-end, use one of the other options described in this chapter.

DataTables

The DataTables component offers many features for tables. It supports editing, sorting and searching of data and handles large amounts of data through pagination. Various options for customisation are available. The great flexibility of options does cause higher complexity in the setup and usage of the component.

Non-editable tables

If you would like to include a table of any size in your form that does not need to be editable by the user, it is advised to do so by using the HtmlTable component. The content of the table can still be filled and updated from the back-end.

Editable tables with many rows

If you want an editable table in your form that can have many rows (100+), it is advised to use a DataTables component. In addition to all kinds of customization functionality, it provides pagination for maintaining performance.

Editable tables with many columns

If you want an editable table in your form that has many columns (50+), you can simply use a DataTables, DataGrid or EditGrid component for this. A DataTables component will perform better than DataGrid or EditGrid components if there are many columns. For non-editable tables with many columns, the HtmlTable component may be useful.

Deployment

The graphical user interfaces created with Simian GUI together with your underlying model or application can be deployed on a server. The benefits of deployment and how to approach it are described in this chapter. How to deploy your Python applications is described here and for MATLAB, this information is presented here.

Note that when your Simian web app code is deployed on your deployment environment, you need to add a configuration to your Simian Portal to ensure that it is available there and can communicate with the deployed code. Users can reach the web app when they have sufficient access rights to use the app.

Key business value

The key business value of deploying your models and applications on a server are:

• Models and applications are kept in production in a governed way. This holds for both the underlying code as well as (intermediate) results.
• Any stakeholder with sufficient access rights can use the applications and run the models. 'Local runs' are also supported for developers. Both operational modes (local and deployed) look and behave nearly identical.
• The computational power of your deployment server can be exploited instead of having to use that of your user’s machines.
• Only one code base must be maintained for both local and deployed mode.
• Applications developed using MATLAB and Python both have the same look and feel.
• MATLAB:
  • No MATLAB license required per user when using the deployed application.
  • Multiple MATLAB Runtime versions are managed simultaneously. This means that models and applications developed in different MATLAB releases can be used next to each other.

MATLAB

Prerequisites

The minimum requirements for deploying your web application developed in MATLAB are as follows:

• MATLAB R2020a or newer is required for Simian GUI.
• MATLAB Production Server
• MATLAB Production Server Dashboard
• MATLAB Runtime Engine v98
• MATLAB Compiler SDK
• Redis is used as a caching mechanism between calls to the MATLAB Production Server.

Deployment workflow

Setting up a MATLAB Production Server is thoroughly described in the Mathworks documentation.

Once your MATLAB Production Server is set up, deploying your application on it can be achieved through the following steps:

1. Prepare your code for deployment.
2. Compile your application into a deployable archive using MATLAB Compiler and MATLAB Compiler SDK.
3. Deploy on MATLAB Production Server.
4. Configure the Simian Portal to connect with the deployed code.

These items are described in more detail below.

Prepare your code for deployment

Before compiling your application into a deployable archive, the code must be made compilable. There are some things to take into consideration.

MATLAB Compiler supports most of the MATLAB language including objects, most MATLAB toolboxes, and user-developed user interfaces. The capabilities and limitations per toolbox are found in the Mathworks documentation. A non-exhaustive list of functions that are not supported for compilation by MATLAB Compiler and MATLAB Compiler SDK is found here.

Compile your application

First create a new function based on the entrypoint example function below, which will be the entry point for communication with your deployable archive. Make sure the namespace field of the metaData struct contains the namespace of your own form. Note that the simian.gui_v2_0_0 package contains a version number that may be different in the version you are including in your archive.

entrypoint.m

function payloadOut = entrypoint(operation, metaData, payloadIn)
    %% Entrypoint.
    % Containing package +my\+name\+space becomes "my.name.space".
    import simian.gui_v2_0_0.*;

    % Put package name into metaData (2nd input to callbackWrapper().
    metaData.namespace = "my.name.space";  % Replace with your own form namespace

    payloadOut = internal.callbackWrapper(operation, metaData, payloadIn);
end

The actual archive can be created in several ways described in the next two sections.

Using buildArchive utility

Compiling your application to a deployable archive can be done with the simian.gui_v2_0_0.buildArchive function (functional as of MATLAB R2020b!). The syntax is: results = simian.gui_v2_0_0.buildArchive(entrypointFcn, options) with entrypointFcn the absolute path to the entrypoint function and option a set of optional name-value pairs for compiler.build.ProductionServerArchiveOptions. For example:

root            = "C:\Files\BallThrower";
archiveName     = "BallThrower";
outDir          = fullfile(root, "CTFs");
entrypoint      = fullfile(root, "entrypoint.m");
additionalFiles = fullfile(root, ["+ballthrower", "@BallThrower"]);
results         = simian.gui_v2_0_0.buildArchive(entrypoint, ...
    "OutputDir", outDir, ...
    "ArchiveName", archiveName, ...
    "AdditionalFiles", additionalFiles);

This is equivalent to the following mcc command in MATLAB:

mcc("-W", "CTF:" + archiveName, ...
    "-d", outDir, ...
    "-Z", "autodetect", ...
    "-U", entrypoint, ...
    "-a", additionalFiles(1), "-a", additionalFiles(2), ...
    "-a", which("mps.cache.connect"), ...
    "-a", <rootOfSimianGui>\config.json, ...
    "-a", <rootOfSimianGui>\+simian\+gui_v2_0_0)

On MATLAB releases R2021b and newer, the buildArchive function outputs a compiler.build.productionServerArchive object. On releases R2020b and R2021a, the function outputs the mcc command that was executed by buildArchive.

The workflow for using this function is as follows:

1. Select the entrypoint.m function as the first input of the buildArchive function.

2. Define what folders and files must be included in the archive. This can be frontend and back-end code, but also for example static data. This set of folders and files constitutes the AdditionalFiles provided to buildArchive. The buildArchive function will automatically add the required Simian GUI folders and files to the archive for you (as well as Simian Wrapper code, if applicable), so these do not have to be specified in your AdditionalFiles.

3. Call the buildArchive function to build the deployable archive.

Using MATLAB functionality

Aside from the buildArchive function, you can also use the MATLAB Production Server Compiler (MPS Compiler) or the MATLAB mcc function. The workflow is similar to using the buildArchive function:

1. If you are using the MPS Compiler, the entrypoint.m function file should be selected as an "Exported Function". When using the mcc function, this function file should be one of the standard inputs.

2. Add the code to the archive:

   • The package(s) and/or folder(s) with the form code and back-end code.
   • Done automatically by the buildArchive function, but a required step when using the MPS Compiler or mcc: The MATLAB Simian GUI's
     • config.json file
     • +simian package folder

   In the MPS Compiler, add these files and folders to the "Additional files" section. In the mcc function add these files using the -a option.

3. Done automatically by the buildArchive function, but a required step when using the MPS Compiler or mcc: To enable caching to a Redis database, the following option needs to be added to the MPS Compiler's settings or the mcc function call:

   -a mps.cache.connect

4. Create a new archive with these settings.

Deploy on MATLAB Production Server

Deployment of the created archives depends on the location and configuration of the MATLAB Production Server. This is documented in the MATLAB documentation in Deploy Archive to MATLAB Production Server and on other pages in the MATLAB documentation.

Configure Simian Portal

The deployed code must be made available from the Simian Portal by adding a configuration. This is documented in the Simian Portal Administration Guide available from the Simian Web apps documentation website.

Python

Some things to take into account before deploying:

• When you run your app locally, everything happens in the same Python session. When you deploy your app, the deployment server may use multiple Python sessions (workers) to process the requests. So, make sure that information that must persist between events is stored in the submission data or is cached.
• Note that deployment environments may reuse Python instances to respond to requests, potentially from multiple users, faster. Therefore, do not use constructs that rely on objects being deleted and recreated between requests.
• It is recommended to fix your dependencies to specific versions to enforce that the exact same versions are installed when a new Python environment is created on the deployment server. This ensures your deployed app runs with tested dependencies and reduces the risk of error or incorrect results.

Deployment process

Deployment of web apps created with Simian GUI generally consists of the following steps:

1. Prepare the environment for the deployment of a new web app.
2. Add simian-gui to your dependencies to ensure it will be available in the deployed Python environment.
   • To install from our PyPi server use the pip option --extra-index-url https://pypiserver.monkeyproofsolutions.nl/simple/
   • For testing with the Ball Thrower example, add simian-examples to the dependencies of your deployed Python environment.
3. Ensure a valid Simian Python license for the deployment environment is available and can be found.
4. Ensure that requests to the deployed code are going to the entrypoint module. (Examples below)
5. The output from the entrypoint module needs to be returned as a response (with status code 200). In case of an error in the backend, the output contains an 'error' field with a message that will be shown in the GUI (see the Ball Thrower for an example).
6. Deploy the web app code to the deployment environment.
7. Configure your Simian Portal to add a link to the deployed web app for the users. This is documented in the Simian Portal Administration Guide available from the Simian Web apps documentation website.

The files that need to be deployed on the server are:

• Web app definition file(s)
• Simian Python license file for the deployment environment.
• Model/back-end. (Alternatively API calls can be used to connect with a model on a different server.)
• Deployment target specific entry_point_deploy wrapper function. (Examples below)
  • To connect to your own web app, replace the "simian.examples.ballthrower" name with its fully qualified module name.

Since there is no standard method for deploying Python code, a number of potential methods are discussed in the following sections:

• Azure Functions
• ownR
• FastAPI - uvicorn
• Flask

Other deployment targets should also be possible, but they will require their own version of what is described below.

To test whether the deployed web apps work, send a POST request with json body ["config", {}, {}] to the deployment host and port. You should get a response with a stringified json dictionary containing a session_id and some other fields.

Azure Functions

GUIs created with Simian GUI can be deployed as Azure functions:

1. Create an Azure Functions project.

   Include simian-gui (and optionally simian-examples) in the Azure Functions requirements file to ensure that the required modules for Simian are installed in the Azure environment.

2. Put all the necessary files as described above in the project folder.

3. In the Azure Functions v2 programming model's function_app.py file, the Azure Functions HttpRequests need to be processed and Responses need to be created. See the example code below on how to make Azure Functions communicate with Simian GUI. For your own GUIs ensure that the fully qualified name of your own GUI is used.

   To ensure all Simian GUI and GUI definition files can be found and used they need to be on the Python path.

4. Publish the project on Azure and deploy to the Function App.

# Use back-end type `python_azure_functions_v2` in the portal configuration.
import json
import azure.functions as func
from simian.entrypoint import entry_point_deploy

app = func.FunctionApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@app.route(route="httpTrigger")
def httpTrigger(req: func.HttpRequest) -> func.HttpResponse:
    request_data = req.get_json()
    response = entry_point_deploy("simian.examples.ballthrower", request_data)

    return func.HttpResponse(json.dumps(response), status_code=200)

ownR

GUIs created with Simian GUI can be deployed as ownR applications:

1. Create a new ownR application as documented on the Functional Analytics wiki (account required).

2. Put the necessary files as described above into the repository of the ownR application.

   Ensure the requirements.txt file of Simian GUI is on the root level and add simian-gui (and optionally simian-examples) to it. This will ensure that ownR can use it to install the required modules in the Python environment.

3. ownR requires a module to exist at the root level that has the same name as the application. In this module import Simian GUI's entrypoint module and route the requests from the ownR environment to Simian GUI's entry_point_deploy function as illustrated below. For your own GUIs ensure that the fully qualified name of your own GUI is used.

   To ensure all Simian GUI and GUI definition files can be found and used they need to be on the Python path.

4. Commit and push the changes to the repository. This will trigger a rebuild of the application and your changes to become available.

# Use back-end type `python_ownr` in the portal configuration.

from simian.entrypoint import entry_point_deploy

def entry_point(operation: str, meta_data: dict, payload_in: dict) -> dict:
    """Route the request to the entrypoint module."""
    return entry_point_deploy(
        "simian.examples.ballthrower",
        operation=operation,
        meta_data=meta_data,
        payload_in=payload_in
    )

FastAPI - uvicorn

GUIs created with Simian GUI can be deployed with FastAPI and uvicorn.

1. Install simian-gui, FastAPI, and uvicorn in your Python environment.

2. Put all the necessary files as described above in a folder.

3. Create a fastapi_deploy.py file as shown below. For your own GUIs ensure that the fully qualified name of your own GUI is used.

4. You can use the procedure as described on the uvicorn website to run uvicorn.
   Hosting the app with multiple workers is supported with gunicorn.

# Use back-end type `python_fastapi` in the portal configuration.
from fastapi import Body, FastAPI
from fastapi.responses import JSONResponse
from simian.entrypoint import entry_point_deploy

app = FastAPI()

@app.post("/apps/ballthrower", response_class=JSONResponse)
def route_app_requests(request_data: list = Body()) -> dict:
    """Route requests to ballthrower GUI and return the response."""
    return entry_point_deploy("simian.examples.ballthrower", request_data)

Flask

GUIs created with Simian GUI can be deployed with Flask. Note that Flask is not recommended to be used for production.

1. Install Flask in your Python environment.

2. Put all the necessary files as described above in a folder.

3. Create a flask_hosting.py file as shown below. For your own GUIs modify the secret key (or store it elsewhere) and ensure that the fully qualified name of your own GUI is used.

4. You can use the procedure as described on the Flask website to run Flask.

# Use back-end type `python_flask_v2` in the portal configuration.
from flask import Flask, request
from simian.entrypoint import entry_point_deploy


def create_app() -> Flask:
    """Create Flask App for hosting a webGUI."""
    # create and configure the app
    app = Flask(__name__)

    # Store secret key elsewhere.
    app.secret_key = b'_8#h3S"T7U9z\n\xec]/'

    @app.route('/apps/ballthrower', methods=('POST', ))
    def route_app_requests() -> dict:
        return entry_point_deploy("simian.examples.ballthrower", request.data)

    return app

Example

In this chapter the Ball Thrower example GUI shipped with Simian GUI is described. For new users of Simian GUI the code of this example and the descriptions in this chapter may offer a good starting point to start using Simian GUI.

Ball Thrower

The Ball Thrower example contains a form that facilitates running a Ball Thrower simulation model. The model uses the MATLAB ode45 or scipy.integrate.solve_ivp solver to calculate the trajectory of the ball. The application upon startup looks as follows:

The model allows for simulating the throw of a ball in an idealised situation without drag and wind and can optionally be run to also simulate the effects of drag and wind on the ball.

The model also has inputs for the throw speed, ball radius, mass and drag coefficient, wind speed, gravity and air density. These inputs can be set from the form.

The following sections describe how to run this example, the most interesting features of the form and the physics and math behind the ball thrower model.

Running the example

To run the Ball Thrower example in a local MATLAB session, ensure that Simian GUI and the Ball Thrower example files are on the MATLAB path and run the following command:

simian.local_v2_0_0.Uiformio("simian.examples_v2_0_0.ballthrower");

To start the form in a pywebview window, make sure Simian GUI is on the Python path and run the following command in Python (ensure that pywebview is installed though, or you will get an error):

import simian.local
simian.local.Uiformio("simian.examples.ballthrower")

To simulate the throw of a ball, click the "Throw" Button. The trajectory of the ball will be shown in the plot and the settings are stored in the table in the "Used settings" tab. The speed with which the ball is thrown and the gravity can be modified to simulate the effect of these parameters on the trajectory of the ball. To simulate the effects of wind and/or drag on the throw, tick the corresponding options. These options will enable more settings that can be modified, which will have their own effect on the trajectory of the ball.

BallThrower files

The files making up the MATLAB Ball Thrower example are stored in the simian-examples folder.

The form files are in the +simian/+examples_v2_0_0/+ballthrower package:

• guiInit.m: contains the form definition.
• guiEvent.m: contains the callbacks of the throw and clear buttons and connects with the model to simulate the ball's trajectory.
• logo.jpg: image shown in the header of the form.

The model for simulating a ball throw is in the +simian/+examples_v2_0_0/@BallThrower class:

• ballThrower.m: ballThrower class definition. Needs to be instantiated before you can call the throwBall method.
• dragBall.m: method creating the set of differential equations that need to be solved for the throw.
• throwBall.m: method starting the simulation of the trajectory of the ball.
• zeroCrossing.m: method for determining the ground contact point boundary condition of the throw.

The Python Ball Thrower contains the same functionality, but instead of being split over multiple files it is all in the simian/examples/ballthrower.py module.

Features

The most interesting features of the example are discussed in the following subsections. Where possible code snippets from the example are included (sometimes slightly modified for readability) to illustrate how these features end up in code. The descriptions also contain links to other parts of the documentation where more information can be found.

We will discuss how the Ball Thrower example can conditionally enable and hide controls, conditionally override a value, add client side validation, prevent runs with invalid settings, and make parameters required. We will also show how to plot and tabulate data, add an image to the form and how we created the form's layout.

Conditionally enabled state

Wind cannot be simulated without simulating drag, as without drag the wind has no effect on the ball. To capture this in the form the "Enable wind" Checkbox is only enabled when the "Enable drag" checkbox is enabled.

To get this behaviour we set the disabled state of the "Enable wind" checkbox to true and add a Logic object to the "Enable wind" checkbox. Each Logic object needs a trigger and one or more actions. The trigger describes under which circumstances the actions in the logic object should be executed.

To ease disabling components with a trigger, the disableWhen method is available for each component. It uses the createDisableLogic function from the componentProperties package/module to disable the component when the trigger is triggered.

enableWindCheckbox.disableWhen("simple", {"enableDrag", false})

enable_wind_checkbox.disable_when(
    trigger_type="simple", trigger_value=["enableDrag", False]
)

Alternatively, when adding components from a table we can create a Logic object and put it in a struct/dict for the options column.

windLogic = componentProperties.createDisableLogic(...
    "simple", {"enableDrag", false});
windOptions.logic = windLogic;

wind_logic = component_properties.create_disable_logic(
    trigger_type="simple", trigger_value=["enableDrag", False]
)
wind_options["logic"] = wind_logic

Conditionally override a value

Disabling the "Enable wind" checkbox alone is not enough. It may already have been ticked, so we also need to ensure it is unticked when the "Enable drag" option is unticked.

For this we create an untick action. This action should change the checkbox's value property to false. We simply add this new action to the actions property of the existing Logic object of the "Enable wind" control, as it already has the correct trigger for this action.

windLogic.actions{end + 1} = struct( ...
    "type", "value",  ...
    "value", "value = false");

wind_logic.actions.append(
    {
        "type": "value",
        "value": "value = false"
    }
)

Conditionally hide controls

When drag and or wind are disabled, the controls for the ball properties and the wind speed are not needed and can be hidden. For this we do not use a Logic object, but a Conditional object which has a more concise definition. First the Conditional object is created with the control we want to hide as input. Then we put the key of the control the hiding depends on in the when property. The value of that control for which our control is to be hidden is put in the eq property.

The following statements hide the ballPanel Panel when the "Enable drag" checkbox is unticked:

% Hide ball panel when drag is not enabled.
ballCondition       = componentProperties.Conditional(ballPanel);
ballCondition.when  = "enableDrag";
ballCondition.eq    = false;

% Or when using table's 'options' column:
ballOptions.conditional.when = "enableDrag";
ballOptions.conditional.eq   = false;

# Hide ball panel when drag is not enabled.
drag_enabled = component_properties.Conditional(ballPanel)
drag_enabled.when = "enableDrag"
drag_enabled.eq = False

# Or when using table's 'options' column:
ball_options = {"conditional": {"when": "enableDrag", "eq": False}}

When controls are hidden, their values are not included in the payload that is sent to the back-end. To ensure that values of hidden controls are included in the payload and user defined values persist when the control is (temporarily) hidden, set the clearOnHide property of the control to false (default is true).

ballRadius.clearOnHide = false;

ball_radius.clearOnHide = False

Client side validation

For some controls we need to limit the range of values that can be entered. The ball's radius for instance should not be negative. To enforce this we can add a Validate object to a control. For the ball radius text field we create a Validate object with the control as input and set the min property to zero. This will ensure that when negative values are entered an error message is shown to highlight the problem.

This type of validation can also be done in the back-end, but doing it in the form provides quicker feedback and shows it close to the invalid value:

% Allow values larger than 0.
radiusValidate      = componentProperties.Validate(ballRadius);
radiusValidate.min  = 0;

% Or when using table's 'options' column:
radiusOptions.validate.min = 0;

# Allow values larger than 0.
ball_radius_validate = component_properties.Validate(ballRadius)
ball_radius_validate.min = 0

# Or when using table's 'options' column:
radius_options = {"validate": {"min":  0}}

Prevent run with invalid settings

To prevent running the model with values that are flagged invalid by the validation the "Throw" Button is disabled. This can simply be done by setting the disableOnInvalid property of the throw button control to true. This ensures that when the validations in the form detects an invalid value, the throw button is automatically disabled and only enabled again when all values in the form are valid.

throwButton.disableOnInvalid = true;

throw_button.disableOnInvalid = True

Required parameters

When empty values are not allowed for a setting, using the setRequired() method of the component will ensure that empty values are marked invalid. The setRequired() method creates a Validate object for the control (if none exist yet) and sets the required property to true (default is false). When you add a new Validate object to the control after using the setRequired() method, the control will lose its required state. Alternatively you can directly set the required property of the Validate object to true.

Controls that have a required value are indicated with a red asterisk and empty values are marked invalid.

ballRadius = component.Number("ballRadius");
ballRadius.setRequired();

% or 

ballRadiusValidate = componentProperties.Validate(ballRadius);
ballRadiusValidate.required = true;

% Or when using table's 'options' column:
radiusOptions.validate.required = true;

ball_radius = component.Number("ballRadius")
ball_radius.setRequired()

# or
ball_radius_validate = component_properties.Validate(ball_radius)
ball_radius_validate.required = True

# Or when using table's 'options' column:
radius_options["validate"].update({"required": True})

Plotting results

To plot ball trajectories in the form after clicking the "Throw" button, we add a Plotly object in the definition of the form and set its "title", "xaxis" and "yaxis" properties to make it look nicer:

% Create a plot window to plot the ball trajectories in.
myPlot                      = component.Plotly("plot", column_2);
myPlot.defaultValue.data    = {};
myPlot.defaultValue.layout  = struct(...
    "title", struct("text", "Balls thrown"), ...
    "xaxis", struct("title", "Distance [m]"), ...
    "yaxis", struct("title", "Height [m]")); 
myPlot.defaultValue.config  = struct(...
    "displaylogo", false);

# Create a plot window to plot the ball trajectories in.
my_plot = component.Plotly("plot", column_2)
my_plot.defaultValue['data'] = []
my_plot.defaultValue['layout'] = {
    "title": {"text": "Balls thrown"}, 
    "xaxis": {"title": "Distance [m]"},
    "yaxis": {"title": "Height [m]"},
    "margin": {"t": 40, "b": 30, "l": 50}
}
my_plot.defaultValue['config'] = {
    "displaylogo": False
}

To plot a ball trajectory in the form we create a Plotly object from the data in the form via the getSubmissionData utility function. We can then use the utils.Plotly.plot() method (MATLAB) or Plotly Figure.add_scatter() method (Python) to plot the x and y values that were returned by the BallThrower model. In MATLAB we can extend the legend by first getting its existing values and then recreating the legend with the existing and new values. In Python the legend is automatically extended with the name of the added scatter trace. We then put the Plotly object in the payload using the setSubmissionData utility function.

% Create a plotly object from the data in the form, put the current data in the plotly
% object and get the legends.
plotly          = utils.getSubmissionData(payload, "plot");
dataSpec        = plotly.data;
existingNames   = cellfun(@(x) x.name, plotly.data, "UniformOutput", false);

% Plot the newly calculated x and y values, append the legend and put the plotly
% object in the submission data.
nr = numel(dataSpec) + 1;
plotly.plot(x, y)
plotly.legend(existingNames{:}, sprintf("Attempt %d", nr));
payload = utils.setSubmissionData(payload, "plot", plotly);

# Create a Plotly object from the information in the payload.
plot_obj = utils.getSubmissionData(payload, key='plot')[0]

# Plot the new newly calculated x and y values, append the legend and put the plotly
# object in the submission data.
nr = len(plot_obj.figure.data) + 1
plot_obj.figure.add_scatter(x=x, y=y, name=f"Attempt {nr}", mode="lines")
utils.setSubmissionData(payload, key='plot', data=plot_obj)

Tabulating used settings

To keep track of the settings used for the simulations of the throws, we can add them to a table. In the form definition we create a DataGrid and use its setContent method to add nine non-editable columns with TextFields.

% Create a table to store the throw settings in.
tableOut        = component.DataGrid("summary", tabB);
tableOut.label  = "Used settings per throw";
tableOut.setContent(...
    ["Attempt", "Horizontal speed", "Vertical speed", "Wind speed", "Ball mass", ...
    "Radius", "Drag Coeff.", "Gravity", "Air density"], ...
    ["nr", "u0", "v0", "w", "m", "r", "Cd", "g", "rho"], ...
    repmat("TextField", 1, 9), ...
    false(1, 9));

# Create a table to store the throw settings in.
table_out = component.DataGrid("summary", tab_b)
table_out.setContent(
    labels=["Attempt", "Horizontal speed", "Vertical speed", "Wind speed", "Ball mass",
            "Radius","Drag Coeff.", "Gravity", "Air density"],
    keys=["nr", "u0", "v0", "w", "m", "r", "Cd", "g", "rho"],
    component_types=["TextField"] * 9,
    is_editable=[False] * 9)
table_out.label = "Used settings per throw"

When the Throw button is clicked we create a new row with the settings that were used in the simulation. This new row is appended to the values already in the table and using the setSubmissionData() function in the utils, it is added to the payload that will be sent to the form.

% Update the table with the settings used for the throws.
newRow = {nr, horSpeed, verSpeed, windSpeed, massBall, radiusBall, dragCoeff, ...
    gravity, rhoAir};

if nr == 1
    % First throw. Only put the new row in the table.
    newTableValues  = newRow;
else
    tableValues     = sub_getTableValues(payload, "summary");
    newTableValues  = [tableValues; newRow];
end

payload = utils.setSubmissionData(payload, "summary", newTableValues);

# Update the table with the settings used for the throws.
new_row = [nr, hor_speed, ver_speed, wind_speed, mass_ball, radius_ball, drag_coeff,
            gravity, rho_air]

if nr == 1:
    # First throw. Only put the new row in the table.
    new_table_values = [new_row]
else:
    # Extra row. Append the row to the DataFrame from the submission data.
    new_table_values = utils.getSubmissionData(payload, key="summary")[0]
    new_table_values = new_table_values.append(
        DataFrame(data=[new_row], columns=new_table_values.columns))

utils.setSubmissionData(payload, key="summary", data=new_table_values)

Including images

Images can be included in the form by creating an HtmlElement and using its setLocalImage() method to point to the image that should be shown. For stability it is best to use a relative file name. In this example the image is next to the guiInit.m file in which the path to the image is set. Using fileparts(mfilename("fullpath")) we get the folder containing the guiInit.m and image files. Using that as first input for the fullfile() function we can make the path to the image file relative:

imageLogo = component.HtmlElement("logo");
imageLogo.setLocalImage( ...
    fullfile(fileparts(mfilename("fullpath")), "logo.jpg"));

image_logo = component.HtmlElement("logo")
image_logo.setLocalImage(
    os.path.join(os.path.dirname(__file__), "logo.png")
)

Layout of controls

Controls in the form can be laid out using panels, containers, columns, tables and tabs.
Panels allow for grouping controls and allow for hiding them by collapsing the panel.
Containers allow for grouping controls without adding borders or background colors.
Columns allow for putting controls and panels next to each-other, making better use of the space in the form. When the window containing the form gets smaller, the contents of the columns are placed below each-other to reduce horizontal scrolling. Tables allow for laying components out in a grid. Tabs allow for grouping and showing/hiding larger parts of the form.

Background

In this section the physics and math side of throwing a ball are discussed for an idealized situation without drag and wind, and for situations where drag, and wind and drag are simulated.

Idealized situation

Let"s throw a ball in an ideal world without drag and wind. Defining a starting point, throwing speed and gravitation will do the trick:

\[\sum \vec{F} = m \cdot \vec{g},\]

therefore, we can derive that:

\[ \begin{align} x & = u_0 t \\ y & = v_0 t - \frac{1}{2}gt^2 \end{align} \]

This can be solved analytically:
\[ \frac{d^2}{dt^2} \begin{bmatrix} x \\ y \end{bmatrix}
= \begin{bmatrix} 0 \\ -g \end{bmatrix} \]

The begin position and speed are enough to determine the final result:
\[x_0, y_0, u_0, v_0\]

Such that:
\[ \begin{align} x(t) & = x_0 + u_0 t \\ y(t) & = y_0 + v_0 t - \frac{1}{2}gt^2 \\ u(t) & = u_0 \\ v(t) & = v_0 - gt \\ \end{align} \]

Adding drag

When we add drag to the idealized situation, things become more complicated:

\[\vec{F}_{drag} = -\frac{1}{2} \rho A |\vec{v}|^2 C_d \hat{v} \]

And thus: \[\sum \vec{F} = \vec{F}_{drag} + \vec{F}_g.\]

This can no longer be solved analytically, this can only be solved numerically. Therefore we need to solve the following equations using a MATLAB ode45 solver.

\[ \dfrac{d}{dt} \begin{bmatrix} x \\ \dot{x} \\ y \\ \dot{y} \end{bmatrix}
= \begin{bmatrix} \dot{x} \\
-\frac{1}{2m} \rho \dot{x}^2 C_d A \dfrac{\dot{x}}{|\dot{x}|} \\
\dot{y} \\
-\frac{1}{2m} \rho \dot{y}^2 C_d A \dfrac{\dot{y}}{|\dot{y}|} + g \end{bmatrix} \]

The begin position and speed are not enough to determine the final result:
\[x_0, y_0, u_0, v_0\]

For this situation we need more parameters:

• \( m \): Mass of the ball
• \( \rho \): Air density
• \( r \): Area of the surface, assumed a sphere here, so radius is asked

Adding wind

When we add wind, the equations become slightly more complicated.

\[\vec{F}_{drag + wind} = -\frac{1}{2} \rho A |\vec{v_r}|^2 C_d \hat{v_r} \]

where \(\vec{v_r} = \vec{v} + \vec{w}\), and

\[\sum \vec{F} = \vec{F}_{drag + wind} + \vec{F}_g.\]

The equations using that need to be solved with the ode45 solver become:

\[ \dfrac{d}{dt}\begin{bmatrix} x \\ \dot{x} \\ y \\ \dot{y} \end{bmatrix}
= \begin{bmatrix} \dot{x} \\
-\frac{1}{2m} \rho (\dot{x} - w)^2 C_d A \dfrac{\dot{x} - w}{|\dot{x} - w|} \\
\dot{y} \\
-\frac{1}{2m} \rho \dot{y}^2 C_d A \dfrac{\dot{y}}{|\dot{y}|} + g \end{bmatrix} \]

The begin position and speed are not enough to determine the final result: \[x_0, y_0, u_0, v_0\]

For this situation we need more parameters:

• \( m \): Mass of the ball
• \( \rho \): Air density
• \( r \): Area of the surface, assumed a sphere here, so radius is asked
• \( w \): Wind Speed

How to

In this chapter, you can find the answers to questions on how to achieve certain things with Simian GUI that may not be so straightforward. Examples include conditionally disabling a component or displaying components side by side.

How to add a piece of uneditable text?

You can use a component's label property to set the text displayed with the component. Multiple component types support setting the labelPosition so that you can change the position of the label with respect to the component. Alternatively, you can set the description property to display text a bit more subtle, under the component.

If this does not meet your demands, you can use an HtmlElement component. For example:

h           = component.HtmlElement("Title", form);
h.content   = "Page title";
h.tag       = "h1";

h = component.HtmlElement("Title", form)
h.content = "Page title"
h.tag = "h1"

The resulting title is:

How to place a button next to a textfield?

Normally when adding multiple components to a form, they are placed below one another. If you wish to add multiple components side by side, there are a few ways of doing this. One of them is using the form-check-inline class as described in Advanced features. This approach is used to place a button next to a textfield in the following example:

txt                 = component.TextField("name", form);
txt.label           = "Name";
txt.customClass     = "form-check-inline";
txt.labelPosition   = "left-left";

btn             = component.Button("check", form);
btn.label       = "Check";
btn.customClass = "form-check-inline";

txt = component.TextField("name", form)
txt.label = "Name"
txt.customClass = "form-check-inline"
txt.labelPosition = "left-left"

btn = component.Button("check", form)
btn.label = "Check"
btn.customClass = "form-check-inline"

An alternative approach is to use a Columns component to place the components side by side. If we wish to display the textfield's label above the component instead of next to it, we have to specify the label separately in order to maintain horizontal alignment between the textfield and the button:

% Separately define a label for the textfield.
lbl         = component.HtmlElement("txt_label", form);
lbl.content = "Name";

% Keep the TextField's label empty.
txt         = component.TextField("name");
btn         = component.Button("check");
btn.label   = "Check";

cols = component.Columns("my_columns", form);
cols.setContent({txt, btn}, [2, 1])

# Separately define a label for the textfield.
lbl = component.HtmlElement("txt_label", form)
lbl.content = "Name"

# Keep the TextField's label empty.
txt = component.TextField("name")
btn = component.Button("check")
btn.label = "Check"

cols = component.Columns("my_columns", form)
cols.setContent([txt, btn], [2, 1])

How to hide a component unless a condition is met?

You can use a Conditional for this. Alternatively, you can use the customConditional property to achieve this. For example, if you wish to show a button only when a specific checkbox is checked and a number that is entered is larger than 5, use the following code:

cb          = component.Checkbox("TheCheckbox", form);
cb.label    = "I agree";

nr          = component.Number("TheNumber", form);
nr.label    = "Years of experience";

btn         = component.Button("TheButton", form);
btn.hidden  = true;
btn.label   = "Continue";
btn.block   = true;
btn.customConditional = "show = data.TheCheckbox && data.TheNumber > 5;";

cb = component.Checkbox("TheCheckbox", form)
cb.label = "I agree"

nr = component.Number("TheNumber", form)
nr.label = "Years of experience"

btn = component.Button("TheButton", form)
btn.hidden = True
btn.label = "Continue"
btn.block = True
btn.customConditional = "show = data.TheCheckbox && data.TheNumber > 5;"

The resulting form in action:

How to disable a component unless a condition is met?

The enabled state of a component can be changed based on the values of other components by giving the component a Logic object. This Logic object has a trigger property where you can specify when the state must be changed, and an actions property where you specify what must be changed.

In the example below we create a checkbox and a number component for input fields, and a button that is enabled when the checkbox is ticked and the number exceeds five. To get this behaviour we use the disableWhen function that all components have. Refer to createDisableLogic for more information on the shared inputs.

cb          = component.Checkbox("TheCheckbox", form);
cb.label    = "I agree";

nr          = component.Number("TheNumber", form);
nr.label    = "Years of experience";

btn             = component.Button("TheButton", form);
btn.label       = "Continue";
btn.block       = true;
btn.disabled    = true;

% Add enable Logic.
btn.disableWhen("javascript", "result = data.TheCheckbox && data.TheNumber > 5", false)

cb = component.Checkbox("TheCheckbox", form)
cb.label = "I agree"

nr = component.Number("TheNumber", form)
nr.label = "Years of experience"

btn = component.Button("TheButton", form)
btn.label = "Continue"
btn.block = True
btn.disabled = True

# Add enable Logic.
btn.disable_when("javascript", "result = data.TheCheckbox && data.TheNumber > 5", False)

The resulting form in action:

Note that only for Buttons the same can be achieved by using the customConditional property, similar to how this property can be used to hide components.

btn.customConditional = "component.disabled = data.TheCheckbox && data.TheNumber > 5";

Buttons also have the disableOnInvalid property (default false). When set to true, this disables the button when any value in the form does not meet its component's validation criteria.

How to send an update to the form and immediately continue calculations?