Table of Contents

Simian GUI Documentation

Table of Contents

• Introduction
  • Python
  • Matlab
  • Form.io
• Getting started
  • Python setup
  • MATLAB setup
  • Hello world!
• Overview
• Form definition
  • gui_init
  • Form structure
  • Simian Form Builder
  • Components
    • Basic
      • Button
      • Checkbox
      • Number
      • Password
      • Radio
      • Select
      • Selectboxes
      • TextArea
      • TextField
    • Advanced
      • Address
      • ColorPicker
      • Currency
      • DateTime
      • Day
      • Email
      • PhoneNumber
      • Signature
      • Slider
      • Survey
      • Tags
      • Time
      • Toggle
      • Url
    • Layout
      • Columns
      • Content
      • FieldSet
      • Html
      • HtmlElement
      • HtmlTable
      • Panel
      • Table
      • Tabs
      • Well
    • Data
      • Container
      • DataGrid
      • DataMap
      • DataTables
      • EditGrid
      • Hidden
    • Miscellaneous
      • File
      • Form
      • Plotly
        • Python
        • MATLAB
      • ResultFile
  • Component nesting
  • Component properties
    • Validate
    • Conditional
    • Logic
    • Json
    • Error
  • Composed components
    • PropertyEditor
    • StatusIndicator
  • Navbar
  • Reusing component definitions
  • Form refresh
• Handling events
  • gui_event
  • Submission data
  • Caching state
  • Error handling
  • gui_upload
  • gui_download
• Nested forms
• Advanced features
  • Custom CSS classes
  • Custom JavaScript
  • Focus lost event
  • Value changed event
  • String evaluation
• Tables
• Deployment
  • Python
  • MATLAB
• Example
• How to
  • How to add a piece of uneditable text?
  • How to place a button next to a textfield?
  • 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?
  • How to add an image?
• Testing
• Frequently asked questions (FAQ)
  • Form definition
  • Runtime
• Release notes
• Known issues & limitations

Introduction

Simian GUI provides an accessible way to define graphical user interfaces for your Python or MATLAB 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 (Python or MATLAB).
• Write the user interface definition in basic Python or MATLAB code. Utilize over 40 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 Python and a MATLAB implementation, both of which are described in this document. The pieces of code in this document are Python or MATLAB 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:

• 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
• MATLAB:
  • simian.gui_v3_0_1.* where the release number 3_0_1 may vary.

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.

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.12 64-bit are supported. Windows, Linux and Mac operating systems are supported.

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.

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 R2022a¹ and newer.

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 behaviour 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 favourite 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).

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 WSGI applications or Matlab Production Server.

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 Python or MATLAB application.

To gain insight into the capabilities of Simian GUI, you can use the Simian Form Builder (beta) or the online form builder. It illustrates how Form.io forms can be constructed and what components and properties are available. The online builder cannot be used for the actual implementation of your application or tool. 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 Python/MATLAB, 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 dict/struct 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 Python and in MATLAB.

The first step is to setup your project in Python or MATLAB . 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.

Python setup

Requires the following resources:

• An internet connection to download and install Simian GUI from our PyPi server (or an offline alternative).

Setup steps:

1. Create and activate a Python environment.

   Note: Use Python 3.8 - 3.12.

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]
      

Testing your setup

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

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-builder:

• simian
  • css CSS for the builder.
  • templates Templates for creating apps and composed components.
  • builder.json Builder form definition.
  • builder.py The Builder module.
  • version.txt Version information.

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:

• 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.
  • version.txt Version information.

MATLAB setup

Requires the following resource:

• MATLAB Simian GUI release toolbox file.

Setup steps:

1. Install the toolbox by double-clicking it in the MATLAB file browser or use matlab.addons.install. Refer to section Simian GUI contents for more information about its contents.

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

Testing your setup

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

form = simian.gui_v3_0_1.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_v3_0_1.Uiformio("simian.examples_v3_0_1.ballthrower");

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

• Unable to resolve the name simian.gui_v3_0_1.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_v3_0_1.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_v3_0_1.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.

• simian-examples Folder containing the included examples.
  • +simian
    • +examples_v3_0_1
      • @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.
      • +treemap The Tree map 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_v3_0_1 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.
  • config.json File containing the version number of the front-end.
• simian-local Folder containing the code to run Simian GUI locally.
  • +simian
    • +local_v3_0_1 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.
• GettingStarted.mlx Help text for the toolbox.

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_v3_0_1";
   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_v3_0_1.updateVersion("C:\Applications\MyApp"). Save all m-files and make a back-up before you run this function!

Hello world!

This section will guide you through creating your first, simple Simian web app.

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:

• Python Setup
• MATLAB Setup

First application

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

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 the MATLAB example.

Add components to the form

A component is created with a call to its constructor. Each constructor 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

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_v3_0_1.*;

    % 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_v3_0_1.*;

    % Process the events.
end

Start the application from the command line:

simian.local_v3_0_1.Uiformio("hello")

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

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

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 gui_event 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

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_v3_0_1.Uiformio("hello")

The form now looks as shown in the figure below.

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.

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_v3_0_1.*;

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

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

    % 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_v3_0_1.Uiformio("hello")

Click the button.

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

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 Python the namespace must be a module. For MATLAB it must be a package. Simian GUI must be able to find the namespace on the path. Refer to the examples for illustrations.

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

Note that the snake case gui_xxx functions have a lower camel case guiXxx equivalent in the MATLAB version of Simian GUI.

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:

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

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

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

The following extra options can be specified:

• 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.
  • Uiformio(_, show_refresh=True) Shows the Refresh button in the navbar.
• 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.
  • Uiformio(_, "ShowRefresh", true) Shows the Refresh button in the navbar.

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

Form definition

The form definition is specified in the gui_init 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 40 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.

Implementing gui_init

The gui_init 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

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

function payload = guiInit(metaData)
    ...
end

Arguments

meta_data:

Meta data describing the client session.

Dict/struct 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
• mode: local or deployed
• client_data:
  • authenticated_user: for deployed apps, the portal provides the logged on user info
    • user_displayname: user name for printing (e.g. "John Smith")
    • username: unique identifier used by the authentication protocol

In the gui_init 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.

Dict/struct with fields:

• form: a simian.gui.Form
• navbar (optional): dict/struct 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 dict/struct with a form field that contains the form.
  • Optionally specify a navbar field to set the logo and title of the application.

There are three ways of adding components to the form:

• Adding components from constructor
• Adding components from table
• Adding components from JSON

Adding components from constructor

Components are created by calling the Component constructor:

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:

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

import simian.gui_v3_0_1.component.*
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 Pandas DataFrame or list of lists (in Python) or MATLAB table 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 Pandas DataFrame, list of lists, or MATLAB table.

It returns the created components in a dict/struct.

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: Dictionary/struct with options, may contain any property that can be set to the component. Use None/missing to leave unspecified. If the column is not present, all options will be set to None/missing. 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 None/missing to leave unspecified. If the column is not present, all default values will be set to None/missing.
• label: Label for the component. Use None/missing to leave unspecified. If the column is not present, all labels will be set to None/missing.
• tooltip: Tooltip for the component. Use None/missing to leave unspecified. If the column is not present, all tooltips will be set to None/missing.

In case of a Python list of lists input these columns are assumed to be the fields of the inner lists, unless specified differently in the column_names input.

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 dict/struct that is put in the table.

The dict/struct that is returned uses the keys specified in the table definition as keys/fields. 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 DataFrame/table. 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 dict/struct is used for multiple components, further reducing the amount of code required for building the form.

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  ],
    ]

    return utils.addComponentsFromTable(form, component_specs, ["key", "class", "level", "options"])


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" ],
    ]

    column_names = ["key", "class", "level", "options", "defaultValue", "label"],

    utils.addComponentsFromTable(column, component_specs, column_names)

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

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(from_file="/path/to/my/form.json")
form = Form(from_file=__file__)  # The extension is replaced with ".json" for convenience.

form = Form(FromFile="/path/to/my/form.json");
form = Form(FromFile=mfilename("fullpath")); % The ".json" extension is added 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.

This can be done by calling the static method Form.componentInitializer before building the form. The input consists of named arguments, where the keyword/name must match the key of the component and the value is an initialization function handle. The initialization function will be called with one input argument: the component object. Only one function can be registered per component.

Note that the initialization function must be registered before the component is created. Otherwise, the function is not applied to the component. As a result, you cannot register an initialization function from another initialization function.

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()

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

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

Note that you can configure the behaviour of registered initializer functions by adding inputs to a function that wraps the actual function. In the example below a standard set_default function is used to set the default value of multiple components.

def gui_init(meta_data: dict) -> dict:
    Form.componentInitializer(
        name=set_default(os.getlogin()),
        folder=set_default(os.getcwd()),
    )
    form = Form(from_file=__file__)
    return {"form": form}

def set_default(value) -> Callable:
    def inner(comp: component.TextField):
        comp.defaultValue = value
    return inner

function payload = guiInit(metaData)
    Form.componentInitializer( ...
        'name', set_default(getenv('USERNAME')), ...
        'folder', set_default(cd()) ...
        );
    form = Form(FromFile='form.json');
    payload = struct("form", form);
end

function func = set_default(value)
    func = @(comp) inner(comp, value);
end

function payload = inner(comp, value)
    comp.defaultValue = value;
end

In a wrapped initialization function it is possible to register other initialization functions. In the example below the initialization function for the folder TextField is added in the function wrapping the name TextField initializer.

A construction like this is useful when your web app is created from a JSON form definition and incorporates another JSON form definition with initializer functions that must be executed.

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

def initialize_name() -> Callable:
    # Add an initialize function for the 'folder' component.
    Form.componentInitializer(folder=initialize_folder)
    def inner(comp: component.TextField):
        comp.defaultValue = os.getlogin()
    return inner

def initialize_folder(comp: component.TextField):
    comp.defaultValue = os.getcwd()

function payload = guiInit(metaData)
    Form.componentInitializer('name', initializeName());  % Function is executed!
    form = Form(FromFile='form.json');
    payload = struct("form", form);
end

function func = initializeName()
    % Add an initialize function for the 'folder' component.
    Form.componentInitializer(folder=@initialize_folder)
    func = @(comp) inner(comp);
end

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

function initialize_folder(comp)
    comp.defaultValue = cd();
end

Simian Form Builder

The Simian Form Builder can be used to build Simian web apps or components in a graphical environment, reducing the amount of code to be written.

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 only runs in Python, although it can be used to create Matlab apps and components.

Installation

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

pip install --extra-index-url https://pypi.simiansuite.com/ simian-builder

Getting started

Open the Simian Form Builder window

python -m simian.builder

The Builder opens and shows the default layout. The menu shows two buttons: one to create a new module and one to load an existing form definition file. Below that, the Form.io builder is shown.

Click the New... button to start.

The options for creating a new module appear:

• Language: Create a Python or Matlab module.
• Mode: Create a web app or a reusable composed component.
• Workspace folder: The folder that needs to be on the path to find your module.
• Module name / Package name: The fully quailified name of the module to create.

When Mode is App:

• Window title: The title to show on the Pywebview / uihtml window.
• Navbar title: The title to show on the navigation bar.
• Navbar subtitle: The subtitle to shown on the navigation bar.
• Navbar logo: The logo to shown on the navigation bar.
• Enable change detection: When selected, shows an indicator badge whenever the user makes changes to the form.

When Mode is Composed component:

• Class name: the name of the composed component class.

Specify the Workspace folder and Module name.

Click Create code to generate the module code.

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.

In general the edit pane for each component has several tabs with settings on the left and a preview on the right. Not each component has all tabs, and the contents of the tabs also varies depending on the properties of the component type. See the Components section and its subsections for more details on specific component types.

The tabs that may be present are:

• Display: generic options such as label, description, visibility, etc.
• Data: settings regarding the value of the component, such as default value, multiple values, input masks, etc.
• Validation: frontend input validation, such as required, min, max, etc.
• API: the field Property Name contains the component key. It is automatically generated based on the label, but can be changed here.
• Conditional: settings to conditionally show or hide the component.
• Logic: settings to update the component properties based on triggered events.

Click the Save button to save the updated form.

For Python web apps, a preview can be opened in a new Python process.

Next steps

Please consider reading the following documentation pages to further develop your application.

• Custom initialization for components in the form

• Handling events

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 gui_event 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 dict/struct with key 'values', which must contain an list/array of dicts/structs 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 dict/struct 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 Address component

Users can select an address.

The address form component is a component that looks up adresses using data from an external provider. Currently, we only support the use of OpenStreetMap Nominatim as the provider.

Note: due to restrictions in MATLABs uihtml, it is not possible to connect to the provider when running the app locally.

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 ColorPicker component

Users can select a colour.

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 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 Slider component

Users can drag a slider 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 Toggle component

Users can select a two state value 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 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.

Note that it is possible to add conditional contents with string interpolation.

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

Sanitize options

The HTML code rendered in this component is sanitized to remove possible malicious code from being rendered/executed in the browser. This is expecially important when user input may be rendered. However, in some cases it may be necessary to configure the sanitation settings when rendering HTML from a trusted source (e.g. generated in the back-end) and be able to use tags and attributes that would normally be deemed unsafe.

To change the sanitize options, set sanitizeOptions to a nested dict/struct using any of the following fields.

For example, to allow rendering SVG, enable the svg profile:

html.sanitizeOptions = {"USE_PROFILES": {"svg": True}}

html.sanitizeOptions = struct("USE_PROFILES", struct("svg", true));

For more information, see Can I configure DOMPurify?.

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.

Note that it is possible to add conditional contents with string interpolation.

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

Showing an image example

Images can be shown in the form by creating an HtmlElement and using its setLocalImage method to point to the image that should be shown. For portability it is best to use a relative file name. In this example the image file is next to the file in which the path to the image is set.

image_logo = component.HtmlElement("logo")
image_logo.setLocalImage(
    os.path.join(os.path.dirname(__file__), "logo.png"),
    alt="Company logo",
    scale_to_parent_width=True,
)

imageLogo = component.HtmlElement("logo");
imageLogo.setLocalImage( ...
    fullfile(fileparts(mfilename("fullpath")), "logo.jpg"), ...
    "Company logo", ...
    "ScaleToParentWidth", true);

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 dict/struct for specifying suffixes, custom styling etc.. Both are described in more detail below.

Updating

Update the data of your table in gui_event using:

setSubmissionData(payload, key, data)

payload = setSubmissionData(payload, key, data);

where data can be a list of lists with numbers and strings in Python, and a numeric, cell or string array in MATLAB. The table content can be customized by adding the Customization name-value pair, like so:

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

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

customization must be a dict/struct 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 dict/struct, 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 dict/struct. 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:

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"

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

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 components that are set per column. Users can add, remove and edit rows. The DataGrid can also be filled from the back-end by setting values for all table cells in the submission data. Use the setContent method to automatically create the components for the DataGrid without filling them with data. Note that you can use Layout components to create more elaborate cell contents.

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"]
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)

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);

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 list of dicts (Python) or a struct array (MATLAB), with fields equal to the keys of the DataGrid's components.

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}
]

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);

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[1].defaultValue = 18
users.components[2].defaultValue = True

users.disableAddingRemovingRows = false;
users.components{2}.defaultValue = 18;
users.components{3}.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 a list 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}
]

% 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});

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 Python, this returns a pandas DataFrame. MATLAB returns a table. 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, new_rows = component.DataTables.getNewRows(payload, key, 
    parent=parent_key, nested_form=nested_form_key)

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

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 gui_event, 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 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.

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.

The syntax is:

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

payload = 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', None, 'text-muted']
)

dt.setColumns(...
    {'#', 'Name', 'Age', 'Present'}, ...
    {'id', 'name', 'age', 'present'}, ...
    'className', {'text-muted', 'text-muted', missing, '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", "", "hidden"])

dt.setEditorFields("type", ["hidden", "readonly", missing(), "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=[
        None,
        None,
        None, {
            'function': 'getBooleanRenderer',
            'arguments': ['Yes', 'No']
        }
    ]
)

dt.setColumns(...
    {'#', 'Name', 'Age', 'Present'}, {'id', 'name', 'age', 'present'}, ...
    'render', struct(...
    'function', {missing, missing, missing, 'getBooleanRenderer'}, ...
    'arguments', {missing, missing, missing, {'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=[{}, {}, {}, {"Yes": True, "No": False}])

dt.setEditorFields("type", ["hidden", "text", "text", "select"], ...
    "options", {[], [], [], struct("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. Note that you can use Layout components to create more elaborate row contents. 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 list of dicts / struct array where each item in the list/array contains the values of a row in the EditGrid. The dicts / structs contain the values of the components in the rows. The getSubmissionData and setSubmissionData utilities work for an entire EditGrid and expect/return a list/array 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 list/array that was returned by getSubmissionData. When sending values back into the front-end, the complete list/array 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 Python and MATLAB code.

# 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"

% 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";

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.

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

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

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 gui_upload 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 Python and MATLAB versions of Simian GUI differ significantly, so they are documented in separate sections. It is possible to combine multiple types of plots in the same figure, which is demonstrated with an example.

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, instead of setting the width and height, you can reduce the width of the component by placing it in a Columns component. The heigth can be managed using the aspectRatio property. Example:

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");
    plotObj.aspectRatio = 2;
    cols                = component.Columns("plot_cols", form);
    cols.setContent({plotObj, {}}, [4, 8])    
end

Background image

Images can be used as background of a Plotly component by adding the image resource, and making the axes overlap with the image.

The image must be specified by encoding the image file with the utils.encodeImage utility function. The settings below put the image in the top-right quadrant of the plot axes, with the bottom-left of the image at location (0, 0). Refer to the Plotly Image documentation for more options.

image_setup = {
    "source": encoded_image,
    "xref": "x",
    "yref": "y",
    "xanchor": "left",
    "yanchor": "bottom",
    "x": 0,
    "y": 0,
    "sizex": image_width,
    "sizey": image_height,
    "layer": "below",
}

To make the Plotly axes neatly overlay the background image, the axes ranges must match the sizes of image_setup, and the margins must be set to zero. Setting "showgrid" to false removes the grid from the plot.

margin_setup = {"l": 0, "r": 0, "t": 0, "b": 0}
xaxis_setup = {"range": [0, image_width], "showgrid": False}
yaxis_setup = {"range": [0, image_height], "scaleanchor": "x", "showgrid": False}

If you need to plot data over the background, replace the image width and height values with your data ranges. Combined with the above settings the image will be shown smaller, but without distortions in the plot axes.

In Python the Plotly API methods can be used to apply the above settings to the Figure object.

plot_obj.figure.update_layout(images=[image_setup], margin=margin_setup)
plot_obj.figure.update_xaxes(**xaxis_setup)
plot_obj.figure.update_yaxes(**yaxis_setup)

In MATLAB the above settings must be converted to a struct and put in the layout property of the utils.Plotly object that is in the component's defaultValue.

plotObj.defaultValue.layout.images = {image_struct}
plotObj.defaultValue.layout.margin = margin_struct
plotObj.defaultValue.layout.xaxis = xaxis_struct
plotObj.defaultValue.layout.yaxis = yaxis_struct

Drawing shapes

User's can draw shapes in the Plotly axes when the modeBarButtonsToAdd option of the config property is set with (a subset of) the following options: drawline, drawclosedpath, drawopenpath, drawcircle, drawrect, and eraseshape.

plot_obj.defaultValue["config"]["modeBarButtonsToAdd"] = ["drawline", ...]

plotObj.defaultValue.config.modeBarButtonsToAdd = ["drawline", ...]

Note that you can modify the look of the drawn lines by changing the layout's newshape's properties:

• fillcolor: {null}, or a (named) color string.
• fillrule: {"evenodd" (with cut-outs)}, or "nonzero" (everything filled).
• opacity: {null}, or a number between zero and one. Applies to line and fill.
• line:
  • color: {"black"}, or a (named) color string.
  • dash: {"solid"}, or one of ("solid", "dot", "dash", "longdash", "dashdot", "longdashdot").
  • width: {2}, or a number greater or equal to zero. Unit is pixels.

Get shapes in backend

The properties of the drawn shapes can be extracted in the backend by using the utils.Plotly.getShapes method. It will return a list of dicts / cell array of structs with the following contents:

Simple shapes like a "type" line, rect (rectangle), and circle contain their type, and the x and y coordinates of the bounding box of the shape:

{
    "type": "line",
    "x": [20, 30],
    "y": [15, 25]
}

A path polygon must contain the type, the coordinates of the vertices, and whether the path between the first and last point is to be closed with a line segment.

{
    "type": "path",
    "x": [20, 30, 25],
    "y": [15, 25, 30],
    "closed": true
}

When the line or fill properties are differing from the defaults, the above structures are extended with the above mentioned newshape's properties.

Add shapes in backend

With the utils.Plotly.addShape method shapes defined as one of the above structures can be added to a Plotly axes from the backend via the submission data.

The advancedPaths option (default false) allows for adding multi element and complex shapes using SVG Paths definitions. The SVG path definition are deconstructed into separate commands and coordinates fields in the input structure to ease dynamic definition.

The example inputs below create one shape made up of a triangle and a parabolic segment. The first command specifies to start at ("M") the first coordinate and draw lines ("L") to the other vertices. The second command draws a Quadratic Bézier curve ("Q") between the start point ("M") and the end coordinate that does not have its own command (denoted with a comma). The second coordinate controls the curvature of the curve.

{
    type="path",
    command=[["M", "L", "L"], ["M", "Q", ","]],
    x=[[1, 1, 4], [0, 1, 2]],
    y=[[1, 3, 1], [2, 0, 2]],
    closed=[True, True],
}

struct( ...
    type="path", ...
    command={{{"M", "L", "L"}, {"M", "Q", ","}}}, ...
    x={{[1, 1, 4], [0, 1, 2]}}, ...
    y={{[1, 3, 1], [2, 0, 2]}}, ...
    closed=[true, true])

This multi-element shape definition (with the fillrule default being "evenodd") creates the following image with part of the triangle being cut-out by the parabola.

Remove shapes in backend

The shape objects are stored in the shapes field of the layout property. To remove shapes in the backend:

• get the Plotly data using the getSubmissionData utility function,
• remove shape definitions from the list in the layout field's shapes field in the returned utils.Plotly object,
• and send the reduced list of shapes to the browser using the setSubmissionData utility function.

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. For examples of Simian web apps with Plotly components, refer to the simian.examples.ballthrower, simian.examples.plottypes, and simian.examples.workshop_example web apps.

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.

Properties

utils.Plotly

This utility class should be used in gui_event, not in gui_init. 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

Note that when putting the utils.Plotly object in the submission data, the settings in the figure property may override the settings in the other properties. When the figure property is set to None, the values in the other properties are used as-is.

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 gui_event 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:

MATLAB

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

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.

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;.

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 gui_download 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: list/array of paths to files to upload
• mimeTypes: list/array of MIME-types corresponding to the files to upload
• metaData: Metadata dict/struct
• payload: The payload dict/struct
• 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 list/array 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 gui_event code snippets below a simple dict/struct is written to a .json file in the session folder of the back-end and made available in the front-end.

# 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",
    file_names=[nice_name]
)

% 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);

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('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)

% 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);

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('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'

% 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";

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 dict/struct 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 dict/struct 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.

5. String templates

   JavaScript code used in string template evaluation blocks.

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.

Note: For more complex JavaScript, it may be convenient to provide some JavaScript functions for use in any of the above. This can be achieved by providing a Custom JavaScript file.

Validate

Most components are able to perform some validation of the values that are provided by the user of the app. The validation takes place in the browser window, before any submission data is sent to the backend. This makes the validation a very convenient method to give an early warning to the user that a provided value may be incorrect, without impacting performance of the application. However, for secure deployment of apps, it is required to also perform validation of user provided values in the backend before using them.

Validation can be configured using the Builder. Each component has a Validation tab that shows the available options.

To add validation programmatically, create a Validate object for the component and set its properties to define the validation criteria.

Properties

Example

The following example shows a form with a Password that has a validation on the minimum number of characters in the input.

The initialization code is as follows:

passwd = component.Password("passwd", form)
passwd.label = "Password"

validate = component_properties.Validate(passwd)
validate.required = True
validate.minLength = 8
validate.customMessage = "Password shall have at least 8 characters."

ok = component.Button("ok", form)
ok.label = "Ok"
ok.disableOnInvalid = True

passwd = component.Password("passwd", form);
passwd.label = "Password";

validate = componentProperties.Validate(passwd);
validate.required = true;
validate.minLength = 8;
validate.customMessage = "Password shall have at least 8 characters.";

ok = component.Button("ok", form);
ok.label = "Ok";
ok.disableOnInvalid = true;

Conditional

Some components are only useful when certain criteria are met, for instance because the value is only used when a particular option is selected. These components can be made conditional, such that they only appear on screen when they are needed.

To make a component conditional using the Builder, go to the Conditional tab of the component.

The options on that tab are also available when creating components programmatically. Use the Conditional class 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 (JavaScript in the Advanced Conditions panel) which evaluates a Javascript expression to determine whether the component should be shown. When conditional and customConditional are both specified, the latter has precedence.

Examples

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('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

% 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;

The next example show the customConditional property. For example, if you wish to show a button only when a specific checkbox is checked and a number that is entered is greater 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:

Logic

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

Logic triggers and actions can also be specified in the Builder, on the Logic tab of the component.

Note that Logic objects and the corresponding triggers are checked on any change in the web app. In larger web apps having many Logic objects may cause performance to decrease.

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 dict/struct must contain a field simple. It must contain a dict/struct 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

• javascript: When the trigger type is 'javascript', the trigger dict/struct 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 dict/struct 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 list/cell array containing one or more action dicts/structs. 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 dict/struct must contain a field property. It must contain a dict/struct with fields:

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

  The action dict/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 dict/struct 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 dict/struct 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 component_properties package/module contains some utility functions to make it easier to add Logic to your components.

• createTrigger: 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:

  Trigger type	Trigger value	Remark
  event	"EventName"	Triggers when the event EventName occurs.
  trigger	trigger definition dictionary	For reusing an existing trigger.

  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.

  Trigger type	Trigger value	Remark
  simple	{"key", value}
  javascript	"result = data.key == value"	javascript trigger syntax
  result	"data.key == value"	Shorter 'javascript' trigger.
  json	'{"==": [{"var": "data.key"}, value]}'	Uses JSON Logic syntax

• createDisableAction: 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.

• createLogic: 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.

• createDisableLogic: 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.

These settings can also be specified in the Custom Errors panel of the Validation tab in the Builder.

The Error class 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, there are several values that you can use to include the component's label.

• {{ field }}
• {{ min }}
• {{ max }}
• {{ length }}
• {{ pattern }}
• {{ minDate }}
• {{ maxDate }}
• {{ minYear }}
• {{ maxYear }}
• {{ regex }}

The following example shows two custom error messages shown when a required component was left empty and when it does not have the minimum length:

The initialization code is as follows:

passwd = component.Password("passwd", form)
passwd.label = "Password"

validate = component_properties.Validate(passwd)
validate.required = True
validate.minLength = 8

error = component_properties.Error(passwd)
error.required = "Please provide a password."
error.minLength = "Password shall have at least {{ length }} characters."

ok = component.Button("ok", form)
ok.label = "Ok"
ok.disableOnInvalid = True

passwd = component.Password("passwd", form);
passwd.label = "Password";

validate = component_properties.Validate(passwd);
validate.required = true;
validate.minLength = 8;

error = component_properties.Error(passwd);
error.required = "Please provide a password.";
error.minLength = "Password shall have at least {{ length }} characters.";

ok = component.Button("ok", form);
ok.label = "Ok";
ok.disableOnInvalid = true;

Composed components

With the term composed component we mean a component that is composed of multiple other components. The main purpose of composed components is to provide a standardized method for reusing code and integrating it with the Simian Form Builder.

Currently, Simian includes one predefined composed component: StatusIndicator

Generic component

The generic class component.Composed can be used to add a reusable group of components as if they are one component. In its className property, the fully qualified name of a class can be provided.

If the class exists, its contructor will be called with a single input argument: the instance of component.Composed.

Example

shared/components.py:

class Name:
    def __init__(self, parent: component.Composed):
        # Add components to parent.
        first = component.TextField("first", parent)
        first.label = "First name"

        last = component.TextField("last", parent)
        last.label = "Last name"

app.py:

# In gui_init:
# - Initialize the container with key "name" and add it to the form.
my_name = component.Composed("name", form)

# - Set the className property to call the constructor of shared.components.Name
#   with the object as input argument.
my_name.className = "shared.components.Name"

# In gui_event:
# - Get the value of the composed component.
name, _ = utils.getSubmissionData(payload, "name")
# {'first': 'John', 'last': 'Smith'}

+shared/+components/Name.m:

classdef Name < handle
    methods
        function obj = Name(parent)
            import simian.gui_v3_0_1.*;

            % Add components to parent.
            first       = component.TextField("first", parent);
            first.label = "First name";

            last        = component.TextField("last", parent);
            last.label  = "Last name";
        end
    end
end

+app/guiInit.m:

% Initialize the container with key "name" and add it to the form.
myName = component.Composed("name", form);

# Set the className property to call the constructor of shared.components.Name
# with the object as input argument.
myName.className = "shared.components.Name";

+app/guiEvent.m:

% Get the value of the composed component.
name = utils.getSubmissionData(payload, "name");
% struct("first", "John", "last", "Smith")

When the specified className cannot be resolved, or when calling the constructor results in an error, a placeholder is shown instead.

Parametrization

A reusable component that can be used as-is, is nice to have, but when a component can be parametrized it may be used in different contexts. Instead of hardcoding the labels of the text fields in the contructor of the reusable component, a component initializer can be used to make the labels configurable.

shared/components.py

class Name:
    def __init__(self, parent: component.Composed):
        # Add components to parent.
        first = component.TextField("first", parent)
        first.label = "First name"

        last = component.TextField("last", parent)
        last.label = "Last name"

    @staticmethod
    def create(key, parent, first_label=None, last_label=None):
        # Create the composed component.
        composed = component.Composed(key, parent)
        composed.className = "shared.components.Name"

        Name._initialize_component(composed, first_label, last_label)

        return composed

    @staticmethod
    def get_initializer(first_label=None, last_label=None):
        # Return the initializer with the enclosed parameters.
        return lambda comp: Name._initialize_component(comp, first_label, last_label)

    @staticmethod
    def _initialize_component(comp: component.Composed, first_label, last_label):
        # Set the labels on the text fields.
        [first, last] = comp.components

        if first_label:
            first.label = first_label

        if last_label:
            last.label = last_label

app.py:

# In gui_init:
# - Create two Name components. One with default labels and one customized.
Name.create("name1", form)
Name.create("name2", form, first_label="Forename", last_label="Surname")

+shared/+components/Name.m:

classdef Name < handle
    methods
        function obj = Name(parent)
            import simian.gui_v3_0_1.*;

            % Add components to parent.
            first = component.TextField("first", parent);
            first.label = "First name";

            last = component.TextField("last", parent);
            last.label = "Last name";
        end
    end

    methods (Static)
        function composed = create(key, parent, options)
            arguments
                key
                parent
                options.FirstLabel  (1, 1) string = missing
                options.LastLabel   (1, 1) string = missing
            end

            import simian.gui_v3_0_1.*;
            import shared.components.*;

            % Create the composed component.
            composed            = component.Composed(key, parent);
            composed.className  = "shared.components.Name";

            Name.initializeComponent(composed, options.FirstLabel, options.LastLabel);
        end

        function initializer = getInitializer(options)
            arguments
                options.FirstLabel  (1, 1) string = missing
                options.LastLabel   (1, 1) string = missing
            end

            import shared.components.*;

            % Return the initializer with the enclosed parameters.
            initializer = @(comp) Name.initializeComponent(comp, options.FirstLabel, options.LastLabel);
        end
    end

    methods (Static, Hidden)
        function initializeComponent(comp, firstLabel, lastLabel)
            % Set the labels on the text fields.
            [first, last] = comp.components{:};

            if ~ismissing(firstLabel)
                first.label = firstLabel;
            end

            if ~ismissing(lastLabel)
                last.label  = lastLabel;
            end
        end
    end
end

+app/guiInit.m:

% Create two Name components. One with default labels and one customized.
Name.create("name1", form);
Name.create("name2", form, FirstLabel="Forename", LastLabel="Surname");

Builder

Composed components can also be added in the Simian Builder. The component type can be found in the miscellaneous category.

Just like any other component it can be dragged into the form. The settings allow to specify the Class of the composed component and the Display height for the placeholder. The preview will always show the placeholder, since the Builder is unaware of the component's implementation.

To set parameters, Form.componentInitializer can used to setup the initialization before creating the form.

Form.componentInitializer(
    myComposedComponent=Name.get_initializer("Forename", "Surname")
)

Form.componentInitializer(...
    myComposedComponent=Name.getInitializer("Forename", "Surname"));

PropertyEditor

The PropertyEditor is a composed component, consisting of nested DataGrids that allow for showing and editing scalar and 1D arrays of text, numeric, boolean, and select values. Subclasses of this component can add support for additional data types.

Note that it is recommended to use only one or a few PropertyEditors in your app, as too many PropertyEditors may slow your app down.

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

Methods

Supported values

The PropertyEditor supports scalar and one dimensional array values of the following data types. The PropertyEditor dynamically adds rows with the listed Components to show the property values in.

• text: values are shown in a TextField component.
• numeric: values are shown in a Number component.
• boolean: values are shown in a Checkbox component.
• select: values are shown in a Select component.

Properties must be specified as a list of dicts / cell array of structs with per property the following (mandatory) settings:

• datatype Mandatory, data type of the property that is shown.
• label: Mandatory, label shown next to the values to inform the user on which property is shown.
• tooltip: {null}, tooltip to be added to the label of the property.
• required: {false}, whether the property must have a value.
• defaultValue: {null}, Value to be shown for the property.
• min: {null}, minimum value for numeric values.
• max: {null}, maximum value for numeric values.
• decimalLimit: {null}, maximum number of decimals allowed in numeric values.
• allowed: {null}, The items that can be selected in a select value.
• minLength: {1} Scalar, or minimum array length of 0 or more.
• maxLength: {1} Scalar, or maximum array length of 0 or more.

The PropertyEditor shown above can be created with the following settings. It allows for specifying between 1 and 5 throw attempt speeds and whether to include drag and/or wind in the simulation.

[
    {
        "datatype": "numeric",
        "label": "Throw speed [m/s]",
        "defaultValue": [12.51, 3.8, 5.41],
        "required": true,
        "minLength": 1,
        "maxLength": 5,
        "decimalLimit": 2
    },
    {
        "datatype": "select",
        "label": "Options",
        "allowed": ["None", "Drag", "Drag and wind"],
        "defaultValue": "Drag and wind",
        "required": true
    }
]

Usage

The following subsections describe how you can add the PropertyEditor to your web app and which options you can select, how to fill it and how to get the user selected values from the submission data.

Adding to web app

In the guiInit function of your app add a Composed component and set the className property to the full PropertyEditor class name.

Use the static getInitializer method to configure the PropertyEditor:

• defaultValue: {null}, set the default value of the PropertyEditor by using the output of the static prepareValues method.
• allowEditing: {true}, set this optional input to false to create a property viewer.
• columnLabel: {"Properties"}, specify a label to show at the top of the outer DataGrid.
• addAnother: {"Add value"}, optional input that sets the label on the nested DataGrid's button that adds new rows.
• hideWhenEmpty: {true}, The PropertyEditor is hidden when empty. Set this optional input to false to ensure it is always shown.

Form.componentInitializer(
    editor=PropertyEditor.get_initializer(
        default_value=PropertyEditor.prepare_values([...]),
        column_label="Parameters",
    )
)

editor = composed_component.PropertyEditor("editor", form_obj)
editor.className = "simian.gui.composed_component.PropertyEditor"

Form.componentInitializer(
    editor=PropertyEditor.getInitializer(
        defaultValue=PropertyEditor.prepareValues({}),
        columnLabel="Parameters",
    )
)

editor = composedComponent.PropertyEditor("editor", formObj)
editor.className = "simian.gui.composedComponent.PropertyEditor"

Filling with properties

The PropertyEditor can be filled with default values during initialization, as shown above, and in the callback of an event. To do this use the static prepareValues method and put the output in the submission data with the setSubmissionData utility function.

The prepareValues method accepts the properties' settings and values as separate inputs, making it easier to reuse static property settings. It also ensures that the property settings are divided over the expected locations in the PropertyEditor rows.

prep_values = PropertyEditor.prepare_values(
    prop_meta=[{"datatype": "numeric", "label": "Rotation [deg]"}],
    prop_values=[45],
)
utils.setSubmissionData(payload, key="editor", data=prep_values)

Getting property values

The property values selected by the user can be extracted from the full PropertyEditor submission data by using the static getValues method. The submission data also contains the property settings, which cannot be modified by the user.

table_values, _ = utils.getSubmissionData(payload, key="editor")
value_list = PropertyEditor.get_values(table_values)

Extending the PropertyEditor

When the PropertyEditor does not support all data types you need, you can extend it to add the support.

• create a subclass of the PropertyEditor,
• Extend the mapping of the data types and the unique keys of the corresponding components.
  • In Python: extend the class property: DICT_TYPE_CONTROL
  • In MATLAB: implement the Constant property:SUB_STRUCT_TYPE_CONTROL
• In MATLAB: implement static getValues and prepareValues methods that send their inputs and the class' SUB_STRUCT_TYPE_CONTROL struct as extra input argument to the corresponding Helper method.
• create component objects for the new data types and add them with the addDatatypeUtil. Note that you cannot use initializer functions for these component.
• Note that any validation (including required) must be implemented as custom validation. Meta data is available as row.meta.

In the guiInit function of your app set the className of the Composed component to the full name of your Editor class.

editor.className = "YourPropertyEditor"

StatusIndicator

The StatusIndicator is a composed component, consisting of a Container that contains an HtmlElement and a Hidden value. It can be used as a visual indication of the state of the data and can be managed on the back-end. The status indicator as follows, the color depends on the active state:

Initialization

To add a StatusIndicator programmatically, use its static method create, that takes the following input arguments:

Additional options can be given as named arguments:

From Json

The StatusIndicator can be added from a Json form definition as a generic Composed component, by specifying its fully qualified className:

{
    "label": "Status",
    "className": "simian.gui.composed_component.StatusIndicator",
    "displayHeight": 40,
    "hideLabel": true,
    "key": "my_status",
    "type": "customcomposed",
}

The component can be initialized using the static method get_initializer that takes the same optional input arguments as create.

Form.componentInitializer(
    my_status=composed_component.StatusIndicator.get_initializer(
        content="Hello, world!", defaultValue="success"
    )
)

form = Form(from_file=__file__)

Form.componentInitializer(...
    my_status=composedComponent.StatusIndicator.getInitializer(...
    content="Hello, world!", defaultValue="success"));

form = Form(FromFile="/path/to/my/form.json");

Updating

Update the status in your gui_event code using:

payload = composed_component.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 = composed_component.StatusIndicator.create("testStatus", form)
        
# Initialize using options:
testStatus = composed_component.StatusIndicator.create(
    "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")

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

% Initialize using options:
statuses = struct(...
    "value", {'notRun', 'running', 'success', 'failed'}, ...
    "theme", {'secondary', 'warning', 'success', 'danger'});

testStatus = composedComponent.StatusIndicator.create(...
    "testStatus", form, ...
    "Content", "Tests", ...
    "DefaultValue", "notRun", ...
    "Statuses", statuses);
    
% Update the status:
payload = composedComponent.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(os.path.join(image_folder, "myCustomLogo.jpg")),
    "title": "Example title",
    "subtitle": "<small>v1.0</small>"
}

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

Note that the image file used for the logo cannot be specified as a file name, as the image file will not be available in the browser. Instead the information in the image file must be encoded with the encodeImage utility function and put in the form. The image file must be stored near the guiInit code and its absolute path must be used as input for encodeImage.

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;

Reusing component definitions

When you need to add (sets of) components to your form multiple times with small differences, it is better to use a (configurable) definition that can be reused, instead of copy-pasting the definitions and applying the differences in the copies.

Note that reuse of components can be within an app, but also between (similar) apps. When reusing functionality between apps it should be clearly documented what the reused functionality does, how it should be used and if the app using it must provide information to the reused code.

A couple of important things to note on components:

• Component keys are easiest to use when they are unique. When you try to get the value of a component with a non-unique key, you may get the value of another component with the same key. A nested form or parent key can be used with the key to get the value of a specific component, when this creates a unique combination
• All components must have a parent component and their ultimate ancestor must be the form object of the application. Components without a parent or without a connection to the form object will not be shown in the web app.

Using a function

Components can be added to the form or other components in other functions. These functions can be used multiple times in one app definition to add the same components (with some differences) to the app multiple times.

Use the intended parent component as input in the function, to immediately add the new component(s) to the form:

component.Number(key="number", parent=parent_component)

To ensure the values of the components can be found in the callback functions, you can do the following:

• Give the function a key prefix or suffix input to give the components a unique key.

  component.Number(key=prefix + "_number_" + suffix, parent=parent_component)

• Use the key of the parent as prefix or suffix

  component.Number(key=parent_component.key + "_number", parent=parent_component)

• Use a container as parent to give the components a unique key - parent-key combination.

You can add additional input arguments to the function to allow for creating the components with different settings.

An example of adding sets of components (with component key prefix) via a function is the _fill_column function in the Form definition example.

def add_number(parent_component) -> None:
    # Add a Number component with unique key to the given parent component.
    new_nr = component.Number(parent_component.key + "_number", parent_component)
    new_nr.label = "Input value"

Using a JSON form definition

Components can be added to a form or parent component from a JSON form definition definition. These JSON form definitions can be created with the Simian Builder.

def gui_init(meta_data: dict) -> dict:
    form = Form()
    root_container = component.Container("parent_component_key", form)
    root_container.addFromJson("path/to/components_definition.json")

Note that component keys are hardcoded in the JSON form definition and may thus be used multiple times. When you use a Container as parent component, you can use the key of the container to find the value of the component you need.

Reusing initialization functions

When your own web app itself is defined in a JSON form definition, you can use (configurable) Component initialization functions to ensure the components are added to one of the components in the JSON form definition.

In the following example the web app is created from a JSON form definition, and the components that are created in the initialize_action_with_config initialization function are added to the containers identified with the parent_component_key, and other_parent_key key.

def gui_init(meta_data: dict) -> dict:
    Form.componentInitializer(
        parent_component_key=initialize_function,
        other_parent_key=initialize_function,
    )

    # Fill the form with components, including a Container to add other components to.
    form = Form(from_file="path/to/components_definition.json")

    return {"form": form}


def gui_event(meta_data: dict, payload: dict) -> dict:
    # Get the value of the number component that is in the Container.
    value, _ = utils.getSubmissionData(payload, "number", parent="parent_component_key")
    value2, _ = utils.getSubmissionData(payload, "number", parent="other_parent_key")
    return payload


# Potentially in other module / package:
def initialize_function(container_component: Component)
    # Initialization function to execute on the container_component.
    some_number = component.Number("number", parent=container_component)

function payload = guiInit(metaData)
    Form.componentInitializer( ...
        parent_component_key=@initializeFunction, ...
        other_parent_key=@initializeFunction,
    )

    % Fill the form with components, including a Container to add other components to.
    payload.form = Form(FromFile="path/to/components_definition.json")
end

function payload = guiEvent(metaData, payload)
    % Get the value of the number component that is in the Container.
    value = utils.getSubmissionData(payload, "number", parent="parent_component_key")
    value2 = utils.getSubmissionData(payload, "number", parent="other_parent_key")
end

% Potentially in other package:
function payload = initializeFunction(containerComponent)
    % Initialization function to execute on the containerComponent.
    someNumber = component.Number("number", containerComponent)
end

Reusing components in the Builder

The methods described in the previous sections describe methods that reuse definitions by calling the reusable functionality in the Python or MATLAB code.

However, when building an app in the Simian Form Builder it is not possible to add the reusable code to the form, since the builder is unaware of any code that has been written.

For this purpose the component.Composed component has been introduced, which allows adding a reusable component to the form by means of drag-and-drop.

Form refresh

In order to aid rapid iterations during development, the Refresh button has been introduced. Clicking the Refresh button performs all the actions associated with closing the window and opening a new one, except for closing the actual window. Modules are reloaded before re-initializing the form.

The Refresh button is aimed at developers and can be enabled when running locally. There is no equivalent for the deployed application that runs in a web browser.

Python

In Python the refresh button can be enabled by giving the show_refresh named argument to Uiformio:

Uiformio("namespace.app", show_refresh=True)

In order to detect the changes that were made to the app module file after starting Uiformio, importlib.reload is used to reload a number of modules.

1. Reload the module with the namespace (first input argument of Uiformio).
2. Find the folder of that module and reload all modules found there (or in its subfolders).
3. Call the gui_refresh function of the web app module, if it is implemented.

The gui_refresh method is intended for reloading additional modules only. Example:

def gui_refresh():
    importlib.reload(sys.modules["core.algorithm"])
    importlib.reload(sys.modules["shared.components"])

Matlab

In Matlab the refresh button can be enabled by giving the ShowRefresh named argument to Uiformio:

Uiformio("namespace.app", ShowRefresh=true);

In order to detect the changes that were made to the app module file after starting Uiformio, rehash is used to compare the timestamps for loaded functions against their timestamps on disk, and it clears loaded functions if the files on disk are newer. Since rehash applies to all known files and classes for folders on the search path that are not in matlabroot, there is no Matlab equivalent of gui_refresh.

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 gui_event function is called on the server. By implementing this function, user-defined functionality can be provided to the application.

Implementing gui_event

The gui_event function serves as a gateway for all events.

The event must be dispatched to other functions that actually provide the intended functionality for the events. In this section the calling syntax, dispatching techniques, and input and output arguments will be discussed, followed by a small example.

Options for triggering events when a component value is changed or loses focus are described in the Advanced features chapter.

Syntax

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

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

Register events explicitly

The recommended way to ensure the correct function is executed, is to explicitly register the event handler functions to the events in the gui_event function. The event must then be dispatched to execute the registered function.

In the examples below the static method Form.eventHandler is used to register the event "SayHello" to the say_hello/sayHello function. The dispatch function ensures that the function registered to the event is executed. Note that the eventHandler input arguments can be repeated to register multiple events.

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

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

Note that you can configure the behaviour of the registered event handler functions by adding inputs to a function that wraps the actual function.

def gui_event(meta_data: dict, payload: dict) -> dict:
    Form.eventHandler(
        SayHello=say_something("Hello"),
        SayBye=say_something("Bye"),
    )
    callback = utils.getEventFunction(meta_data, payload)
    return callback(meta_data, payload)


def say_something(word: str) -> Callable:
    def inner(meta_data: dict, payload: dict) -> dict:
        utils.setSubmissionData(payload, "display", word + ", world!")
        return payload
    return inner

function payload = guiEvent(metaData, payload)
    Form.eventHandler( ...
        'SayHello', say_something("Hello"), ...
        'SayBye', say_something("Bye") ...
        );
    payload = utils.dispatchEvent(metaData, payload);
end

function func = say_something(word)
    % Wrapper function to multiply app input value with a configurable factor.
    func = @(metaData, payload) inner(metaData, payload, word);
end

function payload = inner(metaData, payload, word)
    payload = simian.gui.utils.setSubmissionData(payload, "display", word + ", world!");
end

Dispatching events

Using the information in the payload input it is possible to programmatically route events to the correct function with if-else blocks.

Alternatively, you can let Simian dispatch the events to the intended function for you. This can be achieved by using the dispatchEvent or getEventFunction utility functions:

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

payload = utils.dispatchEvent(metaData, payload);

Simian will look for and execute the function that:

• is explicitly registered to the event,
• has the same full name (including packages and classes) as the event ("reflection"),
• or throw an error

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 further demonstrated in the example below.

Function arguments

meta_data:

Meta data describing the client session.

Dict/struct 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
• mode: local or deployed
• client_data:
  • authenticated_user: for deployed apps, the portal provides the logged on user info
    • user_displayname: user name for printing (e.g. "John Smith")
    • username: unique identifier used by the authentication protocol

payload:

When entering the function, this contains the event data containing all values as provided by the client. It is a dict/struct 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: dict/struct with fields:
  • data: dict/struct 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. dict/struct with fields:
      • data: dict/struct 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 dict/struct with fields:
  • type: message type, see Alerts
  • message: string

In the gui_event 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.

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.

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:

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

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

Example

The following example shows 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 gui_event functions handle these events, the first one using conditional logic and the second one using the dispatchEvent or getEventFunction functions using event-function name reflection:

Note that the ModelS class contains a getResult method and the ModelX class a getValue method. For reflection, the event name must contain the class name!

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)

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

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 list/array. However, this is transformed into a list of dicts/struct array before being placed in the submission data.

These functions should not be used during initialization (gui_init), 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': Python / MATLAB data types. When there is a difference.
• '-': no conversion.
• '(opt.)": optional conversion output type.
• 'table-like': DataFrame, list of dicts, dict with lists, list of lists / table, struct array, 2D-matrix

Syntax

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

[data, isFound] = utils.getSubmissionData(...
    payload, key, "NestedForm", nestedForm, "Parent", parent);
[payload, newData] = utils.setSubmissionData(...
    payload, key, data, "NestedForm", nestedForm, "Parent", 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.

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]

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

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 gui_event 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(meta_data, name, data)
data, is_found = utils.getCache(meta_data, name)

utils.setCache(metaData, name, data)
[data, isFound] = utils.getCache(metaData, 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 Python locally, the cached information is stored in a dictionary object in the Python session. When running an application in Matlab locally, the cache persistently stores the data in the workspace of the Matlab session.

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.

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.

Error Handling

When an uncaught error occurs during the execution of gui_event, Simian GUI automatically shows an alert message to the user. The user gets the option to reload or close the app. In local mode, the error message including stack trace can be found in the console / 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 list of dictionaries (Python) or a cell array of structs (MATLAB) 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");

gui_upload

The gui_upload function can be used to upload content to the form. It is triggered instead of gui_event 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 gui_event 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 gui_upload function is similar to that of gui_event as shown in the example below. It shows the initialization code of a button setup for uploading an Excel file. The gui_upload 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.

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

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

gui_download

The gui_download 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 gui_init, you can call myButton.setEvent("downloadStart") to set this event for a specific button.
2. Application-specific function gui_download 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 gui_download.
4. The user selects the location to save the file.

The gui_download function should assign the download field of the payload. The download field is a dict/struct 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 gui_download:

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

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

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

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

sessionFolder = utils.getSessionFolder(metaData, "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 gui_close.

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).