Skip to main content

​
Widget Core Function

UI Experience: Toggle true/false interface for the user
Data Organization: Provides users with exactly two choices to select from, storing the selected data for use in other widgets.

​
Key Features

  • Simple binary choice interface (Yes/No, True/False, On/Off)
  • Clean, intuitive user experience for boolean decisions
  • Stores selection as index (0 or 1) for use in calculations
  • Supports custom labels for both toggle states

​
Video Tutorial

Create a Toggle

Watch Tutorial Learn how to create and configure toggle widgets step by step

​
Visual Presentation

Toggle widget interface in pause mode

​
Configuration

​
Example Code

{
  "type": "sheetTemplateWidgets",
  "attributes": {
    "type": "lookup",
    "label": "Seismic Analysis Required",
    "symbol": "SW_{flag}",
    "defaultValue": "0",
    "visibleIf": "",
    "enableAutosize": false,
    "radioListDisplay": true,
    "dataColumns": [
      {
        "label": "Option",
        "key": "option",
        "type": "string"
      }
    ],
    "dataTable": [
      ["No"],
      ["Yes"]
    ],
    "referenceId": "seismic_analysis_toggle",
    "references": "AS 1170.4",
    "description": "Specify if seismic analysis is required",
    "authorNotes": "Toggle for enabling seismic analysis calculations",
    "referenceImage": ""
  }
}

​
Configuration Parameters

​
type
string
required
Set to “lookup” to define the widget type
​
radioListDisplay
boolean
required
Set to true for toggle widgets to display as radio buttons instead of dropdown
​
dataColumns
array
required
Simple array with one column definition for the toggle options
​
dataTable
matrix
required
Two-row matrix with the toggle options. Typically [“No”] and [“Yes”] or [“False”] and [“True”]
​
enableAutosize
boolean
default:"false"
Should be set to false for toggle widgets as autosize is not applicable

​
Common Toggle Patterns

​
Yes/No Toggle

"dataTable": [
  ["No"],
  ["Yes"]
]

​
True/False Toggle

"dataTable": [
  ["False"],
  ["True"]
]

​
On/Off Toggle

"dataTable": [
  ["Off"],
  ["On"]
]

​
Custom Labels

"dataTable": [
  ["Not Required"],
  ["Required"]
]

​
Examples from Current Calculators

Reference IDCalculator Link
lookup (SW_flag)Steel Beam Calculator

​
Usage in Calculations

Toggle widgets return index values (0 or 1) that can be used in boolean logic:

​
Conditional Logic Examples

// Direct boolean check
if (@seismic_analysis_toggle == 1) {
  // Seismic analysis is required
  seismic_factor = 1.0
} else {
  // No seismic analysis
  seismic_factor = 0.0
}

// Using in equation widgets
seismic_load = @base_load * (@seismic_analysis_toggle == 1 ? @seismic_factor : 0)

​
Visibility Control

// Show/hide widgets based on toggle state
"visibleIf": "@seismic_analysis_toggle == 1"

​
Best Practices

  1. Clear Labels: Use descriptive labels that make the choice obvious to users
    • Good: “Yes” / “No”
    • Good: “Required” / “Not Required”
    • Avoid: “True” / “False” (less user-friendly)
  2. Default Values:
    • Set defaultValue: "0" for the safer/more conservative option
    • Consider which choice users will select most often
  3. Boolean Logic: Remember that toggles return indices (0, 1), not boolean values
    • Use == 1 for “true” checks
    • Use == 0 for “false” checks
  4. Conditional Visibility: Use toggles to control visibility of related widgets 
    "visibleIf": "@my_toggle == 1"
  5. Documentation: Include clear author notes explaining what each toggle state represents

​
Integration Patterns

​
Controlling Widget Visibility

{
  "type": "input",
  "attributes": {
    "label": "Seismic Load Factor",
    "visibleIf": "@seismic_analysis_toggle == 1",
    "referenceId": "seismic_factor"
  }
}

​
Conditional Calculations

{
  "type": "computed",
  "attributes": {
    "label": "Total Load",
    "equation": [
      {
        "condition": "@seismic_analysis_toggle == 1",
        "result": "@dead_load + @live_load + @seismic_load"
      },
      {
        "condition": "@default",
        "result": "@dead_load + @live_load"
      }
    ],
    "referenceId": "total_load"
  }
}

​
Troubleshooting

Common Issues:
  • Forgetting to set radioListDisplay: true (widget will appear as dropdown instead of toggle)
  • Using boolean values instead of string arrays in dataTable
  • Comparing toggle values as booleans instead of indices (0, 1)
Remember: Toggle widgets are implemented as lookup widgets with exactly two options and radio button display enabled. This provides the clean toggle interface while maintaining the flexibility of the lookup widget system.
⌘I