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