Skip to main content
This page contains frequently asked questions and common issues encountered when working with widgets in the ClearCalcs template builder.

​
General Widget Questions

The computed portion of the calculator doesn’t support mixed data types in a single result. However, you can work around this limitation using a two-widget approach:
  1. Primary Equation Widget: Performs the numerical calculation
  2. Secondary Text Widget: Combines the computation output with text using the print() function
The secondary widget can be toggled to be invisible using the visibleIf property with conditional statements.Example Implementation:
// Primary computation widget
{
  "type": "computed",
  "referenceId": "beam_capacity",
  "equation": [
    {
      "condition": "@default",
      "result": "@moment_strength * @safety_factor"
    }
  ],
  "hidden": true
}

// Secondary text display widget
{
  "type": "computed", 
  "referenceId": "capacity_display",
  "equation": [
    {
      "condition": "@default",
      "result": "print('Beam capacity: ', @beam_capacity, ' kN·m')"
    }
  ],
  "visibleIf": "@beam_capacity > 0"
}
The method depends on the type of lookup widget:Data Table Lookups:
// Get selected row index
selectedIndex = @my_lookup

// Access specific column data
columnValue = dataTableValue(@my_lookup, selectedIndex, columnIndex)
Shared Table Lookups:
// Direct column access using column reference ID
columnValue = @my_lookup.columnReferenceId
Toggle Lookups:
// Toggle returns 0 or 1
isEnabled = (@my_toggle == 1)
These properties control widget visibility in different ways:hidden Property:
  • Static visibility control set at design time
  • When true, widget is never shown to users
  • Value can still be set in presets and referenced by other widgets
  • Useful for intermediate calculations or data storage
visibleIf Property:
  • Dynamic visibility control based on conditions
  • Evaluated in real-time based on other widget values
  • When condition is false, widget is hidden and cannot be referenced
  • Useful for conditional user interface flows
// Static hidden widget
{
  "hidden": true,
  "referenceId": "internal_calc"
}

// Conditionally visible widget  
{
  "visibleIf": "@load_type == 1",
  "referenceId": "wind_load_factor"
}
Break complex calculations into multiple equation widgets:
  1. Intermediate calculations can be hidden from users
  2. Final results can reference intermediate steps
  3. Display widgets can format and present results
// Step 1: Hidden intermediate calculation
{
  "type": "computed",
  "referenceId": "moment_demand", 
  "hidden": true,
  "equation": [{"condition": "@default", "result": "@load * @span^2 / 8"}]
}

// Step 2: Hidden intermediate calculation  
{
  "type": "computed",
  "referenceId": "moment_capacity",
  "hidden": true, 
  "equation": [{"condition": "@default", "result": "@section_modulus * @yield_stress"}]
}

// Step 3: Final visible result
{
  "type": "computed",
  "referenceId": "utilization_ratio",
  "equation": [{"condition": "@default", "result": "@moment_demand / @moment_capacity"}]
}
ClearCalcs has built-in unit handling:
  • Input widgets automatically handle unit conversion
  • Equation widgets inherit units from inputs
  • Unit-aware functions maintain dimensional consistency
Best Practices:
  • Define units in input widget unit property
  • Use consistent base units throughout calculations
  • Let the system handle conversions automatically
  • Check the “What’s NOT unit-aware” documentation for exceptions
Yes, using the check functionality in equation widgets:
{
  "type": "computed",
  "referenceId": "beam_check",
  "equation": [
    {
      "condition": "@utilization_ratio <= 1.0",
      "result": "PASS"
    },
    {
      "condition": "@default", 
      "result": "FAIL"
    }
  ],
  "check": {
    "condition": "@utilization_ratio <= 1.0",
    "pass": "Beam capacity is adequate",
    "fail": "Beam is overstressed - increase section size"
  }
}

​
Widget-Specific Questions

Use Data Table when:
  • Data is simple and can be defined in the builder
  • Limited number of options (typically < 50 rows)
  • Data doesn’t change frequently
  • No external data source maintenance required
Use Shared Table when:
  • Data is complex or extensive (> 50 rows)
  • Data is maintained in Excel externally
  • Multiple templates need the same data
  • Advanced filtering capabilities are needed
  • Data includes multiple related columns
Use the visibleIf property and data filtering:
// Primary lookup
{
  "type": "lookup",
  "referenceId": "material_type",
  "dataTable": [["Steel"], ["Concrete"], ["Timber"]]
}

// Dependent lookup - only visible for steel
{
  "type": "lookup", 
  "referenceId": "steel_grade",
  "visibleIf": "@material_type == 0",
  "dataTable": [["Grade 300"], ["Grade 350"], ["Grade 400"]]
}
For dynamic numbers of similar widgets, consider:
  1. Subsheet Widgets for complex linked calculations
  2. Table Widgets for simple data entry arrays
  3. Loop-based equation widgets for calculations over arrays
See the Subsheet Widget documentation for advanced scenarios.

​
Troubleshooting

Common issues and solutions:Check Reference IDs:
  • Ensure referenceId is unique across the template
  • Verify spelling in widget references (case-sensitive)
  • Use valid JavaScript identifier format (no spaces, special chars)
Check Visibility:
  • If visibleIf is false, widget cannot be referenced
  • Ensure referenced widgets exist and are visible
Check Data Types:
  • Ensure data types match expected input types
  • Verify lookup indices are within valid range
Causes:
  • Widget A references Widget B, and Widget B references Widget A
  • Subsheet commonInputs that depend on derived data
Solutions:
  • Identify the dependency chain
  • Break circular dependencies with intermediate widgets
  • Use hidden widgets for one-way data flow
  • Review subsheet commonInput configurations
Optimization strategies:
  • Use Shared Tables instead of large Data Tables
  • Implement data filtering to reduce displayed options
  • Consider breaking large calculations into smaller steps
  • Use hidden: true for intermediate calculations
  • Minimize complex visibleIf conditions on frequently updated widgets

​
Getting Help

If you encounter issues not covered in this FAQ:
  1. Check the specific widget documentation for detailed configuration options
  2. Review existing templates with similar functionality
  3. Test in isolation by creating a minimal example
  4. Contact the development team with specific error messages and widget configurations
This FAQ is regularly updated based on common questions from template developers. If you have suggestions for additional topics, please reach out to the development team.
⌘I