Block: ControlPanel

A ControlPanel block for configuring a panel of elements to be displayed in the user interface.
Tags:

Overview

A ControlPanel block is used for configuring a control panel that can display a set of elements. Examples of input control elements include Slider, TextInput, NumberInput, Dropdown, and so forth. Examples of elements that are not inputs include Text and Table. In addition, a control panel can also include Button an SubmitButton elements.

The elements in a control panel can either be laid out using the default layout scheme. This scheme places elements vertically, from top to bottom. Alternatively, the layout property allows a custom layout to be configured.

Typically, a Model subscribes to a ControlPanel to get the inputs it requires. When the value of control panel is submitted, it then triggers the model to execute. The value of the control panel can be submitted in two ways.

  • If there is no SubmitButton present in the control panel, then submission occurs each time any change is made to any input control.
  • If there is a SubmitButton present, then submission occurs only when the submit button is clicked by the user.

Example

Below is an example configuration.

kind: Solution
version: v0
router:
  kind: Router
  routes:
    - frame: home-frame
frames:
  home-frame:
    kind: Frame
    contents:
      my-control-panel:
        kind: ControlPanel
        card: false # optional
        layout: # optional
          kind: GridLayout
          widths: [12px, 1fr, 1fr, 12px]
          widthGap: 12px
          heights: [12px, auto, auto, 12px]
          areas:
            - ["", "", "", ""]
            - ["", my-slider, my-slider, ""]
            - ["", my-submit-button, my-cancel-button, ""]
            - ["", "", "", ""]
        controls:
          my-slider:
            kind: Slider
            label: My slider
            value: 10
            min: 3
            max: 30
            precision: 2
          my-submit-button:
            kind: SubmitButton
            text: OK
          my-cancel-button:
            kind: Button
            text: Cancel

ControlPanelConfig

A ControlPanel allows users to change alter values and see textual results

Name Type Required Description
kind "ControlPanel" Yes
controls Dictionary<string, ControlConfig> Yes
layout LayoutConfig No
card boolean No
subscribe List<ControlPanelSubscribe> No A list of objects for subscribing the ControlPanel block to other blocks.

ControlConfig

TextControlConfig

Name Type Required Description
kind "Text" Yes
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
text string Yes A string, the text.
type TextType No A constant specifying the type of text. Valid options are display-1 to display-4, h1 to h6, and lead.
color ThemeColor No A constant specifying the theme colour of the text. Valid options are primary, secondary, success, danger, warning, info, light, dark, and link. The default is primary.
align "left" | "right" | "center" | "justify" No A constant specifying the text alignment. Valid options are left, right, center, and justify. The default is left.
weight "normal" | "light" | "bold" | "italic" No A constant specifying the text weight. Valid options are bold, italic, light, and normal. The default in normal.
margin boolean No A boolean to set whether a margin is added to the text.
TextType
  • "lead"
  • "h1"
  • "h2"
  • "h3"
  • "h4"
  • "h5"
  • "h6"
  • "display-1"
  • "display-2"
  • "display-3"
  • "display-4"

SliderControlConfig

Name Type Required Description
kind "Slider" Yes
value number Yes
min number Yes
max number Yes
precision integer Yes
label string No
unit string No
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
infoButton boolean No A boolean to set whether an information button is generated. The button has an ‘info’ icon and is placed to the right of the label. The default is false.

NumberInputConfig

Name Type Required Description
kind "NumberInput" Yes NumberInput is used to input a number
label string No The label of the number input
value number No Optionally define the value of the number input
unit string No Optionally show a unit behind the number input
placeholder string No Optionally display a placeholder when the value is empty
min number No Optionally set the lower bound of the number
max number No Optionally set the upper bound of the number
step number No A float defining the step size that the value must adhere to.
Valid values are defined by moving in discrete steps from the basis, possibly constrained by min and max if they are specified.
The basis is either min, or value, or the default value, depending on what is specified.
The default for step is undefined, which means that any value is allowed (barring other constraints,
such as min
and max).
required boolean No A boolean to specify whether the control is required. Default is true.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
infoButton boolean No A boolean to set whether an information button is generated. The button has an ‘info’ icon and is placed to the right of the label. The default is false.

TableControlConfig

Name Type Required Description
kind "Table" Yes Table is used to display table of data
columns Dictionary<string, TableControlColumn> Yes Columns schema. Columns should be referenced by key when defining table items. Item object should specify value for each column
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value

TableControlColumn

Name Type Required Description
type "Text" | "Number" Yes
label string No

ButtonControlConfig

Name Type Required Description
kind "Button" Yes
routerLink string No
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
text string Yes
color ThemeColor No A constant that defines the theme colour to use for the button.
Possible options are primary, secondary, success, danger, warning, info, light, dark, and link. The default is primary.
href string No A string specifying a hyperlink. Clicking the hyperlink will navigate the browser to the link provided and away from the current solution. When no button colour is defined, the button background will have no colour, and the link text will have the primary colour.

ButtonSubmitControlConfig

Name Type Required Description
kind "SubmitButton" Yes
routerLink string No
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
text string Yes
color ThemeColor No A constant that defines the theme colour to use for the button.
Possible options are primary, secondary, success, danger, warning, info, light, dark, and link. The default is primary.
href string No A string specifying a hyperlink. Clicking the hyperlink will navigate the browser to the link provided and away from the current solution. When no button colour is defined, the button background will have no colour, and the link text will have the primary colour.
ThemeColor
  • "primary"
  • "secondary"
  • "success"
  • "danger"
  • "warning"
  • "info"
  • "light"
  • "dark"

TextAreaConfig

An object for configuring a text area in a control panel. A text area allows the user to enter multiple lines of text.

Name Type Required Description
kind "TextArea" Yes A constant, textArea.
label string No A string defining the label for the text area.
placeholder string No A string defining the text to be display in the text area when no value has been entered.
required boolean No A boolean to specify whether the control is required. Default is true.
infoButton boolean No A boolean to set whether an information button is generated. The button has an ‘info’ icon and is placed to the right of the label. The default is false.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value

FileControlConfig

An object for configuring a file input in a control panel. A file input allows the user to upload one or mutliple files to the platform.

Name Type Required Description
kind "File" Yes A constant, File.
basePath string No A string specifying a prefix to the file path when uploading. The path of the uploaded file will become {basePath}/{fileName} where fileName is the name of the uploaded file. The default is no basePath.
randomisePath boolean No A boolean to specify whether the file path should be randomised when uploading. The path of the uploaded file will become {basePath}/{RND}/{fileName} where {RND} is a random string. The default is true.
multiple boolean No A boolean to specify whether multiple files can be uploaded. Default is true.
placeholder string No An string specifying a placeholder when the value is empty.
maxFileSizeBytes integer No An integer specify the maximum allowed file size of new uploads in bytes. By default no limit is set.
acceptFileExtensions List<string> No A list of strings specifying file type extensions that may be uploaded in format ".txt". By default extensions are not limited.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
required boolean No A boolean to specify whether the control is required. Default is true.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
label string No A string specifying the label of the control input
infoButton boolean No A boolean to set whether an information button is generated. The button has an ‘info’ icon and is placed to the right of the label. The default is false.

DisableWhenConfig

HideWhenConfig

FalsyConfig
Name Type Required Description
kind "Falsy" Yes Check if the control value is falsy
control string Yes The control name to check the condition against its value
TruthyConfig
Name Type Required Description
kind "Truthy" Yes Check if the control value is truthy
control string Yes The control name to check the condition against its value
EqualConfig
Name Type Required Description
kind "Equal" Yes Check if the control value is equal to a specific value
control string Yes The control name to check the condition against its value
value number | string | boolean Yes The value to check the condition with
NotEqualConfig
Name Type Required Description
kind "NotEqual" Yes Check if the control value is not equal to the provided value
control string Yes The control name to check the condition against its value
value number | string | boolean Yes The value to check the condition against

SpinnerControlConfig

Indicate the loading state of a model.

Name Type Required Description
kind "Spinner" Yes A constant, Spinner.

TextInputConfig

Name Type Required Description
kind "TextInput" Yes TextInput is used to input text
label string No The label of the text input
value string No Optionally define the value of the text input
placeholder string No Optionally display a placeholder when the value is empty
required boolean No A boolean to specify whether the control is required. Default is true.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
infoButton boolean No A boolean to set whether an information button is generated. The button has an ‘info’ icon and is placed to the right of the label. The default is false.

EmailInputConfig

An object for configuring an email input in a control panel. An email input allows the user to enter an email address. The input value is automatically validated to ensure that it is a properly-formatted email address.

Name Type Required Description
kind "EmailInput" Yes A constant, emailInput.
label string No A string defining the label for the email input.
placeholder string No A string defining the text to be display in the email input when no value has been entered.
required boolean No A boolean to specify whether the control is required. Default is true.
infoButton boolean No A boolean to set whether an information button is generated. The button has an ‘info’ icon and is placed to the right of the label. The default is false.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value

ToggleControlConfig

Name Type Required Description
kind "Toggle" Yes Toggle is used to input true or false value
value boolean Yes Define the value of the toggle input
label string No The label of the toggle input
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
infoButton boolean No A boolean to set whether an information button is generated. The button has an ‘info’ icon and is placed to the right of the label. The default is false.
Name Type Required Description
kind "Dropdown" Yes Dropdown is used to select one option from multiple choices
label string No The label of the dropdown
choices List<DropdownChoice> Yes The choices of the dropdown
value boolean | string | number No Optionally define the value of the dropdown
placeholder string No Optionally display a placeholder when the value is empty
required boolean No A boolean to specify whether the control is required. Default is true.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
updateChoicesWhen UpdateChoicesWhen No Update the choices of this control based on another control’s value
infoButton boolean No A boolean to set whether an information button is generated. The button has an ‘info’ icon and is placed to the right of the label. The default is false.
allowUnselect boolean No

CheckboxConfig

Name Type Required Description
kind "Checkbox" Yes Checkbox is used to display a list of choices for the user to select from
label string No The label of the checkbox
choices List<CheckboxChoice> Yes The choices for the user to select from
required boolean No A boolean to specify whether the control is required. Default is true.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
infoButton boolean No A boolean to set whether an information button is generated. The button has an ‘info’ icon and is placed to the right of the label. The default is false.

CheckboxChoice

Name Type Required Description
label string Yes The label to be displayed in the dropdown
value string Yes The value to be used for selected choice

SelectionControlConfig

Name Type Required Description
kind "Select" Yes
choices List<ColorChoiceConfig> | List<ImageChoiceConfig> Yes A list of choices to select
value string No Optionally define the start value of the control
label string Yes Text displayed above the control
columns number No Optionally set the number of equal sized columns in which the selection items are displayed, default is 3
height number No Optionally define the height of the selection grid, default is 300
itemHeight number No Optionally set the heigh of each item in the grid, default is 50
required boolean No A boolean to specify whether the control is required. Default is true.
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
updateChoicesWhen UpdateChoicesWhen No Update the choices of this control based on another control’s value
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.

SelectColorControlConfig

Name Type Required Description
kind "SelectColor" Yes Select is used to select an item from a list of items
choices List<ColorChoiceConfig> Yes A list of choices to select
value string No Optionally define the start value of the control
label string No Text displayed above the control
numberOfColumns number No Optionally set the number of equal sized numberOfColumns in which the selection items are displayed, default is 3
height number No Optionally define the height of the selection grid, default is 300
itemHeight number No Optionally set the heigh of each item in the grid, default is 50
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
updateChoicesWhen UpdateChoicesWhen No Update the choices of this control based on another control’s value
required boolean No A boolean to specify whether the control is required. Default is true.
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
infoButton boolean No A boolean to set whether an information button is generated. The button has an ‘info’ icon and is placed to the right of the label. The default is false.

ColorChoiceConfig

Name Type Required Description
kind "Color" Yes
label string Yes
value string Yes
color List<number> Yes

SelectImageControlConfig

Name Type Required Description
kind "SelectImage" Yes Select is used to select an item from a list of items
choices List<ImageChoiceConfig> Yes A list of choices to select
value string No Optionally define the start value of the control
label string No Text displayed above the control
numberOfColumns number No Optionally set the number of equal sized numberOfColumns in which the selection items are displayed, default is 3
height number No Optionally define the height of the selection grid, default is 300
itemHeight number No Optionally set the heigh of each item in the grid, default is 50
disableWhen DisableWhenConfig No A boolean to disable this control based on another control’s value
hideWhen HideWhenConfig No A boolean to hide this control based on another control’s value
updateChoicesWhen UpdateChoicesWhen No Update the choices of this control based on another control’s value
required boolean No A boolean to specify whether the control is required. Default is true.
hidden boolean No A boolean to specify whether the hidden is disabled. Default is false.
disabled boolean No A boolean to specify whether the control is disabled. Default is false.
infoButton boolean No A boolean to set whether an information button is generated. The button has an ‘info’ icon and is placed to the right of the label. The default is false.

ImageChoiceConfig

Name Type Required Description
kind "Image" Yes
label string Yes
value string Yes
imagePath string Yes

UpdateChoicesWhen

Name Type Required Description
kind "Match" Yes Match is used to match the control value with the provided choices
control string Yes The control name to match a choice against its value
matchValues List<{ value: undefined, choices: undefined }> Yes The list of values to be matched with
Name Type Required Description
label string Yes
value boolean | string | number Yes

ControlPanelSubscribe

ControlPanelModelSubscribe

An object for configuring a subscription from a ControlPanel block to a Model block. The subscription supports multiple behaviors depending on which properties are set. Setting the setOutputs property allows Text elements and Table elements in the control panel to have their contents set based on data generated by the Grasshopper model. Setting the disableControls property to true disables the control panel and shows a progress bar while the Grasshopper model solves.

Name Type Required Description
kind "Model" Yes A constant, Model.
frame string Yes A string specifying the name of the frame in which the Model is located.
source string Yes A string specifying the name of the Model.
setOutputs Dictionary<string, SetOutput> No A dictionary for configuring elements in the control panel to be updated based on outputs from the Grasshopper model. The dictionary keys are strings that specify a name of both an element in the control panel and a Packhunt output component in the Grasshopper model. The dictionary values are objects with a type property for configuring the type of element to be updated. - If it is a Text element, then the type property should setText. The Grasshopper model is then expected to output a string. - If it is a Table element, then the type property should be setTable. The Grasshopper model is then expected to output a list of JSON objects containing name-value pairs that match the table structure.
disableControls boolean No A boolean to set whether to disable the controls while model is solving. The default is true

SetOutput

SetTextOutput
Name Type Required Description
type "setText" Yes
SetTableOutput
Name Type Required Description
type "setTable" Yes

ControlPanelDataStoreSubscribe

An object for configuring a subscription from a ControlPanel block to a DataStore block. The subscription allows the control panel to be updated based on the name-value pairs in the data store.

Name Type Required Description
kind "DataStore" Yes A constant, DataStore.
frame string Yes A string specifying the name of the frame in which the DataStore is located.
source string Yes A string specifying the name of the DataStore.

ControlPanelEntityDataStoreSubscribe

An object for configuring a subscription from a ControlPanel block to a EntityDataStore block. The subscription allows the control panel to be updated based on the data in the entity data store.

Name Type Required Description
kind "EntityDataStore" Yes A constant, EntityDataStore.
frame string Yes A string specifying the name of the frame in which the EntityDataStore is located.
source string Yes A string specifying the name of the EntityDataStore.
setControls Dictionary<string, ControlSetter> No A dictionary for configuring elements in the control panel to be updated based on data in the entity data store. The dictionary keys are strings that specify the name of both an element in the control panel and a property in the entity data store. The dictionary values are objects for configuring the element to be updated.

ControlSetter

SetSelectionChoices

An object for configuring the updating of selection choices in a SelectColor or SelectImage element in a control panel based on the data in an entity data store.

Name Type Required Description
type "setSelectionChoices" Yes A constant, setSelectionChoices.
imageProperty string Yes A string specifying the name of the property in the entity data store to use for setting the choice image path.
labelProperty string No A string specifying the name of the property in the entity data store to use for setting the choice label.
filterChoices List<string> No A list of strings specifying names to be used for filtering entities in the entity data store. Each name in the list specifies both a property name in the entity data store and an element name in the control panel. A list of choices is created by iterating through each entity in the entity datastore and each name in the list of names. For each entity, if the value of any named property is not equal to the value of the matching named element, then it is discarded. Whatever entities remain are then used to set the choices of the element in the control panel.
SetDropDownChoices

An object for configuring the updating of dropdown choices in a DropDown element in a control panel based on the data in an entity data store.

Name Type Required Description
type "setDropDownChoices" Yes A constant, setDropDownChoices.
labelProperty string No A string specifying the name of the property in the entity data store to use for setting the choice label.
filterChoices List<string> No A list of strings specifying names to be used for filtering entities in the entity data store. Each name in the list specifies both a property name in the entity data store and an element name in the control panel. A list of choices is created by iterating through each entity in the entity datastore and each name in the list of names. For each entity, if the value of any named property is not equal to the value of the matching named element, then it is discarded. Whatever entities remain are then used to set the choices of the element in the control panel.
SetNumberValue

An object for configuring the updating of a number value in a NumberInput or Slider element in a control panel based on the data in an entity data store.

Name Type Required Description
type "setNumberValue" Yes A constant, setNumberValue.
filterBy List<string> No A list of strings specifying names to be used for filtering entities in the entity data store. Each name in the list specifies both a property name in the entity data store and an element name in the control panel. For each entity, if the value of any named property is not equal to the value of the matching named element, then it is discarded. If the filtering process results in a single entity, then the number value of the element in the control panel will be updated. If on the other hand the filtering results in multiple entities, then no update is made.
valueProperty string No A string specifying the property name in the entity data store to be used for setting the number value of the element in the control panel.
SetTextValue

An object for configuring the updating of a text value in a TextInput element in a control panel based on the data in an entity data store.

Name Type Required Description
type "setTextValue" Yes A constant, setTextValue.
filterBy List<string> No A list of strings specifying names to be used for filtering entities in the entity data store. Each name in the list specifies both a property name in the entity data store and an element name in the control panel. For each entity, if the value of any named property is not equal to the value of the matching named element, then it is discarded. If the filtering process results in a single entity, then the text value of the element in the control panel will be updated. If on the other hand the filtering results in multiple entities, then no update is made.
valueProperty string No A string specifying the property name in the entity data store to be used for setting the text value of the element in the control panel.
SetMinMax

An object for configuring the updating of minimum and maximum range limits in a NumberInput or Slider element in a control panel based on the data in an entity data store.

Name Type Required Description
type "setMinMax" Yes A constant, setMinMax.
minProperty string Yes A string specifying the property name in the entity data store to be used for setting the minimum range limit of the element in the control panel.
maxProperty string Yes A string specifying the property name in the entity data store to be used for setting the maximum range limit of the element in the control panel.
filterBy List<string> No A list of strings specifying names to be used for filtering entities in the entity data store. Each name in the list specifies both a property name in the entity data store and an element name in the control panel. For each entity, if the value of any named property is not equal to the value of the matching named element, then it is discarded. If the filtering process results in a single entity, then the minimum and maximum range limits of the element in the control panel will be updated. If on the other hand the filtering results in multiple entities, then no update is made.
SetVisibility

An object for configuring the updating of the visibility of an element in a control panel based on the data in an entity data store.

Name Type Required Description
type "setVisibility" Yes A constant, setVisibility.
filterBy List<string> Yes A list of strings specifying names to be used for filtering entities in the entity data store. Each name in the list specifies both a property name in the entity data store and an element name in the control panel. For each entity, if the value of any named property is not equal to the value of the matching named element, then it is discarded. If the filtering process results in a single entity, then the visibility of the element in the control panel will be updated. If on the other hand the filtering results in multiple entities, then no update is made.