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).
Limitation: When nested forms are used, all controls should be added to the nested forms. Adding controls to the main form may cause errors when events are processed. In a future release having nested forms and controls in the main form will be supported.
Form and Form
Simian GUI has two Form classes:
Form
: This is the application form, the top level of the user interface.component.Form
: This is a nested form, which is used as a component in the application form.
Although they both refer to the same type of form eventually, the properties and data associated with both classes are different.
Initialization
A nested form can be added to the application form in guiInit
in a similar fashion as any other component.
nestedForm = component.Form(nestedFormKey, formObj)
However, the recommended method to add nested forms is addNestedForms
:
formObj.addNestedForms(formKeys, createFcns, inputs)
where
formObj
is theForm
object.formKeys
is an array/list of keys, one for each of the nested forms to create.createFcns
is an array of function handles (MATLAB) or a list of function names including namespace (Python). Each of these is called to initialize a nested form. The input to each of them is the nested form object and optionally, theinputs
provided.inputs
is a cell array (MATLAB) or a list of inputs (Python) to send to thecreateFcns
. This lets you call the samecreateFcn
multiple times, but with different parameters.
The first nested form will be visible on initialization, while the others are made invisible. The benefits of using this method are:
- Manages switching behaviour (hiding one nested form and showing another).
- Less boilerplate code.
An example of how it can be used is given below.
formDefs = {
% Key Create function Inputs
"mainForm" @guiLibrary.createMain {}
"inputForm" @guiLibrary.createInputPhase {}
"swapExemptionForm" @guiLibrary.createSwapExclusion {}
"createPhaseAsset" @guiLibrary.createCreatePhase {"Asset"}
"createPhaseLiability" @guiLibrary.createCreatePhase {"Liability"}
"testPhaseAsset" @guiLibrary.createTestPhase {"Asset"}
"testPhaseLiability" @guiLibrary.createTestPhase {"Liability"}
};
appForm.addNestedForms([formDefs{:, 1}], formDefs(:, 2), formDefs(:, 3));
form_defs = [
# Key Create function Inputs
["mainForm", guiLibrary.createMain, []],
["inputForm", guiLibrary.createInputPhase, []],
["swapExemptionForm", guiLibrary.createSwapExclusion, []],
["createPhaseAsset", guiLibrary.createCreatePhase, ["Asset"]],
["createPhaseLiability", guiLibrary.createCreatePhase, ["Liability"]],
["testPhaseAsset", guiLibrary.createTestPhase, ["Asset"]],
["testPhaseLiability", guiLibrary.createTestPhase, ["Liability"]],
]
appForm.addNestedForms(*zip(*form_defs))
This creates seven nested forms, the first of which will be visible after initializing the application.
Switching Forms
For forms that have been added to the application using addNestedForms
it is possible to switch between the forms using switchForms
in guiEvent
.
After event handling has completed, the selected form (identified by its key) will be displayed. Other nested forms will be hidden.
payload = utils.switchForms(payload, "inputForm");
utils.switchForms(payload, "inputForm")
The key of the currently visible form can be found as follows (with "currentFormKey"
always the same):
currentFormKey = utils.getSubmissionData(payload, "currentFormKey");
current_form_key = utils.getSubmissionData(payload, "currentFormKey")
You can check if a given form is the nested form currently shown by using:
isShown = utils.isCurrentForm(payload, formKey)